MCP API errors

POST /v1/mcp can report failures at three levels. HTTP failures (auth, transport, content negotiation) come back as standard HTTP responses. JSON-RPC protocol failures come back in a JSON-RPC 2.0 error envelope with HTTP 200. A valid tool call can instead return an MCP tool error result.

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`.
`413`	JSON request body exceeds the 50 MB (52,428,800-byte) limit. Returned before MCP handling as `{"message":"Request body too large. Maximum size is 50 MB."}`.
`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. Also `"dlp_uninspectable_content"` and `"dlp_unavailable"` — see data loss prevention.
`-32601`	Method not found	Unsupported method (`resources/list`, `resources/read`) or a disabled integration’s tools.
`-32602`	Invalid params	Unknown tool name, gateway-level invalid parameters, 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 the integration in Settings > Integrations at https://app.kindo.ai/"
    }
  }
}

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

DLP envelopes

A result the organization’s DLP policy will not let out comes back as a deliberate -32000, never a masked internal error:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32000,
    "message": "Result contains content that cannot be DLP-inspected; blocked by organization policy (fail-closed).",
    "data": {
      "reason": "dlp_uninspectable_content",
      "contentKind": "embedded binary resource"
    }
  }
}

data.reason is "dlp_unavailable" instead when the policy itself could not be determined or applied. Both are terminal — retrying produces the same result. See data loss prevention for which content is redacted and which is blocked.

MCP tool errors

A call to a valid platform_* tool with arguments that do not match the tool’s schema returns a successful JSON-RPC response whose result is a CallToolResult with isError: true. The text content is a JSON error body:

{
  "content": [
    {
      "type": "text",
      "text": "{\"code\":\"invalid_input\",\"message\":\"agent_id must be a valid UUID\",\"retryable\":false}"
    }
  ],
  "isError": true,
  "_meta": {
    "kindo.dev/platform-tool-error": 1
  }
}

Read the text value as JSON to inspect the error. The versioned _meta marker identifies this Platform tool error format.

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 in Settings > Integrations at https://app.kindo.ai/ (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.