Your MCP tool just failed. How does the server tell the model what went wrong?

Flashcard·Easy·4.0 · 0·~30s·Relevant atAnthropic

Attempt it

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.

Your answer

**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.

Memory aid

Easy to grasp

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.

Key concepts

isError Flag JSON-RPC Error Object JSON-RPC Error Codes Tool Error Contract

Detailed answer & concept explanation

~5 min read

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.

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.

A 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.
A 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.
When 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.
MCP 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?

QShould the host reformulate -32602 invalid params into a tool error the model can see?

QHow do MCP error codes interact with HTTP status codes on the streamable HTTP transport?

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.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

References

Primary sources. Skim if you want the original framing.