SpanHound

Name: SpanHound
Author: abhishekash

by abhishekashversion 0.6.1i★ –iRuns on your computer

Registry nameio.github.abhishekash/spanhound

Install

Overview

Description from the maker (original English)

Capture local agent traces and inspect failures, approvals, and run comparisons.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Other

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
The registry lists no key to fill in.

You need

PyPIPython’s uv installed (for the uvx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

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

Run this in your terminal

claude mcp add spanhound -- uvx spanhound

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

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

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

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

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account abhishekash, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Otheri

More stars than 0% of the other 32673 servers in this category
Published to the registry more recently than 63% of the other 32673 servers in this category
Basic checks equal to or better than 100% of the other 32673 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is SpanHound safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.6.1) reached the registry 23 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Python (uv) on your computer.

What can I use instead?

In the same category: Spec Driven Development, Remote Desktop Commander, Systemdox

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Spec Driven Development

by formulahendry

MCP Server that facilitates spec-driven development workflows, not just Vibe Coding.

Runs on your computer★ 440MITUpdated 14 months ago

Install

Remote Desktop Commander

by desktop-commander

Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.

Runs in the cloud★ 211Updated 2 days ago

Install

Systemdox

by puglieseweb

Your architecture in your agents' context: checks, specs, ADRs and docs over MCP, at write time.

Runs on your computerUpdated today

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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

Only the beginning is shown; read the rest in the repo

SpanHound

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Otheri

Common questions

Alternatives

Spec Driven Development

Remote Desktop Commander

Systemdox

README from the maker

SpanHound

Try it in one command

Explore the repository fixtures

Capture your own traces

Start your instrumented agent here.

Where it fits

AI-native use cases

Install & run

or, for local development:

Client configuration

Tools

Example session (real fixture trace)

Design