{
  "markdown": "# MCP Agent Trace Inspector\n\nnpm `mcp-agent-trace-inspector` package\n\nLocal-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.\n\n[Tool reference](#tools) | [Configuration](#configuration) | [Contributing](#contributing) | [Troubleshooting](#troubleshooting) | [Design principles](#design-principles)\n\n## Key features\n\n- **Tool call tracing**: Captures inputs, outputs, latency, and token usage for every step in a workflow.\n- **Persistent storage**: Traces survive session restarts; stored locally in SQLite with no external dependencies.\n- **HTML dashboard**: Generates a self-contained single-file dashboard with an interactive step timeline.\n- **Token cost estimation**: Calculates USD cost per trace using a configurable model pricing table — no API calls required.\n- **Trace comparison**: Diff two traces side by side to measure the impact of prompt or tool changes.\n- **Low overhead**: Adds less than 5ms per step; never becomes the bottleneck.\n\n## Why this over LangSmith / AgentOps?\n\n|                 | mcp-agent-trace-inspector                        | LangSmith / AgentOps                          |\n| --------------- | ------------------------------------------------ | --------------------------------------------- |\n| Data location   | Local SQLite — never leaves your machine         | Cloud-hosted; traces sent to external servers |\n| Setup           | `npx` one-liner, zero config                     | Account signup, API key, SDK instrumentation  |\n| MCP-aware       | Native — records tool calls as first-class steps | Generic LLM proxy; MCP structure is opaque    |\n| Run diffs       | Built-in `compare_traces` diff                   | Separate paid feature or manual export        |\n| Cost estimation | Offline tiktoken + configurable pricing table    | Requires live API traffic through their proxy |\n| Overhead        | <5ms per step                                 | Network round-trip per event                  |\n\nIf your traces contain sensitive tool outputs, proprietary prompts, or data that must stay on-device, this is the right tool. If you need cross-team trace sharing or a managed SaaS, use LangSmith.\n\n## Disclaimers\n\n`mcp-agent-trace-inspector` stores tool call inputs and outputs locally in a SQLite database. Traces may contain sensitive information passed to or returned from your tools. Review trace contents before sharing dashboard exports. Traces are not automatically transmitted; optional alert webhooks are available.\n\n## Requirements\n\n- Node.js v22.5.0 or newer.\n- npm.\n\n## Getting started\n\nAdd the following config to your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"trace-inspector\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-agent-trace-inspector@latest\"]\n    }\n  }\n}\n```\n\nTo set a custom storage path:\n\n```json\n{\n  \"mcpServers\": {\n    \"trace-inspector\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-agent-trace-inspector@latest\",\n        \"--db=~/traces/my-project.db\"\n      ]\n    }\n  }\n}\n```\n\n### MCP Client configuration\n\nAmp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed\n\n## Your first prompt\n\nEnter the following in your MCP client to verify everything is working:\n\n```\nStart a trace called \"test-run\", then list the files in the current directory, then end the trace and show me the summary.\n```\n\nYour client should return a summary showing step count, total tokens, and latency.\n\n## Tools\n\n### Trace lifecycle (3 tools)\n\n- `trace_start` — begin a new trace; returns a `trace_id` for subsequent calls\n- `trace_step` — record one tool call step (inputs, outputs, optional token count and latency)\n- `trace_end` — mark a trace as completed\n\n### Inspection (4 tools)\n\n- `list_traces` — list stored traces with names, statuses, and timestamps\n- `get_trace_summary` — token totals, step count, latency, and cost estimate for a trace\n- `compare_traces` — diff two traces side by side (step counts, tokens, latency)\n- `extract_reasoning_chain` — extract only reasoning/thinking steps from a trace\n\n### Export (3 tools)\n\n- `export_dashboard` — generate a self-contained single-file HTML dashboard with latency waterfall\n- `export_otel` — export one or all traces in OpenTelemetry OTLP JSON span format\n- `export_compliance_log` — export the compliance audit log as JSON or CSV, with optional date range filtering\n\n### Operations (3 tools)\n\n- `configure_alerts` — configure alert rules on latency, error rate, or cost; fire to Slack or generic webhooks\n- `set_retention_policy` — set how many days to keep traces (in-memory; must be called before `apply_retention`)\n- `apply_retention` — archive traces older than the configured threshold; delete traces past 2x the threshold\n\n## Configuration\n\n### `--db` / `--db-path`\n\nPath to the SQLite database file used to store traces.\n\nType: `string`\nDefault: `~/.mcp/traces.db`\n\n### `--retention-days`\n\nAutomatically delete traces older than N days. Set to `0` to disable.\n\nType: `number`\nDefault: `0`\n\n### `--pricing-table`\n\nPath to a JSON file containing custom model pricing ($/1K tokens). Overrides the built-in table.\n\nType: `string`\n\n### `--no-token-count`\n\nDisable tiktoken-based token counting. Traces will omit token usage metrics.\n\nType: `boolean`\nDefault: `false`\n\nPass flags via the `args` property in your JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"trace-inspector\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-agent-trace-inspector@latest\", \"--retention-days=30\"]\n    }\n  }\n}\n```\n\n## Design principles\n\n- **Append-only traces**: Steps are immutable once recorded. Trust requires integrity.\n- **Local-first**: All core functionality works without a network connection.\n- **Portable dashboards**: HTML exports are always single-file; no server required to view them.\n\n## Verification\n\nBefore publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.\n\n**Interactive UI** (opens browser):\n\n```bash\nnpm run build && npm run inspect\n```\n\n**CLI mode** (scripted / CI-friendly):\n\n```bash\n# List all tools\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list\n\n# List resources and prompts\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list\n\n# Call a tool (example — replace with a relevant read-only tool for this plugin)\nnpx @modelcontextprotocol/inspector --cli node dist/index.js \\\n  --method tools/call --tool-name list_traces\n\n# Call a tool with arguments\nnpx @modelcontextprotocol/inspector --cli node dist/index.js \\\n  --method tools/call --tool-name list_traces --tool-arg key=value\n```\n\nRun before publishing to catch regressions in tool registration and runtime startup.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full contribution guidelines.\n\n```bash\nnpm install && npm test\n```\n\n## MCP Registry & Marketplace\n\nThis plugin is available on:\n\n- [MCP Registry](https://registry.modelcontextprotocol.io)\n- [MCP Market](https://mcpmarket.com)\n\nSearch for `mcp-agent-trace-inspector`.\n",
  "bytes": 7339,
  "sha": "6ec340eced3615c7bf5f675553b96485d3f375c4a8749be0d1a10f9cbe6c9890",
  "repo_slug": "dbsectrainer/mcp-agent-trace-inspector",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dbsectrainer_mcp_agent_trace_i_518c6b0d/readme"
}