MCP

Errors & Troubleshooting

MCP clients need to distinguish transport or protocol errors from tool-level outcomes. A successful JSON-RPC response does not always mean the business action completed — inspect isError, structuredContent.reason_code, structuredContent.tool_output, and structuredContent.execution.status.

Response shapes

1. JSON-RPC error response

Used for protocol, authentication, authorization, session, rate-limit, or unavailable-edge failures.

{
  "jsonrpc": "2.0",
  "id": "tools-list",
  "error": {
    "code": -32001,
    "message": "Public MCP requests require Authorization: Bearer <api_key>.",
    "data": { "code": "authentication_required" }
  }
}

2. Tool result with isError: true

tools/call may return HTTP 200 and a JSON-RPC result with isError: true. Treat that as a business failure — inspect structuredContent before retrying.

{
  "jsonrpc": "2.0",
  "id": "call-send-email",
  "result": {
    "content": [{ "type": "text", "text": "Tool invocation failed." }],
    "structuredContent": {
      "reason_code": "sender_profile_unavailable",
      "tool_output": {
        "error_code": "sender_profile_unavailable",
        "error_message": "The default sending domain must finish verification before production email can be sent without from. Provide from explicitly, or verify the default domain."
      },
      "execution": {
        "status": "failed"
      }
    },
    "isError": true
  }
}

This example shows sender_profile_unavailable when send_email runs with full_execution and an omitted from while the workspace default sender/domain is not ready for production. Omit from only when that default is configured and verified for production; otherwise confirm production sending setup with the user before retrying, or supply a production-authorized from.

3. Tool result awaiting confirmation (isError: false)

Some production actions pause for explicit human confirmation instead of failing. The JSON-RPC request still succeeds, but isError stays false and structuredContent.execution.status is awaiting_confirmation. No production send has been created yet.

{
  "jsonrpc": "2.0",
  "id": "call-send-email",
  "result": {
    "content": [{ "type": "text", "text": "Production email is awaiting explicit confirmation. No production send request or schedule has been created." }],
    "structuredContent": {
      "reason_code": "explicit_production_confirmation_required",
      "tool_output": {
        "error_code": "explicit_production_confirmation_required",
        "error_message": "explicit_production_confirmation must be true for production execution."
      },
      "execution": {
        "status": "awaiting_confirmation",
        "confirmation": {
          "required": true,
          "required_argument": "explicit_production_confirmation"
        }
      }
    },
    "isError": false
  }
}

After the user confirms, retry with explicit_production_confirmation: true and a new idempotency_key (for example, production-send-confirmed-002). Do not reuse the idempotency_key from the suspended awaiting_confirmation call.

Common error codes

Troubleshooting