mcp-telemetry

Zero-config observability for MCP servers. OTel GenAI conventions. Redaction on by default.

MCP hit 97 million monthly SDK downloads — and the production playbook is still being written. OWASP's MCP Top 10 puts "Lack of Audit and Telemetry" at the top of the risk list. This repo is that gap, filled in three lines.

Install

pip install mcp-telemetry            # core — zero dependencies
pip install 'mcp-telemetry[otlp]'    # + OTLP/HTTP export (httpx)

Use — no changes to your server logic

import mcp_telemetry as mt

mt.auto()                                # patches the official `mcp` SDK, writes JSONL

@mt.wrap_tool_call("issues.fetch", server="gh")
def fetch_issue(issue_id, token=""):
    ...

Every call emits an OTel GenAI gen_ai.client.tool_call span with:

• input fingerprint — SHA-256 hash, never the raw payload
• secret scrubbing — token, secret, api_key-style keys → [REDACTED]
• latency, status, error type, server name

Manual spans and traces work too:

with mt.session():                    # one trace for the whole agent turn
    with mt.span("chat.step"):
        ...

Distributed traces cross servers

Propagation is built in. A traceparent header on an inbound MCP request starts a continuation, not a new trace — the span stamps parent_span_id and the trace id carries through:

from mcp_telemetry.propagator import parse_traceparent
store.start(parse_traceparent(my_header).trace_id)

Pair with mcp-hub: the gateway relays W3C traceparent verbatim to every upstream, and the responder below records the far side. One trace, end to end. See examples/responder.py for a stdlib-only server that does exactly this.

Watch the firehose

mcp-trace                 # last 25 spans, ANSI table
mcp-trace --tail          # follow the JSONL feed
mcp-trace --json | jq .   # pipe raw records anywhere
mcp-trace --replay store.jsonl --console   # offline replay → OTLP-shaped output

Exporters

Spans follow OTel GenAI semantic conventions (gen_ai.client.tool_call, gen_ai.agent.invoke) so traces land in your existing stack without a transform layer.

Extended surface

• Sampling — parent_based, ratio, rate_limited (mcp_telemetry.sampler)
• Metrics — Registry + histogram buckets, metrics_from_store (mcp_telemetry.metrics)
• OTel provider — builds OTLP-shaped telemetry, OtelProvider.export_built (mcp_telemetry.otel_provider)
• fastmcp — opt-in shim: mt.make_server(), patch_fastmcp (mcp_telemetry.fastmcp)
• Offline replay — re-deliver any recorded JSONL through the exporter stack

Overhead

examples/bench.py: ~78µs median, ~85µs p95 per instrumented call (Python 3.14). There's no free lunch, but at that cost you can trace every tool call in a hot agent loop.

Design

• monkey.py — monkeypatches the official mcp SDK's call_tool; idempotent, no-ops cleanly when the SDK is absent
• redact.py — fingerprinting + secret scrubbing, deterministic hashes
• store.py / api.py — trace lifecycle + the three-line public surface
• propagator.py — W3C traceparent/tracestate continuation between services
• replay.py / cli.py — offline re-export + mcp-trace renderer/tail/replay
• Core import graph is stdlib-only; httpx lives behind [otlp]

MIT. Ship it.