SpanHound

What SpanHound MCP server does

SpanHound MCP server provides local inspection of traces produced by agent runs. It focuses on evidence recorded in spans rather than interpreting an agent's final response. Developers can examine nested execution paths, tool calls, model activity, approval decisions, bounded error details, token usage, and differences between selected runs.

The project is intended for the 💻 Developer Tools category and is useful when a local workflow needs trace queries through MCP without a hosted observability backend. It can work with traces from supported Python libraries, agents that already export OpenTelemetry data, and the formats documented by the project: JSONL spans and OTLP JSON exports.

How it works

SpanHound MCP server runs locally and reads trace files from a directory. Its MCP process communicates over stdio, while a separate collection mode accepts OTLP/HTTP trace requests on loopback using JSON or protobuf. Accepted requests are stored as local JSON files. The server can query files that are already present and poll files being written during an active run.

For Python agents, the optional spanhound[auto] package instruments supported calls from OpenAI, Anthropic, OpenAI Agents, HTTPX, and Requests. The spanhound run command starts the local receiver, configures OTLP export, runs the agent, and stops the receiver. The agent and SpanHound need to use the same Python environment for this mode. Other runtimes must already have OpenTelemetry trace export configured; SpanHound does not add instrumentation for them.

Setup and configuration

Install and start the MCP process with uvx spanhound --trace-dir /path/to/traces. The trace directory can contain JSONL spans or saved OTLP JSON exports. Add the same command and directory to an MCP client configuration. Claude Desktop is documented as a supported client, using uvx with spanhound and the --trace-dir argument.

To capture a Python agent, install spanhound[auto] and run spanhound run --trace-dir ./traces -- python agent.py. For an already instrumented agent, run uvx spanhound collect --trace-dir ./traces and export traces to http://127.0.0.1:4318/v1/traces with the OTLP HTTP/protobuf protocol. The bundled uvx spanhound demo command provides a recorded failure example without requiring a client, account, or trace backend.

Tools and capabilities

The SpanHound MCP server exposes tools for:

• Listing recent runs and summarizing an individual run.
• Viewing a run's nested span tree and ranking its slowest spans.
• Reviewing approval, denial, and edit decisions with the recorded actor and rationale.
• Aggregating token usage across runs or for one run.
• Searching spans by terms such as tool names, file paths, or denial markers.
• Reporting redacted failures and failed tool calls.
• Ranking tools by volume, errors, denials, and latency.
• Auditing caller identity, tenant, server provenance, risk, and approval evidence.
• Polling newly written spans with a cursor.
• Comparing cost, latency, tokens, tool calls, and failure changes across runs.

Limitations and notes

SpanHound MCP server queries stored trace evidence; it does not push events or infer intent from an agent's final answer. Automatic capture is limited to the supported Python instrumentation packages. It does not automatically trace arbitrary agent functions or approvals.

The project is designed for local files, not backend-specific exports from Jaeger, Tempo, or Traceloop. Use a backend-connected tool for those sources. The receiver accepts OTLP/HTTP on loopback, and the captured data remains in the configured local trace directory. The repository also notes that malformed complete JSONL or OTLP JSON records and missing trace directories are reported by --check.