# MCP Trace [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/abhishekash/mcp-trace  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-trace

## Description
Query OpenTelemetry traces from agent runs through MCP.

## 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 MCP server does

The MCP Trace MCP server, distributed in the repository as SpanHound, gives MCP clients a query interface for locally stored traces from agent runs. It is intended for inspecting what an agent did, why a run was slow or failed, how approvals were handled, and how two runs differ. The data source is a local directory containing supported JSONL spans or saved OTLP JSON exports.

The server focuses on evidence recorded in traces rather than interpretation of an agent's final answer. It can return bounded, redacted failure details and failed tool calls, approval decisions with the recorded actor and rationale, token and cost information, and security-related fields such as caller identity, tenant, server provenance, risk, and approval evidence.

## How it works

The MCP Trace MCP server runs as a local stdio process and reads trace files from the directory supplied at startup. It can inspect files that already exist and poll files being written while a run is active. The `recent_activity` tool uses a cursor to find newly written spans; the server does not push events to clients.

Traces can be captured in two supported ways. For Python agents, the optional auto-instrumentation package can run the agent through SpanHound and capture supported calls from OpenAI, Anthropic, OpenAI Agents, HTTPX, and Requests. The agent and capture command must use the same Python environment. For other runtimes, or agents that already export OpenTelemetry data, the local receiver accepts OTLP/HTTP JSON or protobuf on loopback and stores accepted requests as local JSON files. The receiver does not add instrumentation to an agent.

The bundled demo uses a recorded regression trace and does not require a trace backend, account, repository clone, or MCP client. It illustrates a blocked shell call with its diagnostic and approval evidence.

## Setup and configuration

Install and start the server with UV, pointing it at a trace directory:

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

Use `--check` to list discovered runs and validate the directory's complete JSONL or OTLP JSON records without starting an interactive inspection session. A local development checkout can be run with `uvx --from . spanhound --trace-dir ./traces`.

To capture a Python agent, install the optional extra and run the agent through the collector:

```bash
python -m pip install 'spanhound[auto]'
spanhound run --trace-dir ./traces -- python agent.py
```

For an already instrumented agent, start the receiver with `uvx spanhound collect --trace-dir ./traces`, then configure the agent's OTLP exporter to use `http://127.0.0.1:4318/v1/traces` and the `http/protobuf` protocol. A Claude Desktop configuration uses the `uvx` command with `spanhound` and `--trace-dir` arguments. The repository also documents use with pi and agent-harness.

## Tools and capabilities

The MCP Trace MCP server exposes tools for different investigation tasks:

- `list_runs` and `run_summary` identify recent runs and summarize an individual trace.
- `span_tree` shows the nested execution structure, while `slowest_spans` ranks spans by duration.
- `approval_log` records approve, deny, and edit decisions, including the decision maker and rationale.
- `token_usage` aggregates token and cost information across runs or for one run.
- `search_spans` finds spans by terms such as tool name, file path, or denial status.
- `failure_report` returns bounded, redacted errors and failed tool calls.
- `tool_stats` reports tool volume, error rate, denials, and latency.
- `security_audit` checks identity, tenant, provenance, risk, and approval evidence.
- `recent_activity` polls new spans with a cursor, and `compare_runs` compares selected traces for cost, latency, tokens, tool calls, and failure changes.

The server reads local files; it does not connect to Jaeger, Tempo, or Traceloop backends, and it does not read backend-specific JSON exports. It also does not automatically trace arbitrary agent functions or approvals.

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