Troubleshooting

401 Missing authentication token

The endpoint did not see a valid JWT or OAuth bearer token. Response includes:

WWW-Authenticate: Bearer realm="mcp",
  resource_metadata="https://<api>/.well-known/oauth-protected-resource"

Claude.ai uses this header to start OAuth discovery — there is nothing to fix server-side. If you're testing with curl, send Authorization: Bearer <token>.

403 Feature not included in plan: mcp.access

Your account is on Free. Upgrade to Bitter or higher.

403 Tool 'update_agent' requires mcp.tools.write (not in plan)

update_agent is the one tool gated behind mcp.tools.write, which starts at Chainer. Every other tool consumes mcp.tools.read.

403 Feature not included in plan: mcp.oauth_client.manage

OAuth client creation requires Chainer or higher. Use an existing client or upgrade.

429 Rate limit exceeded for mcp.access

You hit the per-minute endpoint budget. The response includes:

• Retry-After: <seconds>
• X-RateLimit-Limit: <budget>

Back off and retry. If you regularly hit it, upgrade — Architect has 10× the budget of Bitter.

429 Rate limit exceeded for mcp.tools.read

You burned the per-hour read budget. Slow your tools/call cadence or wait an hour.

OAuth /authorize redirects to login but never comes back

The login page must redirect back to /api/v1/mcp/oauth/authorize?... with the original query string intact. If you see your web app dropping the redirect query param, that's a web-app config bug, not an MCP issue.

A tool name returns "unknown tool"

Some tools exist in the server but are not surfaced, and calling one by name fails. Check the Tools Reference — the tools that are wired but not yet enabled are listed at the end of that page. list_connector_instances and execute_connector_tool in particular are not served; use connectors_list and connectors_get.