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.

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
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`