SpanHound
Capture local agent traces and ask an MCP client about failures, approvals and run diffs
- Pricing
- Open source
- Platforms
- CLI, self-hosted, Linux
- Runs
- Locally
- Version
- 0.6.1
- Listing updated
- today
Similar MCP servers
About SpanHound
SpanHound is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
SpanHound (formerly mcp-trace-inspector) records what a Python agent did and lets an assistant answer questions about it from local files, without a trace backend. It can wrap a run with spanhound run to auto-instrument supported OpenAI, Anthropic, OpenAI Agents, HTTPX and Requests calls, or receive OpenTelemetry over a local OTLP/HTTP receiver, and it also reads JSONL spans and OTLP JSON exports.
The tools are read-only. The README maps questions to tools: slowest_spans for stalled runs, approval_log and span_tree to check whether an agent acted after a denial, token_usage, failure_report and tool_stats for failing or slow tools, security_audit for who was allowed to act, recent_activity for polling a live run, and compare_runs for cost, latency and failure deltas between versions. It does not infer intent from final answers.
It began from a shell-boundary regression where a blocked command left no recorded diagnostic. uvx spanhound demo replays a bundled scripted failure with no account or client. It does not read Jaeger, Tempo or Traceloop exports.
Install
Run in a terminal
claude mcp add spanhound -- uvx spanhoundAdd to claude_desktop_config.json
{
"mcpServers": {
"spanhound": {
"command": "uvx",
"args": [
"spanhound"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"spanhound": {
"command": "uvx",
"args": [
"spanhound"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"spanhound": {
"type": "stdio",
"command": "uvx",
"args": [
"spanhound"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"spanhound": {
"command": "uvx",
"args": [
"spanhound"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"spanhound": {
"command": "uvx",
"args": [
"spanhound"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (10)
Taken from the project documentation; the running server may differ.
- list_runs
- Lists captured runs
- slowest_spans
- Longest model or tool spans in a run
- approval_log
- Recorded approval decisions
- span_tree
- Tree of spans for a run
- token_usage
- Run-level token usage totals
- failure_report
- Redacted diagnostics for failures
- tool_stats
- Tool error rates and latency
- security_audit
- Caller, tenant, provenance and risk findings
- recent_activity
- Polls newly written spans
- compare_runs
- Cost, latency, tokens and failure deltas between runs
What it does
- Auto-capture
- Instruments supported Python library calls with one wrapper command.
- OTLP receiver
- Accepts OTLP/HTTP JSON or protobuf on loopback and stores it locally.
- Approval evidence
- Shows recorded approve or deny decisions and what ran afterward.
- Failure diagnostics
- Returns redacted errors, error rates and p95 latency.
- Run comparison
- Compares cost, latency, tokens and tool calls between runs.
- One-command demo
- uvx spanhound demo replays a recorded failure.
Good for
- Find out why yesterday's agent run stalled
- Check whether an agent acted after a write was denied
- See which tool is failing or timing out
- Compare token cost across two model versions
Pricing
Open source
Free from PyPI
SpanHound FAQ
Do I need a trace backend?
No. It reads local JSONL and OTLP JSON files.
What does the demo need?
No clone, account, trace backend or MCP client.
Which libraries are auto-instrumented?
OpenAI, Anthropic, OpenAI Agents, HTTPX and Requests via the optional auto extra.
Can it read Jaeger or Tempo data?
No. It does not read backend-specific exports.
Is SpanHound free?
Yes. SpanHound is open source, so you can use and self-host it for free.
How do I add SpanHound to Claude Code?
Run this command in your terminal: claude mcp add spanhound -- uvx spanhound
What are the best alternatives to SpanHound?
The closest alternatives to SpanHound are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.


