SpanHound
Capture local agent traces. Ask your MCP client what happened. SpanHound (formerly mcp-trace-inspector) captures supported Python agent calls, receives OpenTelemetry over local OTLP/HTTP, and exposes read-only MCP tools for failures, approval decisions, token usage, and run comparisons. 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
SpanHound demo β recorded agent failure
Tool: run_shell
Failure: error: shell path escapes workspace root: '../outside.txt'
Approval: approve (auto)
Trace: 563e779ee8fa2d7069fc63ed2cf9c8ec (6 spans)
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.
Capture your own traces
For a Python agent, install SpanHound's optional auto instrumentation in the same environment as the agent, then run it through SpanHound:
python -m pip install 'spanhound[auto]'
spanhound run --trace-dir ./traces -- python agent.py
The command starts and stops a local receiver, configures OTLP export, and
captures supported library calls without changes to agent.py. The optional
package includes instrumentation for OpenAI, Anthropic, OpenAI Agents, HTTPX,
and Requests. It reports when no spans were produced. Your Python agent and
SpanHound must share one environment; for a uv project, use
uv add 'spanhound[auto]' and uv run spanhound run -- python agent.py.
See the Python capture guide.
For other runtimes, or agents that already export OpenTelemetry traces, start the receiver in one terminal:
uvx spanhound collect --trace-dir ./traces
Point an agent that already uses an OpenTelemetry trace exporter at the receiver, then run the agent:
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
# Start your instrumented agent here.
SpanHound stores each accepted OTLP/HTTP trace request as a local JSON file.
Run uvx spanhound --trace-dir ./traces --check to see the captured runs, then
connect your MCP client to that folder. The receiver accepts OTLP/HTTP JSON or
protobuf on loopback; it does not add instrumentation to an agent. See the
capture guide for limits and privacy.
Where it fits
For a live terminal and browser view of local Codex/Claude Code sessions and received OTLP telemetry, try Agent Observatory. SpanHound provides trace investigation through MCP using JSONL and OTLP JSON files.
Use this when you want a local trace view through MCP without setting up a trace backend. Capture supported Python library calls in one command, receive OTLP/HTTP from another runtime, or read the supported JSONL or OTLP JSON formats. Focused queries include recorded approval decisions, bounded failure diagnostics, and run comparisons.
MCP Agent Trace Inspector records steps into a local SQLite database and provides a dashboard and exports. SpanHound auto-instruments supported Python libraries or receives OTLP/HTTP traces, then queries the captured files through MCP. It does not automatically trace arbitrary agent functions or approvals.
For traces stored in Jaeger, Tempo, or Traceloop, use a backend-connected tool such as OpenTelemetry MCP Server. For a trace UI, instrumentation, and evaluations, see Phoenix. SpanHound does not read backend-specific JSON exports.
AI-native use cases
| Question during an agent run | MCP tool | Evidence returned |
|---|---|---|
| "Why did yesterday's run stall?" | list_runs β slowest_spans | Run IDs and the longest model or tool spans. |
| "Did the agent act after I denied the write?" | approval_log β span_tree | The recorded decision and subsequent execution path. |
| "How many model tokens did this run use?" | token_usage β span_tree | Run-level usage totals and the span tree for context. |
| "Which tool is failing or timing out?" | failure_report / tool_stats | Redacted diagnostics, error rates, denials, and p95 latency. |
| "Who/what was allowed to act?" | security_audit | Caller, tenant, server provenance, risk, and missing-evidence findings. |
| "What is happening in the run right now?" | recent_activity | Cursor-based polling of newly written spans. |
| "Did this model/version regress?" | compare_runs | Cost, latency, tokens, tool calls, and failure deltas. |
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 install the downloaded file in the client; the download link does not open
a web page. In Claude Desktop, use Settings β Extensions β Advanced settings β
Install Extension⦠and select the .mcpb file. 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 | Use it when |
|---|---|
list_runs | Starting out β recent runs with task, model, duration, cost, decision counts |
run_summary | One run at a glance (accepts trace-id prefix) |
span_tree | "What did the agent actually do?" β nested shape of the run |
slowest_spans | "Why was it slow?" β top-k spans by duration |
approval_log | HITL audit β every approve/deny/edit, who decided, and the rationale |
token_usage | Cost questions β aggregated across runs or per-run |
search_spans | Find spans by tool name, file path, "denied", β¦ |
failure_report | Find actionable, bounded, redacted errors and failed tool calls. |
tool_stats | Rank tools by volume, error rate, denials, and latency. |
security_audit | Audit caller identity, tenant, server provenance, risk, and approval evidence. |
recent_activity | Poll new spans with a cursor while a run is active. |
compare_runs | Compare selected traces for regressions across models or versions. |
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_usagereturnscost_known: falseand 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_activitymakes 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
- MCP 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.
First-run feedback
Tell us what happened when you tried it: your MCP client or trace producer, the question you were trying to answer, and any missing evidence. Share a redacted excerpt when a file fails to load.