SpanHound

Inspect recorded agent-run failures and approvals from local trace files. SpanHound (formerly mcp-trace-inspector) is a read-only stdio MCP server for inspecting local agent-run traces, including tool failures, approval decisions, and changes between runs. It reads JSONL spans and OTLP JSON exports as described in the user guide, including traces from agent-harness.

Demo: Watch the full 48-second video · Read the reproducible story. This is a scripted regression trace, not a live-model benchmark.

The project's concrete origin was a shell-boundary regression: the harness blocked cat ../outside.txt, but the old trace recorded only that run_shell was called, not the returned diagnostic. SpanHound and the harness now preserve and query that bounded error.

Try it in one command

uvx spanhound demo

The demo shows a recorded run_shell failure and its approval evidence from a bundled scripted regression trace. It needs no clone, account, trace backend, or MCP client. To inspect your own traces, point SpanHound at a directory of JSONL spans or saved OTLP JSON exports:

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

--check prints the runs it found and exits. Connect an MCP client with the configuration below to ask questions about those runs.

Explore the repository fixtures

git clone https://github.com/abhishekash/spanhound.git
cd spanhound
uvx --from . spanhound --trace-dir examples --check

--check also reports a missing directory or malformed complete JSONL or OTLP JSON record.

To try an OTLP JSON export, run the same command with --trace-dir tests/fixtures. The sample export includes a model call, token usage, a tool call, and an exception.

Where it fits

Use this when your agent already writes the supported JSONL span format or OTLP JSON export and you want an MCP client to inspect those files without setting up a trace backend. Its focused queries include recorded approval decisions, bounded failure diagnostics, and comparisons between selected runs.

MCP Agent Trace Inspector records steps into a local SQLite database and provides a dashboard and exports. Use it when you need trace capture. This project reads trace files written by an existing producer, including agent-harness; it does not record the agent's actions itself.

For traces stored in Jaeger, Tempo, or Traceloop, use a backend-connected tool such as OpenTelemetry MCP Server. For standard OTLP traces with a local receiver, see otel-mcp. For a trace UI, instrumentation, and evaluations, see Phoenix. This project reads saved OTLP/JSON trace exports. It does not receive live OTLP traffic or read backend-specific JSON exports.

AI-native use cases

The tools read stored traces and can poll files being written, but they do not push events or infer intent from the final answer. Start with the installation and user guide, then see the real trace fixture and the tool descriptions for the query contract.

Install & run

uvx spanhound --trace-dir ./traces
# or, for local development:
git clone https://github.com/abhishekash/spanhound
cd spanhound
uvx --from . spanhound --trace-dir ./traces

For a desktop client that accepts MCP Bundles, download the .mcpb asset from the latest release and open it in the client. The bundle asks you to choose a local trace folder. It uses UV to install its Python dependencies on first run. SpanHound reads the folder locally; the connected client receives the evidence returned by its MCP tools.

If you previously ran uvx mcp-trace-inspector, change that command to uvx spanhound to receive this release. The old PyPI distribution stays at 0.3.1; the new package retains its Python import paths and command aliases for clients that install spanhound explicitly.

Client configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["spanhound", "--trace-dir", "/path/to/traces"]
    }
  }
}

pi (~/.pi/agent/settings.json):

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["spanhound", "--trace-dir", "/path/to/traces"]
    }
  }
}

agent-harness (mounted as gated tools):

harness run "Why was my last run slow?" --mcp "uvx spanhound --trace-dir ./traces"

Tools

Tool descriptions are written as prompts (when-to-use, not just what-it-does) — descriptions are the interface for agent-called tools.

Example session (real fixture trace)

> list_runs
[{ "trace_id": "f920798dd2558fcb84f9977736432a8b", "task": "Summarize the workspace's notes…",
   "tool_calls": 4, "human_decisions": 2, "stopped_reason": "completed" }]

> approval_log
[{ "tool": "write_file", "decision": "approve", "approver": "auto", … },
 { "tool": "run_shell",  "decision": "approve", "approver": "auto", … }]

Design

traces/*.jsonl ──┐
traces/*.json  ──┴─▶ mcp_trace.core (local query functions)
                          │
                   mcp_trace.server (MCP adapter)
                          │
                    stdio (JSON-RPC)

• core/server split: all logic is pure functions over parsed spans; the MCP layer only parses args and JSON-encodes results. Tests hit both layers.
• trace_id prefixes: agents fumble full 32-char hex ids; every tool accepts prefixes.
• bounded output: diagnostics are truncated and obvious credentials are redacted before query results leave the server.
• honest cost totals: token_usage returns cost_known: false and a null cost when any model span lacks a cost or marks pricing as unavailable; unknown pricing is never presented as $0.
• cursor polling: recent_activity makes the snapshot reader useful while a run is still writing spans.
• The demo fixture (examples/example_trace.jsonl) is a real agent-harness run, not hand-written.

Honest limitations

• stdio transport only (Streamable HTTP plus authenticated remote access is the next transport boundary)
• live polling re-reads snapshots; it is not a push subscription
• security audit can only report identity/provenance that the trace producer records
• read-only tools; trace mutation (annotations) is roadmap
• The Python query and server modules are available as mcp_trace; older import and command aliases remain for existing clients.

License

MIT