Connect a client

You need a Postal account and an API key. Keys are created in Settings → Integrations in the Postal app. See API keys for scopes and rotation.

The server speaks Streamable HTTP at https://mcp.postal.music/mcp. Clients that support remote servers connect to that URL directly. Clients that only launch local stdio servers can bridge through mcp-remote (last section).

Claude (web, desktop and mobile)

Claude connects through a custom connector. This is the recommended path and the one we support first.

Tokens last one hour and refresh automatically for 30 days. Revoking the API key in Postal disconnects the connector immediately.

Claude Code

claude mcp add --transport http postal https://mcp.postal.music/mcp

The first tool call opens the same authorisation page in your browser. To skip the browser flow, pass the key as a header instead:

claude mcp add --transport http postal https://mcp.postal.music/mcp \
  --header "X-API-Key: YOUR_API_KEY"

Cursor

Add the server to .cursor/mcp.json in your project, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "postal": {
      "url": "https://mcp.postal.music/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Omit headers to use the OAuth flow instead; Cursor will prompt you to authorise on first use.

Any other client

For clients with native remote-server support, use the URL above with either OAuth or an X-API-Key header. Both X-API-Key: <key> and Authorization: Bearer <key> are accepted.

For stdio-only clients (older Claude Desktop builds, some IDE plugins), bridge through mcp-remote:

{
  "mcpServers": {
    "postal": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.postal.music/mcp",
        "--header",
        "X-API-Key:${POSTAL_API_KEY}"
      ],
      "env": { "POSTAL_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Verify the connection

Ask the assistant to call get_track_count. A working connection returns a number in under a second. If you get a scope error, see Auth and scopes.

You can also check the server itself without credentials:

curl https://mcp.postal.music/health
curl https://mcp.postal.music/tools   # full tool catalog with JSON schemas