Agent Inspect MCP Server

<p align="center"> <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/agent-inspect-logo-mark.svg?sanitize=true" width="56" height="56" alt="AgentInspect"> </p> <p align="center"><strong>agent-inspect</strong></p> <p align="center">Local-first evidence for TypeScript AI agents</p> <h1 align="center"> See what your agent did.<br> Catch the wrong path in CI.<br> Keep the evidence local. </h1> <p align="center"> AgentInspect turns TypeScript agent runs into readable execution trees, deterministic trajectory checks, and portable Evidence v2—without requiring an account, collector, or default upload. </p> <p align="center"><strong>Capture once. Debug, prevent, and share from the same local trace.</strong></p> <p align="center">_{No account · no collector · no default upload · metadata-only by default}</p> <p align="center"> <a href="https://agentinspect.vercel.app/">Website</a> · <a href="https://agentinspect.vercel.app/docs/">Docs</a> · <a href="https://www.npmjs.com/package/agent-inspect">npm</a> · <a href="https://github.com/rajudandigam/agent-inspect">GitHub</a> </p> <p align="center"> <a href="https://www.npmjs.com/package/agent-inspect"><img src="https://img.shields.io/npm/v/agent-inspect.svg" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a> <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js 20 or newer"></a> </p>

Support level: Stable — see SUPPORT-LEVELS.md. Network behavior: NETWORK-BEHAVIOR.md.

npm install agent-inspect

<p align="center"> <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/debug-tree.gif" alt="AgentInspect lists a local demo-good run, then you inspect the execution tree from the same JSONL" width="900"> </p>

Agent code rarely fails as one function call. It plans, retrieves, calls tools, invokes a model, retries, and produces side effects. Flat logs show fragments. AgentInspect keeps the run as local JSONL and gives you one evidence loop from the same trace.

<p align="center"> <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/readme-product-loop.svg?sanitize=true" alt="Capture one local trace, then debug, prevent, and share from the same evidence loop" width="900"> </p>

One trace. Three jobs.

Debug — read the execution path

See nested steps, tool calls, LLM calls, model and token metadata, durations, errors, and the first causal failure without sending the trace to an AgentInspect service.

npx agent-inspect view <run-id> --dir .agent-inspect --summary
npx agent-inspect report <run-id> --dir .agent-inspect
npx agent-inspect explain <run-id> --dir .agent-inspect

Use manual instrumentation, official adapters, supported standards files, or structured logs you already emit.

Prevent — fail CI on the wrong trajectory

<p align="center"> <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/check-pass-fail.gif" alt="The same deterministic AgentInspect check exits zero for demo-good and one for demo-regression" width="900"> </p>

Checks are deterministic and provider-free: the same trace and rules produce the same result. Start with a preset, then extend it with the expectations that matter to the workflow.

npx agent-inspect check <run-id> --dir .agent-inspect \
  --preset trajectory \
  --required-tool retrieve_policy

Use --fail-on-observation failed only when the run records explicit OUTCOME events (for example the broken-agent-debugging starter). Trajectory checks do not invent outcomes from tool/LLM/run success.

A passing check exits 0; a rule failure exits 1. Invalid configuration and unreadable/unsupported inputs use separate documented exit codes. Use TraceContract, suites, cohorts, Vitest/Jest reporters, or --evidence-on fail when the workflow needs more than one CLI check.

Share — create reviewable offline evidence

<p align="center"> <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/evidence-bundle.gif" alt="AgentInspect writes a share-checked Evidence v2 bundle to ./evidence and verifies the listed file hashes offline" width="900"> </p>

npx agent-inspect verify-safe <run-id> --dir .agent-inspect
npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
npx agent-inspect bundle verify ./evidence

verify-safe is a best-effort local assessment and can report SAFE, SAFE WITH WARNINGS, UNSAFE, or UNKNOWN. bundle writes a redacted artifact and manifest; bundle verify rechecks the listed file hashes offline. “Share-checked” is not compliance certification—review the artifact before attaching it to a PR, incident, or support handoff.

First local trace

The generated demo is synthetic, keyless, and local. npm install agent-inspect does not copy repository examples; init writes them into the project.

npm install agent-inspect
npx agent-inspect init --yes
node examples/agent-inspect-demo.mjs
npx agent-inspect list --dir .agent-inspect

Copy the printed run ID, then inspect it:

npx agent-inspect view <run-id> --dir .agent-inspect --summary
npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory
npx agent-inspect verify-safe <run-id> --dir .agent-inspect

For a fixed good/regression/PII walkthrough with stable run ids (demo-good, demo-regression, demo-pii), use the canonical keyless showcase. The richer blessed starters cover framework-specific paths.

Use it with your stack

Stack	Install / command	Start
Custom functions or classes	agent-inspect	Getting started
LangChain / LangGraph	agent-inspect + @agent-inspect/langchain	LangGraph guide
AI SDK	agent-inspect + @agent-inspect/ai-sdk	AI SDK guide
OpenAI Agents JS	agent-inspect + @agent-inspect/openai-agents	Local processor guide
Existing structured logs	npx agent-inspect logs ...	Log-to-tree quickstart
OpenInference / OTLP JSON	npx agent-inspect open ...	Standards
Vitest / Jest CI	@agent-inspect/vitest / @agent-inspect/jest	CI artifacts

See support levels for Stable, Supported, Beta, Preview, and Experimental surfaces.

Programmatic trajectory checks

import { openTraceFile } from "agent-inspect/readers";
import {
  defineTraceContract,
  evaluateTraceContractRead,
} from "agent-inspect/checks";

const read = await openTraceFile("./trace.jsonl");
const contract = defineTraceContract({
  run: { requireCompleted: true },
  tools: { required: ["retrieve_policy"] },
});

const result = evaluateTraceContractRead(read, contract);
if (result.status !== "pass") process.exitCode = 1;

The full API also exposes TraceFacts for bounded, logical analysis of supported traces. See programmatic trace analysis.

Where AgentInspect fits

AgentInspect owns the laptop-to-PR evidence loop. It complements hosted observability, production trace retention, and broad eval platforms rather than replacing them.

Need	Best fit
Inspect one local TypeScript agent run immediately	AgentInspect
Enforce deterministic tool/order/completion expectations in CI	AgentInspect
Attach a redacted, hash-verifiable offline artifact	AgentInspect
Monitor a production fleet with hosted dashboards and retention	Hosted observability / APM
Manage prompts, datasets, and online LLM-judge experiments	Eval / prompt platforms

See the factual comparison guide.

Safety and network behavior

• Traces are local JSONL under .agent-inspect/ or AGENT_INSPECT_TRACE_DIR.
• Capture is metadata-only by default; raw prompts and outputs require opt-in.
• Write-time redaction is enabled by default. The redact command creates a separate redacted copy and does not mutate its source.
• Core capture and inspection do not require an AgentInspect account, collector, or default upload.
• Redaction and verify-safe are best-effort controls, not privacy, security, or compliance certification.
• Optional MCP, standards export, and customer-owned Studio surfaces are explicit and have their own network boundaries.
• AgentInspect is not a chain-of-thought recorder.

Read network behavior, no-egress policy, and safe trace sharing.

Optional coding-agent loop

@agent-inspect/mcp-server exposes configured local evidence to an MCP client through bounded, read-only tools. It is optional and currently Preview; the core debug/check/evidence loop does not require it.

npx agent-inspect mcp configure --client cursor

Review the generated dry-run configuration and the coding-agent loop guide before enabling it.

<details> <summary><strong>Package family (18-package fixed release group)</strong></summary>

Group	Packages
Core product	agent-inspect, @agent-inspect/redact
Framework integrations	@agent-inspect/ai-sdk, @agent-inspect/openai-agents, @agent-inspect/langchain
Testing and evaluation	@agent-inspect/harness, @agent-inspect/eval, @agent-inspect/vitest, @agent-inspect/jest
Safety analysis	@agent-inspect/guardrails, @agent-inspect/circuit
Developer surfaces	@agent-inspect/viewer, @agent-inspect/tui, @agent-inspect/mcp, @agent-inspect/mcp-server
Local/team optional surfaces	@agent-inspect/index-sqlite, @agent-inspect/studio
Extension SDK	@agent-inspect/adapter-sdk

The root package is enough for custom capture, the CLI, checks, and Evidence workflows. Install optional packages only for the integration or surface you use. agent-inspect-vscode is currently in the repository and is not presented as a published Marketplace extension.

</details>

What it is not

• A maintainer-hosted SaaS or production APM replacement
• Hosted trace retention, a team dashboard service, or a prompt registry
• An LLM-as-judge or dataset platform by default
• A replay engine, automatic remediation system, or compliance certification

Status and documentation

Current published baseline: 6.31.36 · persisted schema 1.0 · Node.js >=20 · MIT.

Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and changelog for the current published version.

• First trace in five minutes
• CLI reference
• Trace contracts
• Evidence format
• Use cases
• Demos and screenshots
• Full documentation index

Contributing

See CONTRIBUTING.md, good first issues, and GitHub Discussions.

Redact and review traces before posting them in issues or pull requests.