MCP Agent Trace Inspector

Step-by-step observability for MCP agent workflows — trace, inspect, and debug multi-step agent executions

Local-first, MCP-native observability for agent workflows. Every tool call, prompt transformation, latency, and token count is recorded in a local SQLite database — no cloud account, no API key, no traces leaving your machine. Built specifically for MCP rather than bolted onto a generic LLM proxy.

Tool reference|Configuration|Contributing|Troubleshooting|Design principles

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

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

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

Enter the following in your MCP client to verify everything is working:

Start a trace called "test-run", then list the files in the current directory, then end the trace and show me the summary.

Your client should return a summary showing step count, total tokens, and latency.

- trace_start— begin a new trace; returns atrace_idfor subsequent calls
- trace_step— record one tool call step (inputs, outputs, optional token count and latency)
- trace_end— mark a trace as completed

- list_traces— list stored traces with names, statuses, and timestamps
- get_trace_summary— token totals, step count, latency, and cost estimate for a trace
- compare_traces— diff two traces side by side (step counts, tokens, latency)
- extract_reasoning_chain— extract only reasoning/thinking steps from a trace

- export_dashboard— generate a self-contained single-file HTML dashboard with latency waterfall
- export_otel— export one or all traces in OpenTelemetry OTLP JSON span format
- export_compliance_log— export the compliance audit log as JSON or CSV, with optional date range filtering

- configure_alerts— configure alert rules on latency, error rate, or cost; fire to Slack or generic webhooks
- set_retention_policy— set how many days to keep traces (in-memory; must be called beforeapply_retention)
- apply_retention— archive traces older than the configured threshold; delete traces past 2x the threshold

Path to the SQLite database file used to store traces.

Automatically delete traces older than N days. Set to0to disable.

Path to a JSON file containing custom model pricing ($/1K tokens). Overrides the built-in table.

Disable tiktoken-based token counting. Traces will omit token usage metrics.

Pass flags via theargsproperty in your JSON config:

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

- Append-only traces: Steps are immutable once recorded. Trust requires integrity.
- Local-first: All core functionality works without a network connection.
- Portable dashboards: HTML exports are always single-file; no server required to view them.

Before publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.

npm run build && npm run inspect

# List all tools npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list # List resources and prompts npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list # Call a tool (example — replace with a relevant read-only tool for this plugin) npx @modelcontextprotocol/inspector --cli node dist/index.js \ --method tools/call --tool-name list_traces # Call a tool with arguments npx @modelcontextprotocol/inspector --cli node dist/index.js \ --method tools/call --tool-name list_traces --tool-arg key=value

Run before publishing to catch regressions in tool registration and runtime startup.

SeeCONTRIBUTING.mdfor full contribution guidelines.

MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent