Errors

ON THIS PAGE

MCP returns structured errors so hosts and agents can recover. Prefer the recovery hint on the error result when present. Agents can also read opensolar://docs/errors.

The tables below are a non-exhaustive list. Ask the agent or read opensolar://docs/errors for the current set of codes.

Common MCP codes

Code	Typical HTTP	When	What to do
MCP_0002	403	Token lacks the required scope	Re-consent with WRITE or DELETE as needed
MCP_0004	403	Tool org_id does not match the token org	Use the token organisation; do not pass a different org_id
MCP_0006	≥400 (upstream)	OpenSolar API returned an error	Inspect included error / detail; fix the request payload
MCP_0008	403	Tool is not on the allowlist / denied	Use a published tool from Tools
MCP_0011	402	Org missing Raw Data API Access for an API-backed tool	Enable Raw Data API Access
MCP_0012	429	Daily or burst quota exceeded	Wait for Retry-After / window reset; see MCP Limits

Access and policy codes

Code / signal	When	What to do
MCP_ACCESS_0001 / introspect mcp_access_required	Organisation missing MCP Access	Enable MCP Access
Introspect mcp_role_denied	User role lacks MCP Access (view) permission	Grant the role permission

HTTP expectations

Situation	Response
Unauthenticated POST /mcp	401 + WWW-Authenticate with resource_metadata
Rate limited tool call	429 + MCP_0012
Successful tool error	Tool result / error with MCP code (not always a transport failure)

Recovery tips for agents

1. On MCP_0011, tell the user to enable Raw Data API Access — do not retry in a loop.
2. On MCP_0002, stop and request re-authentication with broader scopes.
3. On MCP_0012, back off using Retry-After or the daily reset time.
4. On MCP_0006, surface the upstream API message; many cases are validation errors on fields.