Troubleshooting

For the complete troubleshooting guide, see TROUBLESHOOTING.md on GitHub.

Common Errors

Error -32000: Connection Closed

Most common cause: console.log polluting stdout.

Fix: Replace console.log with console.error in your backend.

Error 401: Unauthorized

• Verify your API key starts with mcp_ (legacy keys may start with mcp_sk_)
• Check the key hasn't been revoked or expired
• Ensure the Authorization header format: Authorization: Bearer YOUR_KEY

Error 429: Rate Limited

You've exceeded your tier's rate limit.

Fix: Wait for the Retry-After period, or upgrade your plan.

Tools Not Showing

Check backend health:

curl https://zephex.dev/health | jq .checks.backends

Slow Performance

1. Check /health for degraded backends
2. Test from a different network
3. Compare simple vs complex tool timing

Still Stuck?

Open an issue on GitHub