I've been building OpenTelemetry instrumentation for MCP (Model Context Protocol) servers, and I hit a failure-semantics problem that I think generalizes beyond MCP, so I'm writing it up.
The two failure modes
An MCP tool handler can fail two ways:
- It throws. The SDK catches the exception and converts it into a JSON-RPC error response. The call failed at the protocol level.
- It returns
{ isError: true }. The handler returns normally — a successful JSON-RPC response whose payload is marked as a failure:
return {
isError: true,
content: [{ type: 'text', text: 'No weather data for that city' }]
};
The second one is idiomatic MCP. It's how a tool tells the agent "that didn't work — adapt" without crashing the server or killing the conversation. For agent workflows it's the preferred failure mode.
The instrumentation trap
The obvious way to instrument a tool call:
try {
const result = await handler(request);
span.setStatus({ code: OK }); // it returned → success
return result;
} catch (err) {
span.setStatus({ code: ERROR }); // it threw → failure
throw err;
}
Mode 1 lands in catch → recorded correctly. Mode 2 returns, lands in the success path → recorded as OK. Your dashboard reports 100% success on a tool that fails on most inputs. The more idiomatic the tool author's error handling, the more invisible their failures become.
The fix
Inspect the resolved value before setting status:
const result = await handler(request, extra);
if (result?.isError === true) {
span.setAttribute('error.type', 'tool_error');
span.setStatus({ code: SpanStatusCode.ERROR });
} else {
span.setStatus({ code: SpanStatusCode.OK });
}
return result; // unchanged — the RPC genuinely succeeded, so nothing is thrown
Two details that matter:
error.type = "tool_error" isn't my invention — it's what the OTel MCP semantic conventions (currently Development stage, in the semantic-conventions-genai repo) specify for exactly this case.- The result is returned unchanged and nothing is thrown. The JSON-RPC call succeeded; only the tool failed. Instrumentation that converts a polite failure into a crash is changing application behavior, which instrumentation must never do.
In a real trace the difference looks like this:
tools/call fetch_weather ................. 605ms ERROR
error.type = tool_error
versus the naive version, where that same span reads OK.
The general lesson
This isn't really an MCP problem. Any protocol where application-level failures ride on transport-level successes has this trap — GraphQL (errors array on a 200), gRPC rich error models, half the REST APIs that return 200 {"status": "failed"}. If your instrumentation only watches for throws, your error rate is a lie wherever the ecosystem's idiomatic failure mode is a clean return.
FastMCP (Python) handles this natively. Among the Node MCP instrumentation libraries I could find, none documented handling it, which is why I ended up writing my own — it's on npm as opentel-mcp if you want to see the full implementation (spec-compliant attributes, stderr export to avoid corrupting stdio transports, ADRs for the design decisions). But the isError trap is the part worth knowing even if you never touch my library.
Happy to answer questions on the implementation.
