@agent-inspect/mcp-server
Read-only MCP server for the local coding-agent debug loop: list runs, summarize failures, inspect trees, evaluate contracts, and fetch TraceFacts (get_trace_facts) — without invoking agent tools or mutating traces.
Support level: Preview — see SUPPORT-LEVELS.md.
When to use
- Let Cursor, Claude Code, Codex, Gemini, or other MCP clients inspect local
.agent-inspect/evidence - Debug failed trajectories with the same TraceFacts used by CLI checks
When not to use
- Invoking target-app tools through MCP
- Uploading traces to a remote MCP host / collector
- Expecting the server to edit application code
Install
npm install @agent-inspect/mcp-server
# optional helper:
npx agent-inspect mcp configure --client cursor
Example
npx @agent-inspect/mcp-server --dir .agent-inspect
Flagship tools (read-only)
| Tool | Role |
|---|---|
list_recent_runs / list_recent_failures | Browse local runs |
get_run_summary / get_execution_tree | Bounded summaries |
get_first_causal_failure | Deterministic first causal failure |
get_contract_failures | TraceContract / check failures |
get_trace_facts | TraceFacts / semantic parity summary |
compare_runs | Structural diff |
create_share_checked_evidence | Share-gated Evidence package |
First causal failure ambiguity
Unlinked failures remain unrelated. get_first_causal_failure does not infer
causal parents from event adjacency or timing alone, so ambiguous relationships
remain explicit rather than being fabricated.
Results are redacted (share profile by default), bounded, and deterministic for the same inputs.
Every tools/list entry includes MCP hint annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Hints are not authorization or attestation—see MCP.md.
Privacy
- Reads local trace directory only
- Tool results go through a share-profile redaction / size boundary
- Exposes configured local evidence to the connected MCP client — treat that client as a trust boundary
- No trace mutation; no agent tool invocation; no default upload
Limitations
- Preview surface — tool catalog and bounds may evolve
- Not a gateway or remote upload service
- Not a substitute for hosted APM
Docs
Troubleshooting
- Empty resources: Confirm
--dirpoints at JSONL traces - Security: Do not expose server beyond localhost without redaction review
Version
Part of the fixed AgentInspect release line. See the npm badge / package manifest for the current version.
License
MIT