Postal DevelopersTroubleshooting
Common connection and permission problems.
The assistant does not have a tool I expected
The server lists only the tools the connected key's scopes allow, so a tool missing from the assistant's list means the key lacks its scope. Look the tool up in the tool reference, add that scope to the key (or create a key that has it) and reconnect. Note the composer tools use two different read scopes; see Auth and scopes.
"The API key is missing a required scope"
The API refused a call because the key does not carry the scope the tool needs. This can happen when the key's scopes were narrowed after the assistant loaded its tool list. Reconnect, or start a new conversation, and the list will match the key again.
A tool says the track (or playlist, composer, brief) was not found
A read on an ID that does not exist, or that belongs to another account,
answers error: "not_found" with a sentence naming the ID and the list tool
that returns valid ones (list_tracks, list_playlists, list_composers,
list_briefs). The two cases are deliberately indistinguishable. A mistyped
or stale ID is the usual cause; on a brand-new account every ID is unknown
until something has been uploaded. The assistant should look the entity up by
name with the list tool rather than retry the ID. See
Errors for the shape.
The connector asks me to authorise again
OAuth access tokens last one hour and refresh silently for 30 days. A new authorisation prompt after that window is expected. If it happens sooner, the API key was revoked or rotated in Postal, or the server's signing secret was rotated. Reconnect with a current key.
Search returns nothing useful
search_tracks ranks tracks that have finished audio analysis. Newly uploaded
tracks appear once analysis completes; call wait_for_auto_tag on them first.
Very restrictive hard filters (a narrow BPM window plus a key plus a language)
can also empty the result set. Loosen one at a time.
Search says I'm out of credits
search_tracks is credit-metered. Top up in Settings → Usage in the
Postal app, or use list_tracks for name and tag lookups, which are free.
A stdio-only client can't connect
The server is HTTP-only; there is no local process to run. Bridge with
mcp-remote as shown in Connect a client.
Check the server is up
curl https://mcp.postal.music/healthReturns the deployed version. If this fails, the problem is on our side; see status.postal.music or contact support.