MCP Troubleshooting

Client can't connect

"Server unreachable" — confirm https://mcp.subscriby.net is reachable from the client (open it in a browser; you should see an MCP protocol handshake description, not a 404).
TLS errors — update the client. Claude Desktop < 1.11 and Cursor < 0.46 don't negotiate modern MCP streaming HTTP correctly.
Proxy in the way — corporate proxies sometimes strip the Authorization header. Test over a direct network first.

The server URL must be exactly https://mcp.subscriby.net. A trailing slash or a path makes the client compare it to the address the server publishes and refuse the connection before you see a sign-in page.
You landed on the Subscriby sign-in page instead of the consent screen: sign in (two-factor and passkeys apply), and the client retries the authorization on its own.
The consent screen appeared but the client still says it is not connected: press Authorize on it; Cancel sends the client an error and it stays disconnected.
Corporate proxies that rewrite or block https://app.subscriby.net/.well-known/… break discovery. Test over a direct network first.

Tool list is empty

With a personal access token: the token is missing the ability the tool enforces. Check the tools reference for which one, and mint a token that carries it.
Client config JSON invalid. Validate with jq or similar.
Restart required after editing config. MCP servers load at client launch; hot reload isn't a thing in MCP-1.

With a personal access token the error envelope includes required_ability. Mint a new token with that ability added, replace the old one in the client config, restart the client. An OAuth connection carries every ability your role grants, so a 403 there means your team role lacks the permission itself.

Specific tool returns 404

Tenant mismatch — the token's scope:team: does not include the project/plan/subscriber you referenced.
Entity does not exist. Double-check the ID or handle.

Tool call times out

Long-running operations (batch access-code generation) return a job_id immediately and must be polled via get_job_status rather than waited on in the initial request. See async jobs.
Short tool calls that still time out usually indicate a transient backend slowdown; retry after a brief backoff.

Rate limited (429)

The mcp bucket is 120/min per token for authenticated calls. Claude Desktop and Cursor pace tool calls internally, so hitting it usually means a tight loop.
Unauthenticated traffic on the MCP host is bucketed separately at 5/min per IP. If a client is hitting RATE_LIMITED after only a handful of attempts, the token is missing or malformed — fix the Authorization header before retrying.
The Retry-After header tells you how long to wait. Honour it.

Agent loops asking for confirmation

The client is auto-denying write tools. Toggle auto-approve for the subscriby namespace in the client's settings.
If you want confirmation on every write, that's the default — the server doesn't control client-side confirmations.

"Session expired" or 401 after hours of chat

An OAuth access token lasts an hour and the client renews it silently. If it stopped renewing (the refresh token was discarded, or 30 days passed with no use), disconnect and connect again inside the client.
Personal access tokens don't expire mid-session unless you revoked them.
The session-level timeout inside some clients caps at a few hours for safety — reconnect.