MCP troubleshooting
Resolve connection, OAuth, cached-tool, permission, confirmation, retry, readiness, upload, and rate-limit problems safely.
On this page
Common problems
| Problem | Likely cause | What to do |
|---|---|---|
| The setup prompt did not connect RouteKite | The client still requires server configuration or consent | Follow Client setup, complete OAuth, enable RouteKite in the conversation, and verify with a workspace read |
| RouteKite does not connect | The client cannot reach the remote endpoint or complete OAuth | Use the exact server URL, allow the browser sign-in, then reconnect |
| Only 20 tools appear | The client cached an older manifest | Remove and reconnect RouteKite or use the client's refresh-tools action |
| A tool is missing | The connection is Read-only or the client disabled the tool | Review the access level and enabled tools before requesting broader access |
| Missing scope | The managed or local credential cannot perform the operation | Reconnect with Manage only when the workflow truly needs it |
| confirmation_required | RouteKite returned a preview | Review the summary and explicitly approve that exact action |
| Idempotency conflict | The same key was reused with different input | Use the original input or a new key for a genuinely new operation |
| Sending is blocked | Readiness, consent, suppression, template, campaign, or funded-capacity checks failed | Read the returned blocker and correct it in RouteKite |
| Attachment is not ready | The upload was not completed or validation failed | Upload the exact bytes, then run the completion tool |
| Request timed out | The operation exceeded the client's wait window | Read current state before retrying; do not assume it failed |
| Rate limit reached | The client called tools too frequently | Wait for the retry window and reduce polling |
| Generic error | An internal failure was safely redacted | Retry one safe read, then contact support with the request ID |
Diagnose in this order
- 1
Confirm the endpoint
Use https://routekite.com/mcp and confirm the client supports remote Streamable HTTP.
- 2
Confirm authorization
Complete OAuth and verify the approved workspace and access level.
- 3
Refresh tools
Reconnect when the client shows an old or incomplete manifest.
- 4
Run a bounded read
Check readiness or list domains before attempting another change.
- 5
Match permission
Compare the tool with the Available tools page before granting Manage access.
- 6
Preserve evidence
Keep the customer-safe error code and request ID for support.
Recover without duplicates
Reads can be retried after a transient failure. For operations with idempotency_key, reuse the same key only with the exact same input.
After a timeout on a configuration, template, attachment, or webhook change, read the current object before retrying because those endpoints do not all guarantee deduplication.
Inspect the connection in RouteKite
Open Developers, then MCP Connections, to see access level, status, last use, and recent tool activity. Revoke the connection and authorize it again if the grant or cached manifest cannot be recovered safely.