Skip to content
MCP server

SpanHound

Capture local agent traces and ask an MCP client about failures, approvals and run diffs

Runs locallyStatus and history
Install
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 spanhound

Add to claude_desktop_config.json

{
  "mcpServers": {
    "spanhound": {
      "command": "uvx",
      "args": [
        "spanhound"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "spanhound": {
      "command": "uvx",
      "args": [
        "spanhound"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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.

How AIPoweredBot checks servers