Two channels, two audiences. Tool error: return a successful JSON-RPC response with isError: true and a content array describing the failure. The host forwards this to the model so the LLM can read the error and retry or adjust. Protocol error: return a JSON-RPC error object with a numeric code (e.g., -32601 method not found, -32602 invalid params) and a message. The host catches this for logging; the model does not see it. The test: can the model do something useful with this information? If yes, use isError. If no, use the error object.
**MCP separates two kinds of failures** so each reaches the right audience.
**Tool error** means the tool ran, but its outcome was a failure. Examples: the file does not exist, the API returned a rate-limit response, the SQL query had a syntax error, the user denied permission. The server returns a successful JSON-RPC response whose result has `isError: true` and a `content` array (typically a text block) explaining what went wrong. The host forwards this to the model on the next turn. The model reads the error and decides what to do: retry with different arguments, try another tool, or explain the problem to the user.
**Protocol error** means the protocol layer broke down before the tool could run. Examples: the client called a method the server does not implement, the parameters did not match the schema, the JSON was malformed, the server crashed. The server returns a JSON-RPC error response (no result, an error object instead) with a numeric code and a string message. Standard codes include `-32601` method not found, `-32602` invalid params, and `-32603` internal error. The host catches these for logging and debugging; the model does not see them because it has no language-level way to fix protocol bugs.
The most common implementation mistake is mixing the two paths: returning JSON-RPC errors for tool failures (the model never sees them and gives up) or returning `isError: true` for protocol bugs (the host cannot detect them).
**MCP defines two distinct error channels**, and choosing the right one determines whether the model can recover from a failure.
**Tool error path**: for failures of the tool's business logic (file not found, rate-limited, invalid query, permission denied, downstream service unavailable). The server returns a normal successful JSON-RPC response. The result carries `isError: true` and a `content` array describing the failure. The host wraps this as a tool_result on the next inference turn. The model reads the error and has options: retry with corrected arguments, fall back to a different tool, or explain the problem to the user.
**Protocol error path**: for failures of the protocol contract (method not found, invalid params, malformed JSON, internal crash). The server returns a JSON-RPC error response with no result and an error object containing numeric `code`, string `message`, and optional `data`. Standard codes: `-32700` parse error, `-32600` invalid request, `-32601` method not found, `-32602` invalid params, `-32603` internal error. The host catches these for debugging and does not forward them to the model.
The decision test is simple: would the model be able to do something useful with this information? If yes, it is a tool error and goes through `isError: true`. If no, it is a protocol error and goes through the JSON-RPC error object.
The most common server bug is using `-32603` for tool exceptions. A developer catches a business-logic exception and sees a stack trace, so they return a JSON-RPC internal error. The model never sees it; the agent gives up. Fix: catch inside the tool handler, format as a content block, return with `isError: true`.
Quick reference
TL;DR
Tool error: successful response with `isError: true` plus content the model reads. Protocol error: JSON-RPC error object with numeric code; the host catches it and the model never sees it.
Imagine ordering food at a restaurant. Two ways things can go wrong. First: the kitchen tried to cook your dish but ran out of an ingredient. The waiter brings you a polite note explaining and asks if you want something else. That is a tool error. The tool ran, but the result was a failure. You (the model) read the note and decide what to do next.
Second: the waiter does not understand what you said because you spoke a language they do not know. The conversation broke down before anyone could try cooking. That is a protocol error. The system failed before the operation even started.
MCP uses different channels for each: a flag inside a normal response for the first kind, a numbered error code for the second.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.
Returning an empty isError true result with no content describing what went wrong. The model needs the error message to react. An empty content array leaves it guessing and likely produces an unhelpful retry.
Using JSON-RPC errors for business-logic failures the model could recover from. The model never sees JSON-RPC errors. Recoverable failures (rate limits, missing files, bad inputs) should use isError true so the model can decide what to do.
Using isError true for genuine protocol violations. Hosts and observability tools rely on JSON-RPC errors to detect protocol regressions. Hiding protocol bugs in normal responses makes them invisible to debugging tools.
Quick scan · 2–4 min
Everything important, quickly.
4 min: walk both error channels with one example each, state the decision test (can the model act on it?), name the standard JSON-RPC codes, describe the most common bug (mixing channels), and close with the host-side convention of reformulating -32602 as an isError tool result for model recovery.
Real-world examples
Real products, models, and research that use this idea.
1A filesystem server asked to read a missing file returns `{isError: true, content: [{type: 'text', text: 'File not found: /path/to/missing.ts'}]}`. The model on the next turn retries with a corrected path or asks the user.
2A database server asked to run invalid SQL returns `{isError: true, content: [{type: 'text', text: 'SQL syntax error at line 3: unexpected FROM'}]}`. The model corrects the SQL and retries.
3When the host calls `resources/list` against a server that did not advertise the resources capability, the server returns JSON-RPC error `-32601 method not found`. The host logs the violation; the model never sees it.
4MCP Inspector distinguishes the two paths visually: isError results appear in red within a normal response panel, while JSON-RPC errors appear in a separate error panel with the numeric code displayed.
Interviewer follow-ups
What an interviewer would ask next. Try answering before peeking at the approach.
QWhat is the right path for a tool that hit an unexpected exception during execution?
Sign in or go Pro to see the approach for this follow-up.
QShould the host reformulate -32602 invalid params into a tool error the model can see?
Sign in or go Pro to see the approach for this follow-up.
QHow do MCP error codes interact with HTTP status codes on the streamable HTTP transport?
Sign in or go Pro to see the approach for this follow-up.
Don't say this
Red flags and common mistakes that signal junior thinking. Click to expand.
Most common mistake
Returning a JSON-RPC error for tool business-logic failures. The model never sees JSON-RPC errors. Use `isError: true` in the result so the model can read the failure and decide how to recover.