inspector

MCP Inspector

A developer tool for inspecting Model Context Protocol (MCP) servers. It ships as a single package, @modelcontextprotocol/inspector, that provides four ways to inspect a server:

• Web — a Vite + React + Mantine single-page app with a Node backend.

• CLI — a scriptable command-line client for automation, CI, and fast agent feedback loops.

• TUI — an interactive terminal UI built with Ink.

• mcpdo (experimental) — a connection CLI: connect once, then run many commands against the named connection through an implicit local daemon. See clients/mcpdo.

The first three run through one global mcp-inspector binary; mcpdo is a second binary in the same package:

npx @modelcontextprotocol/inspector                   # web UI (default)
npx @modelcontextprotocol/inspector --cli             # CLI
npx @modelcontextprotocol/inspector --tui             # TUI
npx -p @modelcontextprotocol/inspector mcpdo --help   # mcpdo

Warning

The Inspector manages secrets — OAuth tokens, OAuth client secrets, and stdio env: values — and stores them in the OS keychain, if available, by default. On a machine with no keychain — Linux without libsecret or a Secret Service, headless and SSH sessions, Termux, and containers with a mounted volume — they are saved to ~/.mcp-inspector/secrets.json instead, unencrypted unless you supply a key. See Where secrets are stored for how to get a keychain back, encrypt the file, or keep secrets in memory only.

Upgrading from v1? Read the v1 → v2 migration guide — CLI flags, the new --config vs. --catalog split, the Node engine bump, and what no longer ships.

Repo status. This is the v2 line of the Inspector. Active development happens on v2/main (the develop branch — all v2 PRs target it), which is merged into main at milestone releases; main is the default branch and holds the latest released v2, published to the npm latest tag. The legacy v1 line lives on v1/main — security fixes only, published straight from that branch to the npm v1-latest tag (npx @modelcontextprotocol/inspector@v1-latest). See AGENTS.md for branch/board conventions.

Quick start (development)

Requires Node >=22.19.0.

npm install          # at the repo root; postinstall cascades into every client
npm run build        # web → cli → tui → launcher

For day-to-day web iteration, run Vite directly — fast HMR, no launcher build needed:

cd clients/web && npm run dev

The launcher-driven scripts run the built launcher, so build first:

npm run web        # prod web launcher against clients/web/dist
npm run web:dev    # web launcher in --dev mode (Vite)

v2 is not an npm workspace — each client under clients/* keeps its own package.json and node_modules, and shared code lives in core/, consumed via a @inspector/core build-time alias. Every runtime dependency core/ imports is declared once, in the repo-root package.json, and each client declares only what that client alone consumes — its UI stack, its bundler-inlined packages, its dev tooling — which leaves clients/cli and clients/launcher with no runtime dependencies of their own. What that means for adding a dependency (root vs. client, dependencies vs. devDependencies, and the bundler external lists) is in the local-dev skill.

Project layout

inspector/
├── clients/
│   ├── web/          Web client (Vite + React + Mantine). src/ = browser app; server/ = Node backend
│   ├── cli/          CLI client (tsup bundle, @inspector/core alias)
│   ├── mcpdo/   Experimental connection CLI (`mcpdo` bin) — bundled into the
│   │                 published package; see clients/mcpdo/README.md
│   ├── tui/          TUI client (Ink + React, tsup bundle)
│   └── launcher/     Shared launcher — provides the `mcp-inspector` bin, dispatches to web/cli/tui
├── core/             Shared code consumed via the `@inspector/core` alias (no package.json)
├── test-servers/     Composable MCP test servers + fixtures used by integration and smoke tests
├── scripts/          Root build/verify tooling (install cascade, smokes, the verify:* guards),
│                     repo automation run from CI (the dependency, Dependabot-alert and SDK sweeps),
│                     maintainer-workflow helpers (the pr:*, board:*, advisory:*,
│                     release:notes, release:tag and action:resolve-pin aliases)
│                     and the Docker image's HEALTHCHECK probe
├── docs/             Task-oriented guides — see below
├── specification/    Design/build specifications
├── skills/           End-user agent skills (e.g. skills/mcpdo teaches an agent to
│                     drive the `mcpdo` CLI) — distinct from .claude/skills/,
│                     which holds this repo's own procedures
├── .claude/skills/   Agent skills: the repo's procedures, invokable by name
├── AGENTS.md         Contribution rules for agents AND humans
└── README.md         You are here

Each client has its own README with client-specific detail: web · cli · mcpdo · tui · launcher.

Documentation

Testing and the quality gate

Each client self-validates from its own folder; the root scripts chain them. There is no aggregate root test script.

npm run validate     # fast inner loop: format:check + lint + typecheck + build + unit tests
npm run coverage     # the per-file ≥90% gate (lines/statements/functions/branches)
npm run local:gate   # MANDATORY before pushing — every GitHub CI check, plus one local-only one

npm run local:gate chains every check below, plus the smokes and the Storybook tests. Testing and the quality gate owns the stage list and says what each one covers and why one is local-only; AGENTS.md holds the testing rules themselves.

Contributing — AGENTS.md, CLAUDE.md, and the skills

AGENTS.md is the contract for changing this codebase, and it applies to humans and AI agents alike. It is not agent-only boilerplate — it holds the project's real rules: the version/label conventions, the TypeScript and Mantine/React standards, the testing and coverage requirements, and the mandatory pre-push gate. Read it before making changes, and keep it up to date when you change structure, tooling, or rules.