MCP API errors

POST /v1/mcp returns errors in two different shapes depending on where the failure happens. HTTP-level failures (auth, transport, content negotiation) come back as standard HTTP responses. Protocol-level failures (unknown tool, bad params, credentials revoked) come back inside a JSON-RPC 2.0 error envelope with HTTP 200.

HTTP-level errors

Status	Cause
401	Missing, malformed, or revoked Bearer token. Response includes a WWW-Authenticate header pointing at the RFC9728 metadata document.
403	The API key is valid but the holder lacks the Personal API Key Access entitlement. No WWW-Authenticate header. Ask your admin to enable it in the user’s group settings.
404	Path not handled by the MCP gateway. Check the URL — the gateway accepts POST /v1/mcp and GET /.well-known/oauth-protected-resource[/v1/mcp].
406	Accept header missing text/event-stream. Add Accept: application/json, text/event-stream.
5xx	Unexpected gateway failure. Retries are safe; the gateway is idempotent for tools/list and ping.

401 envelope

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.kindo.ai/.well-known/oauth-protected-resource"
Content-Type: application/json

{ "error": "Unauthorized" }

The WWW-Authenticate header lets spec-conformant MCP clients auto-discover that the resource accepts bearer tokens in the Authorization header. Follow the resource_metadata URL for the RFC9728 document — see Kindo extensions for the payload shape.

JSON-RPC errors

Protocol-level failures come back with HTTP 200 and a JSON-RPC 2.0 error envelope:

Code	Meaning	Typical cause
-32000	Server error	Custom Kindo errors. Most commonly data.reason = "credentials_unavailable" — the upstream connection’s credentials are revoked/expired.
-32601	Method not found	Unsupported method (resources/list, resources/read) or a disabled integration’s tools.
-32602	Invalid params	Unknown tool name, malformed arguments, or a tool your account is not authorized to call.

credentials_unavailable envelope

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "Credentials unavailable for integration linear",
    "data": {
      "reason": "credentials_unavailable",
      "integrationId": "linear",
      "hint": "Reconnect at https://app.kindo.ai/settings/integrations"
    }
  }
}

The hint URL reflects your deployment’s frontend URL — self-hosted customers see the URL configured for their deployment, not app.kindo.ai.

Common failure modes

• 406 Not Acceptable: Client must accept both application/json and text/event-stream — Your client is missing Accept: application/json, text/event-stream. Add it. MCP SDKs and mcp-remote set it for you; only raw HTTP callers hit this.
• -32000 credentials_unavailable — Your connection’s credentials have been revoked or have expired. Reconnect the integration at https://app.kindo.ai/settings/integrations (or your self-hosted deployment’s equivalent).
• -32602 Invalid params with “tool not found” — Check the tool name prefix. Tools are named {integration}_{name} (underscore, not colon). For example, linear_get_issue, not linear:get_issue. Integration IDs containing hyphens still use one underscore as the separator: sap-s4hana-rfc_invoke_bapi.
• 401 with WWW-Authenticate: Bearer — The API key is missing, malformed, or revoked. Verify the key is present and well-formed. The gateway does not fall back from a malformed Authorization header to x-api-key.
• Empty tools/list — Your account has no integrations connected, or you passed an ?integrations= filter that matches nothing your account can reach. See Scoping.

See also

• Quickstart — first successful call.
• Request shape — supported methods and required headers.
• Scoping — why a tool may not appear for your account.