MCP Agent Trace Inspector

MCP Agent Trace Inspector

Local-first, MCP-native observability for agent workflows. Every tool call, prompt transformation, latency, token estimate, and cost estimate is recorded in a local SQLite database — no cloud account, no API key, and no traces leaving your machine.

Built specifically for MCP rather than bolted onto a generic LLM proxy.

Tools · Configuration · HTTP transport · Verification · Known limitations · Contributing

Overview

mcp-agent-trace-inspector is an MCP server. Agents call its tools to start a trace, record each step they take, and finish the trace. Humans then inspect summaries, compare runs, export a self-contained HTML dashboard, export OTLP/JSON spans, or stream the compliance audit log.

Agent / MCP client

│ trace_start → trace_step → trace_end ▼ MCP Agent Trace Inspector ├── SQLite (~/.mcp/traces.db) ├── JSONL audit log (~/.mcp/trace-inspector-audit.jsonl) └── tools: summaries, diffs, HTML, OTLP/JSON, retention, alerts

Key features

• Tool-call tracing — inputs, outputs, latency, caller-supplied or automatic token estimates for every step.
• Persistent local storage — SQLite via Node's built-in node:sqlite; traces survive restarts and never require a service.
• Self-contained HTML dashboard — error highlighting, step timeline, latency waterfall, responsive layout, and expandable input/output JSON.
• Cost estimation — offline cl100k_base tokenizer plus a configurable pricing table; no API calls and no billing-account data.
• Trace comparison — aggregate and step-by-step diffs between two runs.
• Reasoning-chain extraction — finds reasoning/thinking/planning steps.
• OTLP/JSON export — standard resourceSpans → scopeSpans → spans documents.
• Compliance audit log — append-only JSONL of recorded steps, exportable as JSON or CSV with date filtering.
• Alerts — persisted latency, error-rate, and cost thresholds evaluated when a trace ends; optional Slack or generic webhook delivery.
• Retention controls — startup purge or explicit archive/delete policy.
• Two transports — stdio (default) and stateless Streamable HTTP with optional API-key/JWT authentication and rate limiting.

Technology stack

Requirements

• Node.js 22.13.0 or newer. node:sqlite first became available in Node 22.5.0 behind --experimental-sqlite; it is unflagged from 22.13.0. This project does not pass the flag.
• npm.
• No database server, API key, or external account is required for core tracing.

Quick start (MCP client)

Add the server to your MCP client configuration:

{

"mcpServers": { "trace-inspector": { "command": "npx", "args": ["-y", "mcp-agent-trace-inspector@latest"] } } }

Use a project-specific database:

{

"mcpServers": { "trace-inspector": { "command": "npx", "args": [ "-y", "mcp-agent-trace-inspector@latest", "--db=~/traces/my-project.db" ] } } }

Then ask your agent to trace its own work:

Start a trace named "test-run" with trace_start.

Record a trace_step for each tool you call, including that tool's input and output. Call trace_end when you are done, then call get_trace_summary for the trace.

The summary contains the step count, estimated token total, total recorded latency, wall-clock duration, cost estimate, and reasoning-chain detection. Tracing is explicit: the inspector records steps when the agent calls trace_step; it does not intercept other MCP servers automatically.

From source

npm ci

npm run build node dist/index.js --db=~/.mcp/traces.db

Development mode runs TypeScript directly and logs MCP protocol messages on stderr:

npm run dev -- --db=/tmp/traces.db

Streamable HTTP transport

HTTP mode is useful for a local team instance or a container. It is stateless: every POST gets a fresh MCP server and transport, there is no Mcp-Session-Id, and the endpoint does not offer a server-initiated SSE stream. Send every JSON-RPC message as its own POST /mcp request.

node dist/index.js --db=~/.mcp/traces.db --http-port=3000 --http-host=127.0.0.1

stderr: MCP Agent Trace Inspector HTTP server listening on http://127.0.0.1:3000/mcp

Initialize the endpoint:

curl -s http://127.0.0.1:3000/mcp \

-H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

The response is an SSE frame. Call a tool:

curl -s http://127.0.0.1:3000/mcp \

-H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_traces","arguments":{}}}'

HTTP authentication

Set one or both environment variables before starting the server:

MCP_API_KEY=change-me \

MCP_JWT_SECRET=change-me-too \ node dist/index.js --http-port=3000 --http-host=127.0.0.1

• If MCP_API_KEY is set, every HTTP request must send X-API-Key: .
• If MCP_JWT_SECRET is set, every HTTP request must send Authorization: Bearer ; exp and nbf claims are checked.
• If both are set, both are required.
• The stdio transport ignores both variables.

--http-host=0.0.0.0 is allowed but the server warns. Put TLS and an authenticating reverse proxy in front of any non-loopback deployment; do not expose the raw endpoint to an untrusted network.

When the server is bound to loopback behind a reverse proxy, the proxy must rewrite the Host header to 127.0.0.1: . The loopback DNS-rebinding guard rejects other Host values with 403 by design.

Configuration

CLI flags

Environment variables

The server does not load .env files automatically. Export variables in your shell or configure them in your MCP client.

See .env.example for a copy-paste template. Never commit real secrets or database files; both are ignored by .gitignore.

Tools

The server exposes 13 tools. Tool annotations mark state-changing tools (readOnlyHint: false) and destructive retention (destructiveHint: true).

Trace lifecycle

trace_step requires trace_id, tool_name, input (object), and output (object). token_count must be a non-negative integer; latency_ms must be a finite, non-negative number. Caller-supplied token counts are used as-is.

Inspection

| compare_traces | Diff two traces: aggregates, tool coverage, and per-position steps.