# SpanHound

> SpanHound is an open-source MCP server for developer tools. Capture local agent traces and ask an MCP client about failures, approvals and run diffs. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Linux, macOS, Windows
- **Repository:** https://github.com/abhishekash/spanhound
- **MCP Registry name:** io.github.abhishekash/spanhound
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add spanhound -- uvx spanhound
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "spanhound": {
      "command": "uvx",
      "args": [
        "spanhound"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "spanhound": {
      "command": "uvx",
      "args": [
        "spanhound"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "spanhound": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "spanhound"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "spanhound": {
      "command": "uvx",
      "args": [
        "spanhound"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "spanhound": {
      "command": "uvx",
      "args": [
        "spanhound"
      ]
    }
  }
}
```

## Tools

- `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

## 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.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/spanhound
