MCP Trace

What MCP Trace MCP server does

The MCP Trace MCP server, distributed in the repository as SpanHound, gives MCP clients a query interface for locally stored traces from agent runs. It is intended for inspecting what an agent did, why a run was slow or failed, how approvals were handled, and how two runs differ. The data source is a local directory containing supported JSONL spans or saved OTLP JSON exports.

The server focuses on evidence recorded in traces rather than interpretation of an agent's final answer. It can return bounded, redacted failure details and failed tool calls, approval decisions with the recorded actor and rationale, token and cost information, and security-related fields such as caller identity, tenant, server provenance, risk, and approval evidence.

How it works

The MCP Trace MCP server runs as a local stdio process and reads trace files from the directory supplied at startup. It can inspect files that already exist and poll files being written while a run is active. The recent_activity tool uses a cursor to find newly written spans; the server does not push events to clients.

Traces can be captured in two supported ways. For Python agents, the optional auto-instrumentation package can run the agent through SpanHound and capture supported calls from OpenAI, Anthropic, OpenAI Agents, HTTPX, and Requests. The agent and capture command must use the same Python environment. For other runtimes, or agents that already export OpenTelemetry data, the local receiver accepts OTLP/HTTP JSON or protobuf on loopback and stores accepted requests as local JSON files. The receiver does not add instrumentation to an agent.

The bundled demo uses a recorded regression trace and does not require a trace backend, account, repository clone, or MCP client. It illustrates a blocked shell call with its diagnostic and approval evidence.

Setup and configuration

Install and start the server with UV, pointing it at a trace directory:

uvx spanhound --trace-dir /path/to/traces

Use --check to list discovered runs and validate the directory's complete JSONL or OTLP JSON records without starting an interactive inspection session. A local development checkout can be run with uvx --from . spanhound --trace-dir ./traces.

To capture a Python agent, install the optional extra and run the agent through the collector:

python -m pip install 'spanhound[auto]'
spanhound run --trace-dir ./traces -- python agent.py

For an already instrumented agent, start the receiver with uvx spanhound collect --trace-dir ./traces, then configure the agent's OTLP exporter to use http://127.0.0.1:4318/v1/traces and the http/protobuf protocol. A Claude Desktop configuration uses the uvx command with spanhound and --trace-dir arguments. The repository also documents use with pi and agent-harness.

Tools and capabilities

The MCP Trace MCP server exposes tools for different investigation tasks:

• list_runs and run_summary identify recent runs and summarize an individual trace.
• span_tree shows the nested execution structure, while slowest_spans ranks spans by duration.
• approval_log records approve, deny, and edit decisions, including the decision maker and rationale.
• token_usage aggregates token and cost information across runs or for one run.
• search_spans finds spans by terms such as tool name, file path, or denial status.
• failure_report returns bounded, redacted errors and failed tool calls.
• tool_stats reports tool volume, error rate, denials, and latency.
• security_audit checks identity, tenant, provenance, risk, and approval evidence.
• recent_activity polls new spans with a cursor, and compare_runs compares selected traces for cost, latency, tokens, tool calls, and failure changes.

The server reads local files; it does not connect to Jaeger, Tempo, or Traceloop backends, and it does not read backend-specific JSON exports. It also does not automatically trace arbitrary agent functions or approvals.