tracehub-mcp

tracehub-mcp is a Python MCP server that gives Claude, Cursor or any MCP client a read-only query surface over OpenTelemetry traces from LLM applications, for engineers debugging LLM pipelines. It began as a fork of traceloop/opentelemetry-mcp-server, which contributed the architecture, 3 of the 8 backends and 11 of the 19 tools. GitHub does not show it as a fork because it was created with git clone and a second remote; attribution lives in NOTICE and the README.

• Eight backends, one interface — Jaeger, Grafana Tempo, Traceloop, Datadog, Sentry, AWS X-Ray, New Relic and Honeycomb sit behind one BaseBackend; the first three are inherited.
• 19 read-only tools — trace and span search, token and cost aggregation, error hunting, session and prompt-version stats, triage and correlation.
• Deterministic triage — triage_trace returns a critical path, self-time ranking and deepest error chain with a confidence label and no LLM call.
• Best-effort correlation — correlate_trace matches by exact trace id, else a time-window and service-overlap heuristic, and always returns its limitations.
• Cost attribution — usage tools attach cost_usd from a vendored litellm table of 4,473 models, flagged partial when a model is unresolved.
• Guarded transport — requests stay pinned to the configured origin, cloud-metadata hosts are blocked, and response bodies are byte-capped.

At v0.13.0 (2026-10-14): 322 commits (303 after the fork point), 20 releases in 33 days and 1,737 test functions by static count, with 95% coverage read from the Codecov badge; a solo-maintained repo with no stars, no forks and no outside contributors, whose New Relic and Honeycomb backends have never run against a live account, and recorded integration cassettes exist only for the inherited Jaeger, Tempo and Traceloop backends.

Architecture

One Python package, src/opentelemetry_mcp/, holds the server (43 files, 19,077 lines at v0.13.0). The import name is still upstream's opentelemetry_mcp; only the distribution and CLI are named tracehub-mcp. server.py carries the FastMCP app, the Click CLI, the 19 tool handlers, Origin and Host validation, rate limiting and bearer-token middleware.

backends/base.py defines the abstract BaseBackend and a shared retrying httpx transport that spends one retry and redirect budget under a single deadline; X-Ray uses boto3 on a private 8-thread executor instead. A hybrid filter engine pushes supported operators down into each backend's native language (TraceQL, NRQL and others) and applies the rest client-side. Each tool has its own module under tools/; triage.py and correlate.py compose the iterative, cycle-safe walks in span_tree.py.

Delivery is a non-root multi-stage Dockerfile, a Claude Desktop mcpb/ bundle and 9 GitHub Actions workflows (mypy --strict, pytest with Codecov, MCP conformance, Trivy, CodeQL, Scorecard, TruffleHog). Releases go to PyPI, the MCP registry and GHCR. v0.13.0 is a 0.x release with 14 breaking changes and 90 fix(security) commits, the output of a security-audit remediation programme rather than feature work.

How It Works

1. Configure — BACKEND_TYPE, BACKEND_URL and backend credentials come from env, .env or CLI flags; config.py refuses credentialed URLs, cloud-metadata hosts and out-of-range values at startup.
2. Serve — The server runs on stdio or streamable HTTP; HTTP binds to loopback by default, and a non-loopback bind will not start without MCP_HTTP_BEARER_TOKEN.
3. Query — A call such as search_traces builds a TraceQuery; the filter engine splits it into native pushdown and client-side evaluation, and the backend sends it through the origin-pinned, byte-capped transport.
4. Reconstruct — Datadog, X-Ray, New Relic and Honeycomb have no trace-level search, so traces are rebuilt from spans or summaries and re-verified against the requested trace id. Datadog and Sentry reject malformed spans rather than invent timestamps, per the README; the three inherited backends were deliberately not retrofitted.
5. Price — Spans become typed SpanData and TraceData with gen_ai.* fields, and aggregation tools add cost_usd.
6. Diagnose — triage_trace walks the span tree; correlate_trace queries a configured secondary backend by trace id, then falls back to its heuristic.
7. Cache and observe — With QUERY_CACHE_TTL_SECONDS set, repeat queries come from a TTL cache that coalesces concurrent duplicates; /health and /ready serve orchestrators, and OTEL_EXPORTER_OTLP_ENDPOINT adds an opt-in span per tools/call.