opentel-mcp is an OpenTelemetry instrumentation library for Model Context Protocol (MCP) servers, available for Node.js (npm) and Python (PyPI). Calling instrumentMcpServer(server, options) wraps a server's tools/call handler and creates an OpenTelemetry span for every tool call, detecting silent failures — CallToolResult.isError: true inside an otherwise-successful JSON-RPC 2.0 response — along the way.

What is a silent failure in an MCP server?

A silent failure is when an MCP tool call returns a successful JSON-RPC 2.0 response, but the tool result itself carries isError: true . Instrumentation that only checks whether the JSON-RPC call succeeded misses this, since the failure is nested inside a successful response, not reported as a JSON-RPC-level error. See Silent Failures for the full explanation.

What is Deep Failure Fingerprinting?

Shipped in v0.4.0, Deep Failure Fingerprinting computes a stable 16-character identifier (SHA-256, truncated) for every thrown error and every isError: true result, so repeated occurrences of the same underlying bug group under one fingerprint instead of showing up as unrelated errors. See Deep Failure Fingerprinting .

npm v0.18.1
PyPI v0.2.0
15,000+ npm downloads

Your MCP tool failed. Your traces said 200 OK.

OpenTelemetry for MCP servers in Node.js and Python — it catches silent failures and tampered tool definitions. It detects, never blocks.

npm i opentel-mcp

Read the docs Star on GitHub

1. Tool call

{ "method": "tools/call",

"params": { "name": "query_database" } }

OpenTelemetry
Model Context Protocol
Node.js 20+
TypeScript
MIT licensed
748 tests

15,000+

Total npm downloads since launch.

npm v0.18.1 · PyPI v0.2.0.

200 OK, but the tool failed.

MCP reports success at the JSON-RPC envelope while the failure sits inside CallToolResult.isError. Same call, two traces:

Standard OTel span

tools/call search_docsOK

http.status_code: 200
span.status: UNSET / OK
result.isError: (never inspected)

Dashboards stay green. The failure is invisible.

With opentel-mcp

tools/call search_docsERROR

http.status_code: 200
span.status: ERROR
mcp.failure.fingerprint: stable 16-hex hash

isError detected, span flagged, identical failures grouped.

What's new — v0.18 · Python 0.2.0

Security observability for MCP tool calls

Tool definition integrity: SHA-256 hashes and pinning to spot rug-pulls.
Secret leak detection in tool outputs (opt-in; type and count only).
Auth failure counter and sensitive-tool audit events with wildcards.
Security panel in the dashboard; identical hashes in JS and Python.
v0.18.1: clean install, no deprecation warnings, 0 known vulnerabilities.

Full changelog

Next: v0.19 · planned

Per-call integrity checks
Suspected-rug-pull event
Pin age

Planned, not released. Scope may change.

Built specifically for MCP observability

Always detects, never blocks.

Core

What every server gets from one instrumentMcpServer() call.

Silent-failure detection

isError inside a 200 OK marks the span ERROR.

Error fingerprints

Stable hashes group identical failures; same in JS and Python.

Health grades A–F

A single grade per tool, from real call outcomes.

Unactionable-error detection

Flags errors an agent can't act on or recover from.

flushOnExit

Short-lived processes flush telemetry before they exit.

Tools, resources, prompts

All three MCP call types are traced, not just tools.

Agent thrash detection

Flags the same failure repeating within one session.

Schema drift detection

Flags tools whose inputSchema changes between observations.

Cost and token attribution

Token counts and USD estimates for LLM-wrapping tools.

Shared tracker state

instanceKey keeps state across stateless, per-request servers.

MCP SDK v1 and v2

Works with @modelcontextprotocol/sdk and /server.

Data freshness

Know when a tool is answering with stale data.

Staleness detection

asOf with maxAgeMs, or freshUntil, via the freshness _meta key.

Clock-skew visibility (JS)

Surfaces skew that would make freshness checks misleading.

Privacy and hardening

Observability that doesn't become a data leak.

Never records arguments or results

Tool arguments and results stay out of telemetry.

Credential scrubbing

Credentials are scrubbed before anything is emitted.

Hardened dashboard

CSRF protection, DNS-rebinding defense, CSP, and request size limits.

SECURITY.md and threat model

Documented reporting process and threat-model docs.

Clean install (v0.18.1)

No deprecation warnings, 0 known vulnerabilities, live resource and prompt spans in the dashboard.

Security observability · v0.18 · Python 0.2.0

Notice when a tool changes underneath you.

opentel-mcp detects and reports. It never blocks a call or alters a result.

pinnedsha256:9f2c…41ab

observedsha256:e07d…b390

MISMATCH

Illustrative values.

Tool definition integrity
SHA-256 hashes plus pinning detect rug-pulls: a tool that changes after you approved it.
Secret leak detection
Opt-in. Reports the type and count of secrets in tool outputs, never the value.
Auth failure counter
A metric for rejected credentials across your tool surface.
Sensitive tool audit events
Audit events for the tools you mark sensitive, with wildcard matching.
Security panel
Everything above in the dashboard, with the same hash in JS and Python.

How it works

Install

Add opentel-mcp alongside your existing OpenTelemetry SDK setup.

pnpm add opentel-mcp

Instrument your server

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

import { instrumentMcpServer } from "opentel-mcp";

instrumentMcpServer(server);

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

Capability	opentel-mcp	@opentelemetry/api (raw)
Instruments tools/call automatically
Detects isError: true inside a successful response
Deep failure fingerprinting
Built-in mcp.tool.* metrics instruments
LLM cost tracking on tool calls
Detects an agent retrying the same failure repeatedly
Detects a tool's input schema changing between observations
Detects its own instrumentation silently no-op'ing
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

npm 0.18.1 · PyPI 0.2.0

npm install opentel-mcp

Python support

mcp 1.25–2.x, Python 3.10–3.14
Same silent-failure detection as the Node.js package
Error fingerprints identical to JS (shared conformance fixtures)
Same dashboard, via dev mode
0.2.0 adds the security features: tool integrity hashes and pinning, secret leak detection, auth failure counter, sensitive tool audit events

opentel-mcp on PyPI

After trying opentel-mcp in production MCP servers, developers praised its silent-failure detection for addressing a long-standing gap in MCP observability — something standard OpenTelemetry instrumentation doesn't capture.

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 downloads (weekly) Weekly 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