Skip to content
opentel-mcp
v0.4.0 — Deep Failure Fingerprinting shipped

OpenTelemetry for MCP servers that actually catches silent failures.

MCP tools can return a successful JSON-RPC envelope with isError: true buried inside. Standard OpenTelemetry never sees it. opentel-mcp does — and marks the span ERROR.

pnpm add opentel-mcp
Read the docsStar on GitHub
1. Tool call
{ "method": "tools/call",
"params": { "name": "query_database" } }
  • OpenTelemetry
  • Model Context Protocol
  • Node.js 20+
  • TypeScript
  • MIT licensed
  • 136 tests

A tool can fail and your traces will still say it succeeded.

MCP's JSON-RPC 2.0 transport reports success at the envelope level even when the tool itself failed — the failure is nested inside CallToolResult.isError. Standard instrumentation only looks at the envelope.

Silent failure inside a successful JSON-RPC envelopeJSON-RPC 2.0 response — HTTP 200 OKresult.isError = truecontent: [ "Connection timeout" ]⚠ never inspected by standard OTel instrumentation

Built specifically for MCP observability

Silent Failure Detection

Detects CallToolResult.isError = true inside otherwise-successful JSON-RPC responses and marks the span ERROR — no other Node.js MCP library does this.

Deep Failure Fingerprinting

SHA-256 hashes truncated to 16 hex characters group identical failures across traces, without leaking raw payloads into span attributes.

Four Metrics Instruments

Ships counters and histograms out of the box, including mcp.tool.silent_failures, ready for Prometheus, SigNoz, or any OTel-compatible backend.

Zero-Config Auto-Instrumentation

Wrap your MCP server once and every tools/call gets a span immediately — no manual span management required.

Never Throws

Every instrumentation path is designed to fail safe. Fingerprinting falls back to a fixed value rather than raising an exception.

Cardinality-Safe Labels

A frozen METRIC_SAFE_ATTRIBUTES array constrains metric attributes, preventing high-cardinality label explosions in your backend.

How it works

01

Install

Add opentel-mcp alongside your existing OpenTelemetry SDK setup.

pnpm add opentel-mcp
02

Instrument your server

Wrap your MCP server once — every tools/call gets a span automatically.

import { instrumentMcpServer } from "opentel-mcp";

instrumentMcpServer(server);
03

See silent failures in your traces

Tool calls with isError: true now show up as ERROR spans with a stable fingerprint, in any OTel-compatible backend.

span: tools/call query_database
status: ERROR
fingerprint: a1b2c3d4e5f6a7b8

How opentel-mcp compares

Capabilityopentel-mcp@opentelemetry/api (raw)
Instruments tools/call automatically
Detects isError: true inside a successful response
Deep failure fingerprinting
Built-in mcp.tool.* metrics instruments
Cardinality-safe metric attributes, structurally enforced
Never throws into the instrumented handler
Requires manual span code per handler

Raw @opentelemetry/api has no concept of MCP or CallToolResult — that's true by definition, not a knock against it. See the full comparison page for the reasoning behind every row, including why fastmcp and mcp-tracer aren't columns here.

Install in seconds

pnpm add opentel-mcp

After trying opentel-mcp in a production MCP server, engineer Siranjeevi Ramdoss called out its silent-failure detection as closing a real gap in MCP observability tooling — a problem standard OpenTelemetry instrumentation simply doesn't see.

Paraphrased from feedback on LinkedIn.

Filed and fixed an upstream fastmcp bug related to error propagation — fastmcp#4549.

Discussed by the community on r/OpenTelemetry.

npm downloadsWeekly npm downloads for opentel-mcp

Stop shipping silent MCP failures.

Install opentel-mcp and see the first ERROR span it catches that your current setup misses.

pnpm add opentel-mcp
Get started