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: `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.
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.

MCP API errors

HTTP-level errors

401 envelope