mcp-trace-inspector MCP server

mcp-trace-inspector

<!-- mcp-name: io.github.abhishekash/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.

Release status: The 0.3.0 GitHub release is available, but the new PyPI

distribution is pending Trusted Publisher registration. Until publication

succeeds, install from this checkout; uvx mcp-trace-inspector will not work.

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 (claudedesktopconfig.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

Shortened. The full README is on GitHub.