Developers

Errors and limits

The MCP server reports problems as JSON-RPC errors or as tool results marked isError. The OAuth endpoints use standard OAuth error objects. This page lists each one and the limits behind them.

MCP HTTP statuses

Status	When
200	Every answered JSON-RPC request, including JSON-RPC errors and tool errors.
202	A notification (no id). No body.
400	The body is not valid JSON (-32700).
401	No token, or the token is not valid, expired, revoked, or its owner lost access (-32001).
405	GET or DELETE. Only POST is served.
413	The body is larger than 256 KB (-32600).

401 response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="production-engine", resource_metadata="https://production-engine.com/.well-known/oauth-protected-resource/api/mcp", error="invalid_token"

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "That token is not valid, expired, was revoked, or its owner is no longer a workspace owner or admin."
  }
}

error="invalid_token" is present only when a token was sent. Without one, the challenge still names the metadata so a client can start sign-in.

JSON-RPC errors

Code	Meaning	Examples
-32700	Parse error	Request body is not valid JSON.
-32600	Invalid request	Not a JSON-RPC 2.0 request, a batched array, or a body over 256 KB.
-32601	Method not found	Any method other than initialize, ping, tools/list and tools/call.
-32602	Invalid params	An unknown tool name, a missing required argument, or a value of the wrong type or range.
-32001	Unauthorized	See the 401 above.

Invalid params

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": { "code": -32602, "message": "limit must be a whole number from 1 to 100." }
}

Tool errors

When the arguments are valid but the tool cannot answer, the result has isError: true and one sentence in content. Read the sentence; it says what to change.

A record id that does not exist in this workspace: "No project with id ... in this workspace."
A shoot day that does not match: "That project has no shoot day matching that date or id."
Starting an estimate when the plan is not active, or the AI allowance is used up.
An unexpected server failure: "<tool> failed on the server. Try again." The details are logged on our side, not returned.

A bank feed or Saturation tool with no account connected is not an error. It returns connected: false and a message.

OAuth errors

Token endpoint error

HTTP/1.1 400 Bad Request

{
  "error": "invalid_grant",
  "error_description": "The authorization code expired."
}

error	Endpoint	When
`invalid_redirect_uri`	register	No redirect URIs, more than 10, or one that is not on the allowed list.
`invalid_client_metadata`	register	A grant type other than authorization_code or refresh_token, or a body over 16 KB.
`invalid_request`	token	A required field is missing, a field is repeated, or the body is over 16 KB.
`invalid_scope`	token	A scope other than read was sent to the token endpoint.
`unsupported_grant_type`	token	grant_type is not authorization_code or refresh_token.
`invalid_grant`	token	The code or refresh token is wrong, expired or already used, the PKCE verifier does not match, the token was issued for another resource, the approving person is no longer an owner or admin, or the plan is not active.

Errors on the approval page itself are shown to the person and never redirected. The one redirect with an error is error=access_denied, when the person declines.

Rate limits and size caps

Rate limits

Endpoint	Limit	Counted per
`POST /api/oauth/register`	300 requests per 1 hour	IP address
`POST /api/oauth/token`	30 requests per 15 minutes	Client id

Over the limit, the endpoint answers 429 with a Retry-After header in seconds. The MCP server has no per-token request quota today. start_estimate is bound by the workspace's AI allowance instead.

429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 900

{ "error": "Too many requests. Please try again later." }

Size caps

MCP request body: 256 KB.
OAuth register and token request bodies: 16 KB.
Lists: at most 100 rows per page. Summary tools cap their lists and mark them truncated.
Estimate briefs: 20 to 8,000 characters.