Troubleshooting

Common issues and fixes for the MCP Gateway. If your issue isn't listed here, check the vendor health dashboard for upstream outages.

"Invalid OAuth error response: Unexpected token '<'"

This error means the OAuth discovery or token endpoint returned HTML instead of JSON — typically a Cloudflare error page (404, 502, or 520) rather than the gateway's response.

Causes

The gateway is being deployed (brief downtime during container restart)
A vendor MCP container is down and Cloudflare is returning its default error page
DNS or routing misconfiguration

Fix

Wait 1–2 minutes and try again (deployments typically complete within 60 seconds)
Check /health — if it returns {"status":"ok"}, the gateway is running
Check /health/vendors to see if a specific vendor is down
If the issue persists, restart Claude Desktop and try again

"Connection refused" on OAuth callback

During OAuth, mcp-remote opens a temporary local HTTP server (e.g., localhost:26873) to receive the OAuth callback. If too many OAuth flows run simultaneously, the listener can time out before the browser redirects back — resulting in "connection refused" on the callback URL.

Causes

Multiple per-vendor entries — each vendor triggers its own OAuth flow on startup; with 5+ vendors, the listeners race and time out
The browser took too long to complete the OAuth flow (manual login, 2FA, etc.)
A firewall or antivirus is blocking localhost connections

Fix

Use the unified endpoint — replace all per-vendor mcp-remote entries with a single entry pointing to https://mcp.wyretechnology.com/v1/mcp. This means one OAuth flow instead of many. See the Gateway setup guide.
If using per-vendor endpoints, add them one at a time — connect one vendor, restart Claude Desktop, then add the next
Kill any stale mcp-remote processes: pkill -f mcp-remote
Restart Claude Desktop

"Failed to reconnect" / stale sessions

After a gateway deployment or container restart, existing MCP sessions become invalid. The mcp-remote bridge may show "failed to reconnect" errors or hang indefinitely.

Fix

Kill all mcp-remote processes:
```
pkill -f mcp-remote
```
Restart Claude Desktop (or restart Claude Code's MCP connection with /mcp)
The client will establish a fresh session with the gateway on the next request

This is expected after deployments. The gateway deploys new revisions with zero-downtime traffic switching, but mcp-remote's persistent connections don't automatically reconnect to the new revision.

Vendor shows DOWN on /health/vendors

The /health/vendors endpoint monitors all vendor MCP containers. If a vendor shows "status": "down", the underlying vendor container is unreachable.

Causes

The vendor's MCP container is restarting after a deployment
The vendor's upstream API is experiencing an outage
A container crashed and is being restarted by the orchestrator

Fix

Wait 2–5 minutes — containers typically auto-recover
Check the consecutiveFailures count in the health response — if it's climbing, the issue is ongoing
Other vendors on the unified endpoint continue to work normally — only the affected vendor's tools will be unavailable

Connected vendor's tools don't appear

If you've added credentials for a vendor but its tools don't show up in Claude:

Verify your credentials are saved at mcp.wyretechnology.com — log in and check the credentials page
Restart Claude Desktop or re-establish the MCP connection in Claude Code (/mcp)
The unified endpoint only lists tools for vendors where you have valid credentials — if credentials are expired or invalid, that vendor is silently skipped
If using org/team credentials, ensure you have the correct role and the vendor's tools are in your team's allowlist