# mcp-trace-inspector [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/abhishekash/mcp-trace-inspector  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-trace-inspector

## Description
Read local agent-run JSONL traces through MCP for failures, approvals, and run comparisons.

## Tools
Capabilities this server exposes over MCP:

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

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## What mcp-trace-inspector MCP server does

The mcp-trace-inspector MCP server, now distributed under the SpanHound project name, receives or reads local agent traces and exposes them through MCP tools. Its inputs are JSONL spans and OTLP JSON exports stored in a local directory. It is intended for investigating agent behavior, rather than providing a graphical trace interface or connecting to a hosted tracing backend.

The available queries cover several investigation paths:

- List recent runs and inspect one run by full ID or prefix.
- View the nested span tree and identify the slowest spans.
- Review approval decisions, including approvals, denials, edits, decision makers, and rationales.
- Aggregate token usage across runs or for an individual run.
- Search spans by tool name, path, or text such as denial messages.
- Find bounded, redacted failures and failed tool calls.
- Rank tools by volume, errors, denials, and latency.
- Audit caller identity, tenant, server provenance, risk, and approval evidence.
- Poll newly written spans and compare selected runs for regressions.

## How it works

The server reads trace files from a directory supplied at startup. It can inspect completed files and poll files that are still being written, but it does not push events to an MCP client or infer intent from an agent's final answer.

For Python agents, the optional `spanhound[auto]` package instruments supported OpenAI, Anthropic, OpenAI Agents, HTTPX, and Requests calls. The agent and the capture command must use the same Python environment. Another option is to run the local OTLP/HTTP receiver and point an already instrumented agent at its loopback endpoint. The receiver accepts OTLP/HTTP JSON or protobuf and stores accepted requests as local JSON files.

## Setup and configuration

Run the packaged command with a trace directory:

```bash
uvx spanhound --trace-dir /path/to/traces
```

Use `--check` to list discovered runs and validate the directory without starting an MCP session. The bundled demonstration can be run with `uvx spanhound demo`; it uses a recorded regression trace and does not require a clone, account, backend, or MCP client.

Configure a stdio MCP client with the command and arguments below, replacing the path:

```json
{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["spanhound", "--trace-dir", "/path/to/traces"]
    }
  }
}
```

Claude Desktop can also install the `.mcpb` asset from a release and select the local trace folder. For OTLP capture, set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to `http://127.0.0.1:4318/v1/traces` and use the `http/protobuf` protocol.

## Limitations and notes

The mcp-trace-inspector MCP server does not automatically trace arbitrary agent functions or approvals. It depends on supported instrumentation, an existing OpenTelemetry exporter, or trace files in one of its documented formats. It does not read backend-specific exports from Jaeger, Tempo, or Traceloop, and it does not provide a hosted trace UI.

The old `mcp-trace-inspector` command should be replaced with `uvx spanhound` for the current release. The project retains its Python import paths and command aliases for clients that explicitly install `spanhound`.

_Full upstream README: https://allmcps.com/mcp/mcp-trace-inspector/readme_