MCP Tool Errors ≠ JSON-RPC Failures: Two Recovery Paths Clients Must Keep

MCP client tool calls can fail in fundamentally different ways. Protocol-layer errors—such as malformed requests, unknown tool names, or server internal errors—are signaled via JSON-RPC error responses. In contrast, a tool that is correctly invoked but cannot complete its business task returns a normal tool result with isError: true and explanatory content.

The analysis is based on the MCP draft Tools specification dated 2026-10-31; implementers must adapt to the specific protocol revision they use. Conflating these two failure modes into a single exception type discards information needed for retry decisions, user-facing messages, and audit trails.

Two Error Channels Express Different Things

A successful MCP tool response is a result object that may include content and an isError flag. The specification’s example shows a weather tool returning isError: false. When the tool executes but the business operation cannot succeed, the server still returns a tool result with isError: true and a reason in the content.

A JSON-RPC error, by contrast, indicates the request did not yield a normal protocol result—for instance, calling an unknown tool or sending parameters that do not match the tools/call structure. These errors describe a breakdown in “how the client and server speak,” not a business-level failure returned by the tool.

Both error types may need to be reported to the user, but the handling responsibilities differ: protocol errors require checking protocol versions, tool manifests, parameter schemas, or server health; business errors require reading the tool’s content to decide whether to correct the input, wait for an external system, or abort the task.

isError Is Still a Completed Call

Placing isError: true inside the tool result does not mean the client can ignore the remaining payload. The content may contain actionable error codes, missing resource identifiers, or next-step hints. The client should preserve the call ID, tool name, parameter summary, and returned content so that upper-layer workflows can determine whether a retry after input correction is appropriate.

For example, a tool may successfully access a repository but discover that the specified branch does not exist. This is not a tools/call JSON structure error; the server can return a business result with isError: true. The client can then inform the user about the missing branch or launch a new call after the user supplies a valid name.

Conversely, if the client sends an arguments payload with the wrong JSON structure—e.g., a string where an object is required—the request may fail the CallToolRequest protocol schema. If the outer structure is valid but a date is not in the future or a field value exceeds the tool’s business constraints, the specification treats that as an execution error suitable for isError: true feedback. Do not assume that “parameter problem” alone dictates which error channel applies.

Retry Strategy Cannot Just Look at “Failure”

A robust MCP client should classify errors into at least three categories:

Request unintelligible: Illegal method, parameters, or tool name. Priority is to fix the client or re-discover tools.

Tool execution failure: The call was accepted, but business conditions were not met. The decision to supplement input, wait, or terminate is driven by the tool’s returned content.

Result validation failure: The tool returned a normal result ( isError: false), yet the content does not meet the client’s expectations—for example, a required field is missing. This must not be automatically retried as a network error.

The third category is especially easy to overlook. isError: false only means the server did not mark the result as an execution error; it does not guarantee the client’s business logic has validated the payload. If the tool defines an outputSchema, the client should validate the structured result. A validation failure must be recorded as a contract mismatch between the server’s output and the expected schema, not disguised as a timeout.

Let Audit Records Preserve Original Boundaries

Logs should store JSON-RPC error fields and tool result fields separately. At minimum, include the request ID, tool name, protocol error code or isError flag, disclosable error content, and the client’s schema version. Sensitive parameters must still be sanitized; do not write credentials to logs simply to differentiate errors.

This practice lets operators answer: “Did the request reach the tool?” “Did the tool execute to the business layer?” “Did the failure occur at the protocol, business, or validation boundary?”—instead of seeing only a generic tool failed entry.

MCP’s error design separates protocol failures from business failures not to multiply exception types, but to tell the client where to act next. When the request is not understood, fix the protocol; when the tool runs but the business fails, inspect the result; when the result structure is untrustworthy, halt at the validation boundary. Merging all three into a single retry button makes recovery paths uncontrollable.