# Agent Trace MCP Server

Open-source MCP server owned by **Pawan Gunjkar** (`pawangunjkar@gmail.com` · [GitHub](https://github.com/Pawangunjkar)). MIT licensed.

This is the trace log for agents, not for Java services. Prometheus and Loki show the commerce suite. This server shows which agent called which MCP tool, how long it took, whether the tool failed, and how many tokens the turn used.

Sibling servers: [observability-mcp](https://github.com/Pawangunjkar/observability-mcp), [github-mcp](https://github.com/Pawangunjkar/github-mcp), [deps-mcp](https://github.com/Pawangunjkar/deps-mcp).

## Project information

| Item | Value |
| --- | --- |
| Package | `pawangunjkar-agent-trace-mcp` |
| Runtime | Python 3.10+, FastMCP, stdio |
| Store | Local JSONL, default `~/.agent-trace-mcp/traces.jsonl` |
| Write | `trace_record` appends one span |
| Reads | runs, one run, failed tools, token totals, slowest spans |

Pass the same `run_id` for every tool in one user turn. Keep secrets out of `args_preview`. The preview is truncated to 300 characters.

## Architecture

```mermaid
flowchart TB
  subgraph L1["Layer 1 — Agent"]
    AG["LangGraph CommerceAgent"]
    HUB["McpHub.call"]
  end

  subgraph L2["Layer 2 — MCP"]
    SRV["agent-trace-mcp"]
  end

  subgraph L3["Layer 3 — Store"]
    FILE["traces.jsonl"]
  end

  subgraph L4["Layer 4 — Questions"]
    RUNS["trace_list_runs"]
    FAIL["trace_failed_tools"]
    COST["trace_token_cost"]
  end

  AG --> HUB
  HUB -->|"trace_record"| SRV
  SRV --> FILE
  FILE --> RUNS
  FILE --> FAIL
  FILE --> COST
```

```mermaid
flowchart LR
  START["User turn"] --> REC["trace_record per tool"]
  REC --> FILE["JSONL span"]
  FILE --> ASK["Which checkout step failed?"]
  ASK --> GET["trace_get_run"]
```

## Tools

| Tool | What it does |
| --- | --- |
| `trace_record` | Append agent, tool, latency, ok, error, tokens |
| `trace_list_runs` | Recent runs with span, error, and token counts |
| `trace_get_run` | Every span for one `run_id` |
| `trace_failed_tools` | Spans with `ok=false` |
| `trace_token_cost` | Sum tokens for one run or the whole file |
| `trace_slowest_tools` | Highest `latency_ms` |
| `trace_status` | File path and totals |

## Cursor

```json
{
  "mcpServers": {
    "agent-trace": {
      "command": "uv",
      "args": ["run", "--directory", "C:/AI_Workspaces/Anti_Workspace/agent-trace-mcp", "server.py"],
      "env": {
        "TRACE_FILE": "C:/AI_Workspaces/Anti_Workspace/agent-trace-mcp/traces.jsonl"
      }
    }
  }
}
```

After a commerce-agent scenario, record one span per MCP call. Example: agent `checkout`, tool `order-orchestrator.place_order`, `ok=false`, error text from the tool JSON.