Troubleshooting Matrix
Use this matrix for Cursor, Claude, and ChatGPT MCP troubleshooting against Zerq.
| Symptom | Likely cause | Where to verify | Fix |
|---|---|---|---|
401 on initialize | Missing/invalid bearer token | Gateway logs, auth provider token validity | Refresh token and retry |
Immediate connect failure before initialize | Wrong MCP server URL or transport setting | Client config JSON/UI fields | Use /mcp (gateway) or /api/v1/mcp (management) with streamableHttp |
400 after successful initialize | Missing/invalid Mcp-Session-Id on follow-up call | Client request headers | Reuse session header returned by initialize |
403 on tools/call | Tool/action outside role/policy scope | Management RBAC config, client/profile permissions | Grant minimal required scope or use dedicated profile |
405 from gateway MCP | Wrong method/routing to MCP endpoint | Client request method + endpoint URL | Use supported MCP transport methods and correct path |
429 responses | Policy/rate limit exceeded | Policy assignment, request logs | Backoff with jitter and tune policy limits |
| Empty/partial tool list | Wrong auth identity or wrong surface endpoint | tools/list response, endpoint URL | Validate gateway vs management endpoint selection |
Management MCP returns 401 with valid gateway token | Wrong token type for management surface | OIDC issuer/audience and token claims | Use OIDC access token for /api/v1/mcp |
Gateway MCP denies with 403 despite valid token | Missing or wrong X-Client-ID / X-Profile-ID | MCP headers in client config | Set profile-bound headers correctly in gateway MCP entry |
| Works in staging, fails in prod | Different profile, policy, or OIDC issuer config | Environment vars and deployment config | Align env settings and rotate credentials if needed |
Debug sequence
- Confirm endpoint path (
/mcpvs/api/v1/mcp). - Validate bearer token for the intended surface.
- Re-run
initializeand record new session ID. - Run
tools/listwith same session. - Run one expected
tools/calland one intentionally disallowed call.
Evidence to collect
- Request ID and timestamp
- Full MCP JSON-RPC request/response payloads
- Response headers (especially
Mcp-Session-Id) - Matching request/audit log entries in Zerq