MCP Troubleshooting

Client can't connectCopy Anchor Link

• "Server unreachable": confirm the server address is reachable from the client. Opening it in a browser answers a sign-in challenge, not a 404.
• TLS errors: update the client. Older releases of Claude Desktop and Cursor do not negotiate MCP streaming HTTP correctly.
• Proxy in the way: corporate proxies sometimes strip the Authorization header. Test over a direct network first.

Sign-in never finishesCopy Anchor Link

• The server URL must be exactly the address you were given. 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 Zuse Bifrost sign-in page instead of the consent screen: sign in (two-factor authentication 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 the application's /.well-known/… documents break discovery. Test over a direct network first.

Tool list is emptyCopy Anchor Link

• Client config JSON invalid. Validate with jq or similar.
• Restart required after editing config. MCP servers load at client launch.
• The tool list itself is the same for every credential; a token missing an ability still sees the tool and is refused when it calls it, with the ability named.

Specific tool is refusedCopy Anchor Link

With a personal access token the error envelope includes required_ability under error.context. 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 refusal there means your team role lacks the permission itself; ask the team owner to grant it.

Specific tool answers not foundCopy Anchor Link

• Tenant mismatch: the token's scope:team: or scope:project: does not include the project, team or endpoint you referenced. Out-of-scope data is reported as absent rather than forbidden, so existence does not leak.
• Entity does not exist. Double-check the id.

Tool call times outCopy Anchor Link

• Short tool calls that time out usually indicate a transient slowdown; retry after a brief backoff.
• A webhook test or a replay queues work rather than waiting for it: test_webhook_endpoint answers with the pending delivery, which get_webhook_delivery reads once the worker has posted it.

Rate limited (429)Copy Anchor Link

• Authenticated calls are limited to 120 a minute per token. Claude Desktop and Cursor pace tool calls internally, so hitting it usually means a tight loop.
• Unauthenticated traffic on the MCP endpoint is bucketed separately at 5 a minute per address. 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 confirmationCopy Anchor Link

• The client is auto-denying write tools. Toggle auto-approve for the zusegenius namespace in the client's settings.
• If you want confirmation on every write, that is the default; the server marks every tool that changes data as destructive and leaves the confirmation to the client.

"Session expired" or 401 after hours of chatCopy Anchor Link

• 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 do not expire mid-session unless you revoked them.
• The session-level timeout inside some clients caps at a few hours for safety; reconnect.

RelatedCopy Anchor Link

• MCP security
• Error envelope