MCP Trace

io.github.abhishekashv0.1.1Updated Oct 8, 2026

Query OpenTelemetry traces from agent runs through MCP.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & MonitoringData & Analytics

Overview

AI-generated overview

Lets an assistant query local OpenTelemetry agent-run trace files for runs, span trees, slow spans, approvals, and token costs.

What it does
Reads plain OpenTelemetry JSONL span files from a trace directory and exposes them as queryable tools. Tools include list_runs, run_summary, span_tree, slowest_spans, approval_log, token_usage, and search_spans, covering recent runs, nested span shapes, slowest spans, human approve/deny/edit decisions, and aggregated or per-run token and cost usage. Trace IDs can be given as prefixes. All tools are read-only in this version.
When to use it
Useful when an assistant should inspect its own or another agent's past runs mid-conversation, for example to explain slowness, find repeatedly timing out tools, or audit human approval decisions. It fits setups that already produce OTel-shaped JSONL spans, such as agent-harness, or any compatible trace files.
Requirements
A local Python runtime with uv/uvx to run the PyPI package abhishekash-mcp-trace over stdio, plus a path to a directory of OTel-shaped JSONL trace files passed as --trace-dir. No accounts, API keys, or network access are declared. Desktop client configuration is shown for Claude Desktop and pi.
Before you install
The server reads trace files from the configured directory, so point it only at traces you are comfortable exposing to the assistant; traces may contain task text, file paths, tool arguments, and approval rationales. It is read-only in v0.1, but trace mutation is on the roadmap. The trace directory scan is non-recursive and results are snapshots at call time, not live.

Installation

In SourceWeft

  1. Open MCP Trace in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-trace

[CI] [License: MIT]

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-tracecd 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

ToolUse it when
list_runsStarting out — recent runs with task, model, duration, cost, decision counts
run_summaryOne 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_logHITL audit — every approve/deny/edit, who decided, and the rationale
token_usageCost questions — aggregated across runs or per-run
search_spansFind 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

Source: README.md at commit 65966f5

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.1LatestOct 8, 2026