mcp-trace-inspector

mcp-trace-inspector is a small, local-first stdio MCP server for querying JSONL OpenTelemetry spans emitted by agent runs. It exposes focused queries for run summaries, tool failures, approvals, activity, and comparisons instead of requiring an application-specific dashboard.

It pairs with agent-harness, but the reader is format-simple: any JSONL of OTel-shaped spans works. 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. mcp-trace-inspector and the harness now preserve and query that bounded error.

AI-native use cases

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 mcp-trace-inspector --trace-dir ./traces
# or, for local development:
git clone https://github.com/abhishekash/mcp-trace-inspector
cd mcp-trace-inspector && uv pip install -e .
mcp-trace-inspector --trace-dir ./traces

Client configuration

Claude Desktop (claude_desktop_config.json):

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

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

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

agent-harness (mounted as gated tools):

harness run "Why was my last run slow?" --mcp "uvx mcp-trace-inspector --trace-dir ./traces"

Tools

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.
• bounded output: diagnostics are truncated and obvious credentials are redacted before query results leave the server.
• honest cost totals: token_usage returns cost_known: false and a null cost when any producer marks pricing as unavailable; unknown pricing is never presented as $0.
• cursor polling: recent_activity makes the snapshot reader useful while a run is still writing spans.
• The demo fixture (examples/example_trace.jsonl) is a real agent-harness run, not hand-written.

Honest limitations

• stdio transport only (Streamable HTTP plus authenticated remote access is the next transport boundary)
• live polling re-reads snapshots; it is not a push subscription
• security audit can only report identity/provenance that the trace producer records
• read-only tools; trace mutation (annotations) is roadmap
• The Python query and server modules are available as mcp_trace; older import and command aliases remain for existing clients.

License

MIT