Name: MCP Trace
Author: abhishekash

Agents that can debug themselves. An MCP server that exposes your agent runs — stored as plain OpenTelemetry JSONL span files — as queryable tools: runs, span trees, slow spans, human-approval logs, token/cost usage.

The idea: observability shouldn't be a dashboard you read after the fact. It should be tools your agent can call mid-run — "why was I slow yesterday?", "what did the human deny me last time?", "which tool keeps timing out?" — or query interactively from Claude Desktop / pi / any MCP client.

Pairs with agent-harness (which writes the traces), but the reader is format-simple: any JSONL of OTel-shaped spans works.

Install & run

The mcp-trace name is occupied on PyPI by an unrelated project, so this server is published as abhishekash-mcp-trace; it exposes both the abhishekash-mcp-trace and mcp-trace commands.

bash

uvx abhishekash-mcp-trace --trace-dir ./traces
# or, for local development:
git clone https://github.com/abhishekash/mcp-trace
cd mcp-trace && uv pip install -e .
mcp-trace --trace-dir ./traces

The package is published on PyPI, and the validated server.json is live in the official MCP Registry.

Client configuration

Claude Desktop (claude_desktop_config.json):

json

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["abhishekash-mcp-trace", "--trace-dir", "/path/to/traces"]
    }
  }
}

pi (~/.pi/agent/settings.json):

json

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["abhishekash-mcp-trace", "--trace-dir", "/path/to/traces"]
    }
  }
}

agent-harness (mounted as gated tools):

bash

harness run "Why was my last run slow?" --mcp "uvx abhishekash-mcp-trace --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", …

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": "f920798dd255…", "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/*.jsonl ──▶ mcp_trace.core (pure query functions, zero deps)
                          │
                   mcp_trace.server (thin MCPServer adapter, mcp 2.x)
                          │
                    stdio (NDJSON JSON-RPC)

core/server split: all logic is pure functions over parsed spans; the MCP layer only parses args and JSON-encodes results. Tests hit both layers.
trace_id prefixes: agents fumble full 32-char hex ids; every tool accepts prefixes.
The demo fixture (examples/example_trace.jsonl) is a real agent-harness run, not hand-written.