MCP Troubleshooting

Client can't connect

"Server unreachable" — confirm https://mcp.memberpass.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.

Tool list is empty

Token missing mcp:full. Mint a new token with it ticked.
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.

Specific tool returns 403

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.

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 memberpass 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" after hours of chat

Tokens don't expire mid-session unless you set a short lifetime or revoked them.
The session-level timeout inside some clients caps at a few hours for safety — reconnect.

MCP Troubleshooting

On this page