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 — an API key or a Cross App Access token. Response includes a `WWW-Authenticate` header; for an API key it points at the RFC9728 metadata document, for a Cross App Access token see XAA envelopes below.
`403`	Either 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), or a Cross App Access token is missing the `kindo.mcp` scope — see XAA envelopes.
`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.

XAA envelopes

A Cross App Access token that fails verification — expired, the wrong audience or issuer, a bad signature — gets its own 401 with a resource_metadata pointer and the required scope:

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

{ "message": "unexpected \"aud\" claim value" }

A token missing the kindo.mcp scope gets a 403 instead:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="kindo.mcp", resource_metadata="https://api.kindo.ai/.well-known/oauth-protected-resource/v1/mcp", error_description="access token is missing required scope: kindo.mcp"
Content-Type: application/json

{ "message": "access token is missing required scope: kindo.mcp" }

The gateway also rechecks a Cross App Access token’s grant on every call, not just at issuance — the org’s Cross App Access configuration was disabled, the client is no longer approved, the user was deactivated, or the feature is off for the organization. A recheck failure returns the same 401 status and the same WWW-Authenticate challenge as a verification failure above, so a caller can’t distinguish the two from status or header alone. The body does differ in content: a recheck failure always reads { "message": "invalid_token" }, while a verification failure carries the verifier’s own message (as in the aud example above).

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: `data.reason = "manual_approval_required"` when your organization requires human approval, `"credentials_unavailable"` for revoked/expired credentials, or `"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, including an organization approval setting of Block.
`-32603`	Internal error	Unexpected gateway or tool execution failure (`Internal error` or `Tool execution failed`), or organization tool policy could not be loaded or validated (`Unable to load organization tool policy`, refused before execution).

`manual_approval_required` envelope

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "This tool requires human approval and cannot run through external MCP. Use Kindo chat if manual approvals are enabled, or contact your administrator.",
    "data": {
      "reason": "manual_approval_required"
    }
  }
}

Your organization’s approval setting requires human approval, so the call is refused before execution. It creates no pending approval request, and retrying while that setting remains in force produces the same error. Personal tool settings cannot override this organization requirement. Use Kindo chat if manual approvals are enabled for your organization; otherwise, contact your administrator. These tools are also omitted from tools/list; see Scoping.

The gateway checks approval before contacting the tool server. A misspelled tool name on an authorized server can therefore return manual_approval_required; this error does not confirm that the tool exists.

`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.
401 with { "message": "invalid_token" } from a Cross App Access token — The token verified, but its grant is no longer valid: the org’s configuration was disabled, the client is no longer approved, the user was deactivated, or the feature is off for the organization. The response doesn’t say which — see XAA envelopes.
Empty tools/list — Your account has no integrations connected, or you passed an ?integrations= filter that matches nothing your account can reach, or your organization’s approval setting is Ask before running or Block. See Scoping.