MCP
Troubleshooting
Diagnose Andy MCP HTTP and JSON-RPC failures including -32001, -32002, 401, and scope errors.
Outcome
Classify a failed MCP handshake or tool call and apply the matching fix from the canonical install story.
Failure table
| Symptom | Likely cause | Fix |
|---|---|---|
HTTP 401 + WWW-Authenticate, JSON-RPC -32001 | Missing/invalid Bearer token, or env interpolation did not expand (literal ${env:…} sent) | Check the key; confirm the client expands env vars in headers |
HTTP 400/404, JSON-RPC -32002 | Missing or mismatched Mcp-Session-Id | Complete initialize first; extract Mcp-Session-Id from the response headers; send it on every subsequent request |
Tool problem: workspace_selection_required | OAuth user has multiple Workspaces and none is selected, or the previous selection went stale (context.reason) | Replay one of the ready calls in remediation.calls as-is: tools/call with its mcpToolName and input; the labels are Workspace names |
Tool problem: agent_selection_required | A write that acts on exactly one Agent could not resolve one: the Workspace has several Agents, the Conversation/Knowledge resource named none uniquely, or the write is an Agent deletion (context.reason) | Replay one of the ready calls in remediation.calls: each is a { "agentId": … } patch (mode: "merge_and_retry") to merge into the arguments you already sent; the labels are Agent names |
HTTP 403, JSON-RPC -32003 | Disallowed Origin | Call from an allowed origin, or omit Origin for server-to-server probes |
| Tool error: "The selected Workspace does not currently include MCP access" | Workspace lacks MCP entitlement | Upgrade / enable MCP on the Workspace |
| "API Access requires Pro Max" when creating a key | Plan gate | Upgrade to Pro Max |
| Older Codex cannot reach streamable HTTP | Pre-0.147 without rmcp feature flag | Upgrade to codex-cli ≥ 0.147, or enable [features].rmcp_client = true |
Related
- Auth and scopes
- Generic JSON probe
- Product troubleshooting: Troubleshooting and Upgrading