open-context open-context
November 17, 2026 · 6 min read

How open-context's MCP Tools Report Errors Back to Claude

Most of open-context's MCP tools never throw. A missing context ID or an empty search comes back as a normal text result Claude can read and act on, not a broken tool call. Only real misuse — calling a feature the active store doesn't support, or an unknown tool name — raises an actual error, which the MCP SDK then converts into an isError: true result instead of crashing the connection.

Key takeaways

  • Tools like delete_context, update_context, and get_bubble return a plain text message such as No context found with ID "x" instead of throwing — a "not found" is information, not a failure.
  • The MCP server throws real JavaScript errors only for genuine misuse: calling save_canonical_context or query_canonical_context against a legacy v1 store adapter, or calling a tool name that doesn't exist.
  • The Model Context Protocol separates protocol-level errors from tool execution errors; the TypeScript SDK catches a thrown error and reports it as isError: true content so the model can read the message and retry.
  • open-context's REST API handles failures differently — HTTP status codes plus credential redaction — because its caller is a script or browser, not a model reading text.
  • Because MCP tool errors never carry a connection string, there's nothing in them that needs redacting, unlike the database-facing REST endpoints.

Two kinds of errors in the Model Context Protocol

MCP draws a line between two failure modes that look similar from the outside but are handled completely differently. A protocol error means something is wrong with the request itself — malformed JSON-RPC, a call to a tool that was never registered — and comes back as a JSON-RPC error at the transport level. A tool execution error means the request was valid and the tool actually ran, but the operation itself failed. That second kind doesn't fail the protocol call at all; it comes back as an ordinary successful response whose result sets isError: true.

That distinction exists because the two failures have different audiences. A protocol error is a bug for a developer to fix. A tool execution error is something the model is supposed to read, understand, and potentially recover from mid-conversation — which only works if the error text actually reaches the model instead of tearing down the connection.

How most open-context tools handle "not found"

Open src/mcp/server.ts and you'll notice most of the registered tools never call throw at all. delete_context is typical:

const deleted = await v1.deleteContext(args.id);
return {
  content: [{
    type: 'text',
    text: deleted
      ? `Context ${args.id} deleted.`
      : `No context found with ID "${args.id}".`,
  }],
};

Whether the delete succeeded or the ID didn't exist, the tool returns a normal, successful result — just with different text inside it. update_context, get_bubble, and recall_context follow the same pattern: an empty result set or a missing ID produces a readable sentence, not an exception. From Claude's side, that matters: a thrown error interrupts the model's flow and has to be explained to the user as "something went wrong," while a text result like No contexts found matching "x" is just information Claude folds into its next sentence, the same way a web search with zero results doesn't crash a browser.

When the MCP server actually throws

The exceptions are deliberate, not accidental. open-context's newer v2 "canonical context" tools — save_canonical_context and query_canonical_context — require a store adapter that implements the full OCM (open context model) interface. If the server was started against a legacy v1-only adapter, those tools throw instead of degrading silently:

const { v2 } = await getStore();
if (!v2) {
  throw new Error(
    'Underlying store does not support canonical v2 context operations (legacy adapter in use).'
  );
}

This is a configuration problem, not a data problem — there's no sensible "no results" text to return, because the operation genuinely cannot run. Calling an unregistered tool name hits the same path: the server's own handleToolCall helper — used for direct, in-process tool execution in tests and integrations — throws Unknown tool: <name> if asked to dispatch something that was never registered with server.tool(). In both cases, throwing is correct precisely because there's no partial success to describe — silently returning an empty or misleading result would be worse than telling the caller plainly that the operation can't happen.

What Claude actually sees when a tool throws

Throwing inside a handler doesn't mean Claude's session breaks. The MCP TypeScript SDK's documented error handling wraps every registered tool handler and catches whatever it throws, turning it into the same shape a tool would use if it returned an error on purpose: a CallToolResult with isError: true, where the thrown error's message becomes the result's text content. A client reads a JSON-RPC error response as "the call itself failed" (wrong parameters, unknown method), but reads a successful response with isError: true as "the tool ran, and here's what went wrong" — which is exactly the legacy-adapter message above. The stdio transport stays connected either way; nothing about open-context's MCP process needs to restart because one tool call failed.

That's also why the error messages in src/mcp/server.ts are written as full sentences aimed at a reader, not error codes aimed at a log file — "Underlying store does not support canonical v2 context operations (legacy adapter in use)" tells Claude exactly what's wrong and implicitly what would fix it (reconfigure the store), because that text is the only diagnostic information the model will ever get for that failure.

Why the REST API does it differently

open-context's Express REST API in src/server.ts faces a different caller — a script, a browser, or curl — so it uses a different contract entirely: HTTP status codes. A bad request becomes a 400, a refused database connection becomes a 502, and every error message passes through redactDsn() first, because a driver's raw connection error can echo the database URL — credentials included — straight back into the response body. None of open-context's MCP tools ever handle a raw connection string, so that redaction step simply doesn't apply to them; the worst a tool error message can leak is which store family is configured, not how to connect to it.

The underlying lesson is the same one REST API vs. MCP Server makes about the two interfaces generally: they sit on the same context store but are built for different callers, and "correct error handling" means something different depending on whether a human-written program or a model is going to read the response.

What this means if you're adding a new MCP tool

The pattern worth copying is simple: ask whether the failure is a normal outcome or a broken precondition. An empty search, a missing ID, a bubble with no contexts — these are normal outcomes, and belong in the returned text, not a thrown error. A tool being called against a store that can't support it, or a required dependency that isn't configured, is a broken precondition, and should throw so the SDK's isError path surfaces it clearly instead of returning misleading success text. Getting that split right is most of what good MCP error handling is — the mechanics (SDK-level isError wrapping, a readable message) take care of themselves once the split is correct.

Give Claude persistent memory with tools built to fail gracefully.

Get started with open-context →

FAQ

Does a failed MCP tool call crash the connection to Claude?

No. The MCP SDK catches an error thrown inside a tool handler and converts it into a normal CallToolResult with isError: true. The stdio connection stays open, and Claude sees the error message as text it can read and react to.

Why do tools like save_context and recall_context return text instead of throwing when something isn't found?

Because a missing ID or an empty search result isn't a failure, it's useful information. Returning it as plain text content lets Claude read it and decide what to do next, instead of treating a normal outcome as a broken tool call.

What does open-context's MCP server actually throw an error for?

Mainly for real misuse: calling a v2 canonical-context tool, such as save_canonical_context or query_canonical_context, against a legacy v1 store adapter that doesn't support it, or invoking a tool name that doesn't exist at all.

Does the open-context REST API handle errors the same way as the MCP server?

No. The REST API returns HTTP status codes and redacts any database connection string from error messages with redactDsn(). MCP tool errors never touch connection strings, so there is nothing to redact in the first place.

Is isError part of the MCP specification, or just a convention open-context follows?

It's part of the protocol. The Model Context Protocol separates protocol-level errors, such as an invalid request, from tool execution errors, which are reported inside a successful response via isError: true so the calling model can see what went wrong.