MCP Trace

mcp-trace

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.

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):

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

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

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

agent-harness (mounted as gated tools):

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.

Honest limitations

• stdio transport only (no Streamable HTTP yet)
• non-recursive trace-dir scan; very large dirs should use per-file loading
• no span streaming/watching — snapshots at call time
• v0.1: read-only tools; trace mutation (annotations) is roadmap

License

MIT