Tracehub MCP

tracehub-mcp

Also listed on the official MCP registry as io.github.mcpsmiths/tracehub-mcp (the registry's own ?search= endpoint can surface an outdated version first; this exact-name endpoint always reflects the current isLatest release), and on mcprush.

Give your AI assistant a direct line into your observability backend. tracehub-mcp is an MCP (Model Context Protocol) server that lets Claude, Cursor, Windsurf, Gemini CLI, or any MCP client query OpenTelemetry traces from your LLM/GenAI application and reason about them — find expensive calls, debug errors, compare model performance, track token usage — without you copy-pasting trace JSON into a chat window.

It speaks OpenTelemetry's gen_ai.* semantic conventions natively, so it understands prompts, completions, token usage, and finish reasons as first-class concepts, not just generic span attributes.

tracehub-mcp started as a fork of traceloop/opentelemetry-mcp-server (Apache 2.0) — full attribution and fork history are in NOTICE. It's grown into an 8-backend, security-hardened server maintained independently under mcpsmiths; see What's Different From Upstream below for the parts that are new here.

Table of Contents

• Quick Start
• Supported Backends
• What's Different From Upstream
• Installation
• Configuration
• Diagnostics
• Security Considerations
• Privacy Policy
• MCP Client Setup
• Tools Reference
• Generic Filter System
• Example Queries
• Common Workflows
• Development
• Troubleshooting
• Roadmap
• License
• Support

Quick Start

tracehub-mcp is on PyPI. No install step needed — uvx fetches and runs it in one shot:

// claude_desktop_config.json

{ "mcpServers": { "tracehub-mcp": { "command": "uvx", "args": ["tracehub-mcp"], "env": { "BACKEND_TYPE": "jaeger", "BACKEND_URL": "http://localhost:16686" } } } }

Or from Claude Code directly:

claude mcp add tracehub-mcp -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://localhost:16686 -- uvx tracehub-mcp

That's it. Ask your assistant: _"Show me traces with errors from the last hour."_

See MCP Client Setup for Cursor, Windsurf, VS Code, and Gemini CLI, and Installation for pip/pipx/from-source alternatives.

Supported Backends

• [Jaeger](https://www.jaegertracing.io/) — local/self-hosted, the most common open-source trace backend. No auth required (a Bearer token can be sent via BACKEND_API_KEY; credentials embedded in BACKEND_URL are rejected).
• [Grafana Tempo](https://grafana.com/oss/tempo/) — local or Grafana Cloud, TraceQL-native search.
• [Traceloop](https://www.traceloop.com/) — cloud LLM observability platform, API-key auth.
• [Datadog](https://www.datadoghq.com/) — cloud APM, requires an API key *and* an Application key.
• [Sentry](https://sentry.io/) — cloud or self-hosted, requires an auth token and an organization slug.
• [AWS X-Ray](https://aws.amazon.com/xray/) — SigV4-signed via boto3, requires an AWS region and standard AWS credentials (not an API key). Because OTel span attributes land in unindexed X-Ray segment *metadata* by default (only *annotations* are queryable), native server-side filtering is narrower here than for the other backends — see the Backend Support Matrix.
• [New Relic](https://newrelic.com/) — NerdGraph GraphQL API, requires a User API key (not an Ingest/License key) and an account ID. Built without a live account to verify against — see the New Relic setup section below and the module docstring in backends/newrelic.py for exactly which assumptions are unverified.
• [Honeycomb](https://www.honeycomb.io/) — Query Data API, requires a Configuration Key and a dataset slug. Built without a live account to verify against, and the research behind it found the programmatic Query Data API (the only way to actually run a query and get results back) is documented as Enterprise-plan exclusive — see the Honeycomb setup section below and the module docstring in backends/honeycomb.py.

All eight implement the same BaseBackend interface, so every MCP tool works identically regardless of which one you point the server at. See Configuration for per-backend setup.

What's Different From Upstream

Upstream opentelemetry-mcp-server shipped Jaeger, Tempo, and Traceloop. tracehub-mcp adds Datadog and Sentry as full backends — not thin wrappers, but complete implementations of every tool (search, span search, trace hydration, service discovery, health checks). Along the way, all five backends — including the three inherited from upstream — were hardened to a consistent bar:

• HTTPS-only enforcement on cloud backends. Datadog and Sentry both refuse to start against a plain http:// URL, because their auth is a bearer token / API+App key pair that has no business going out over plaintext.
• Query-injection-safe escaping. Every value spliced into a Datadog span-search query or a Sentry Discover query is escaped and exact-quoted; field *names* (which are less obviously untrusted, since they come from the MCP tool's filters parameter) are validated against an allowlist pattern before being spliced into the query string, closing off structural injection through a crafted field name.
• Bounded pagination on every backend that paginates via cursor (Datadog, Sentry) — a search stops at the requested limit or when the backend stops returning a continuation cursor, whichever comes first, so a single tool call can't degrade into an unbounded crawl.
• Exact-ID re-verification. Where a backend's search API can return neighbors instead of an exact match (notably Datadog's trace reconstruction from grouped spans), every result is re-checked against the exact ID that was asked for before being returned.
• No fabricated data on malformed responses, in the backends we built. Datadog and Sentry reject a span outright — rather than substituting a placeholder like now() for a missing timestamp or a literal "unknown" for a missing service_name/operation_name — since a fabricated value would silently corrupt trace ordering, duration aggregation, and any tool that groups by service or operation. (The three backends inherited from upstream — Jaeger, Tempo, Traceloop — predate this discipline and haven't been retrofitted; that's deliberate scope discipline, not an oversight, mirroring this project's own precedent of not reaching into shared/inherited code without full regression coverage for it.)

All of this is backed by 458 passing tests (2 skipped, zero regressions), a clean ruff check and mypy --strict run, and two rounds of adversarial CodeRabbit review on the new backends.

Installation

tracehub-mcp is on PyPI. Pick whichever of these your workflow already uses — they're equivalent.

Option 1: uvx (no install step)

uvx tracehub-mcp --backend jaeger --url http://localhost:16686

This is what the Quick Start config above uses — uv fetches the package and runs the tracehub-mcp entry point in one shot, nothing left behind on disk between runs.

Option 2: pip / pipx

pipx install tracehub-mcp

or: pip install tracehub-mcp

tracehub-mcp --backend jaeger --url http://localhost:16686

Option 3: Clone and run from source

git clone https://github.com/mcpsmiths/tracehub-mcp.git

cd tracehub-mcp uv sync

uv run tracehub-mcp --backend jaeger --url http://localhost:16686

Use this if you're developing locally, want to pin to a specific commit, or want the dev tooling installed (uv sync --group dev).

Option 4: Docker

# The image's CMD binds 0.0.0.0 inside the container, so a caller token is

mandatory: clients send it as Authorization: Bearer $MCP_HTTP_BEARER_TOKEN.

export MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) docker run --rm -p 8000:8000 \ -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://host.docker.internal:16686 \ -e MCP_HTTP_BEARER_TOKEN \ -e MCP_ALLOWED_HOSTS=localhost \ ghcr.io/mcpsmiths/tracehub-mcp:latest

Backend responses are capped at BACKEND_MAX_RESPONSE_BYTES (64 MiB decoded by default) before they are buffered, but a container that serves many sessions still benefits from Docker's own guard rails: add --memory 1g --restart unless-stopped (or the Compose equivalents) so a process that does exhaust memory is contained and comes back without an operator.

Runs HTTP transport by default (the image's CMD) and refuses to start without MCP_HTTP_BEARER_TOKEN - or the explicit -e MCP_ALLOW_UNAUTHENTICATED_HTTP=true opt-out, which hands every peer that can reach the published port your backend's full read scope. Clients connect to http://localhost:8000/mcp with Authorization: Bearer ; /health and /ready (the image's HEALTHCHECK) never need the token. Because the CMD binds 0.0.0.0, the container validates the Host header only when MCP_ALLOWED_HOSTS is set - always set it to the hostnames clients use (localhost in the example above, the public name in a real deployment); * turns Host validation off and may not be mixed with names (the server refuses to start). This is also the form to use for MCP clients whose config takes a command/args pair pointing at docker directly (Cursor, Windsurf) instead of a local binary - pass the same -e MCP_HTTP_BEARER_TOKEN=... in args.

Prerequisites: Python 3.11+, plus uv for Options 1 and 3; Docker for Option 4.

Configuration

Configuration comes from environment variables, CLI flags, or both. Precedence: CLI arguments > environment variables > defaults.

# .env (see .env.example)

BACKEND_TYPE=jaeger BACKEND_URL=http://localhost:16686

# Equivalent via CLI flags

tracehub-mcp --backend jaeger --url http://localhost:16686

All Configuration Options

| Variable | Type | Default | Description