Postal DevelopersTroubleshooting
Common connection and permission problems.
"The API key is missing a required scope"
The key you connected with does not carry the scope the tool needs. Check the tool reference for the scope, then create a key with that scope in Postal and reconnect. Note the composer tools use two different read scopes; see Auth and scopes.
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.