When a tool's business logic fails (e.g. a database query error), the server must return the error as a successful JSON-RPC `` (not the `error` field). The content array item should contain the error message, and the `` flag must be set to `true` to signal that the tool invocation failed. This contrasts with JSON-RPC protocol errors, which use the `` field for issues like unknown methods.
MCP splits failures into two kinds, and they go to different places.
The first kind is a **tool-level error**: the request was valid and the method exists, but the work inside the tool failed. A database query timed out, a file was missing, an API returned 500. For these, the server still answers on the normal success path. It returns a JSON-RPC `result`, puts the error message in the content array, and sets `isError: true`. Because the message lands in the result, the model actually sees it and can retry or apologize.
The second kind is a **protocol error**: the request itself is broken. The method name is unknown, the JSON is malformed, the parameters fail validation. These use the JSON-RPC `error` field with a numeric code. The model never gets to react; the host handles it.
The rule of thumb: if the tool ran and failed, use `result` plus `isError`. If the tool could never run, use `error`. Mixing these up is the classic MCP bug.
MCP layers tool semantics on top of JSON-RPC, and that creates two distinct error channels.
**Protocol errors** use the JSON-RPC `error` field. These cover a malformed request, an unknown method, or invalid parameters. The call never reached working tool logic. JSON-RPC assigns numeric codes here, and the host, not the model, deals with them.
Tool execution errors are different. The method existed and ran, but its business logic failed. A query errored, a network call timed out, a file was absent. MCP says the server must still return a normal `result`. The failure message goes into the content array, and the response sets `isError: true`.
Why route a failure through the success path? Because the model needs to see it. If a database timeout came back as a JSON-RPC `error`, the host would intercept it and the model would receive nothing useful. By keeping it in the result with `isError: true`, the failure text becomes part of the conversation. The model can read it, retry with different arguments, or tell the user what broke. That is the whole point: tool errors are data the model reasons over, protocol errors are plumbing faults the host absorbs.
Quick reference
TL;DR
A tool logic failure rides the JSON-RPC `result` with `isError: true` so the model sees it; only protocol faults like unknown methods use the `error` field.
Imagine ordering food through a waiter. If the kitchen burns your dish, the waiter still comes back to your table and tells you 'sorry, the dish failed' so you can decide what to do next. That is a tool error: the request was understood, but the work failed, and the result comes back to you with a 'this went wrong' note attached. Now imagine you mumble an order for a dish that does not exist on the menu. The waiter cannot even take the order. That is a protocol error: the request itself was malformed. MCP keeps these two cases on separate tracks, so the model gets handed the kitchen failures it can react to, while the truly broken requests bounce back differently.
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.
The request itself is malformed or names an unknown method That is a protocol fault the tool never executed, so it belongs in the JSON-RPC error field, not in a result with isError.
A parameter fails schema validation before any logic runs Validation happens at the protocol boundary, so it is an invalid-params error, not a tool execution failure the model should reason over.
You want to hard-stop the host and abort the session on a fatal fault isError keeps the conversation alive for the model to retry; a true abort needs a transport-level error or connection teardown instead.
Quick scan · 2–4 min
Everything important, quickly.
5 min: the two error channels + why tool errors ride the result with isError + which faults use the error field + the production exception-handling trap + the injection risk of error content.
Code example
typescript
// Tool logic failure -> result with isError, NOT a thrown JSON-RPC error
server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
const rows = await runQuery(request.params.arguments.sql);
return { content: [{ type: "text", text: JSON.stringify(rows) }] };
} catch (err) {
return {
content: [{ type: "text", text: `Query failed: ${err.message}` }],
isError: true // model sees this and can react
};
}
});
Side-by-side
Aspect
Tool execution error
JSON-RPC protocol error
Where it lives
result, with isError true
error field, with a code
What failed
Tool logic ran and threw
Request never executed
Examples
DB timeout, missing file, API 500
Unknown method, bad params, malformed JSON
Who reacts
The model reads and retries
The host catches and logs
Visible to model
Yes, in the content array
No, intercepted by the host
Real-world examples
Real products, models, and research that use this idea.
1The official MCP filesystem server returns isError true with a message when a read targets a missing path, rather than throwing a JSON-RPC error.
2Claude Code surfaces an isError tool result back into the model's context so Claude Opus 4.7 can retry a failed shell command on the next turn.
3A Postgres MCP server catches a SQL syntax error inside tools/call and packs it into result content so the model can rewrite the query.
Interviewer follow-ups
What an interviewer would ask next. Try answering before peeking at the approach.
QHow should a client distinguish a tool error from a protocol error when both can appear after a tools/call?
Sign in or go Pro to see the approach for this follow-up.
QWhat belongs in the content array of an isError result, and what should you deliberately omit?
Sign in or go Pro to see the approach for this follow-up.
QCould a malicious server abuse the isError channel to inject instructions into the model?
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 tool failure as a JSON-RPC error. That hides it from the model, which can no longer see the message or self-correct on the next turn.