MCP Inspector v2: three front ends for one protocol client

The gap between an MCP server that starts and one that works

An MCP server can boot, log a listening line, and still be wrong. The protocol surface is small enough that a handshake succeeds while the tool list comes back with schemas a model cannot use, or a tool call returns a shape the client silently drops. Reading server logs tells you the server's side of the story and nothing about what the client received. The Inspector exists to close that gap: it acts as an MCP client and shows you the session from the client's position. The README describes it as a developer tool for inspecting Model Context Protocol servers, shipped as a single package, @modelcontextprotocol/inspector. The audience is narrow and specific. It is for people writing MCP servers, people reviewing an MCP App's tools, and people who need a repeatable connect, list and call sequence in a shell or CI job. It is not for end users of an MCP-powered product, and it is not a server framework.

One launcher, three clients, and a shared core with no package.json

The repository is not an npm workspace. Each client under clients/ keeps its own package.json and its own node_modules, and shared code lives in core/, consumed through a build-time alias called @inspector/core. That alias is the load-bearing detail. Every runtime dependency that 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. The README states the consequence directly, that this leaves clients/cli and clients/launcher with no runtime dependencies of their own. The launcher is the single mcp-inspector binary and it dispatches to web, CLI or TUI. According to docs/launcher-config-consolidation-plan.md, the launcher runs a client in-process rather than spawning it, which is why the launcher-driven scripts require a build first. The web client splits further: clients/web/src is the browser app, clients/web/server is a Node backend. The README points at docs/architecture.md for the dumb components plus Storybook approach on the web side, which suggests the React layer is deliberately kept free of protocol logic and the state lives elsewhere.

Running it: npx, three flags, and a Node floor of 22.19.0

The published entry point is a single package. The README gives these invocations: npx @modelcontextprotocol/inspector for the web UI, which is the default, npx @modelcontextprotocol/inspector --cli for the CLI, and npx @modelcontextprotocol/inspector --tui for the terminal UI. Working from source requires Node >=22.19.0. The sequence at the repo root is npm install, where a postinstall cascades into every client, then npm run build, which builds web, then cli, then tui, then launcher. For web iteration the README recommends skipping the launcher entirely and running cd clients/web && npm run dev for Vite HMR. The launcher-driven scripts run the built launcher, so build first; npm run web runs the production web launcher against clients/web/dist, and npm run web:dev runs the launcher in --dev mode against Vite. Configuration is split between two flags, --config and --catalog, and the README flags that split as one of the things the v1 to v2 migration guide covers. It also lists env-var renames in that same guide. The docs table points at docs/mcp-server-configuration.md for which server or servers the Inspector connects to and the config file format, and at docs/cli-smoke-testing.md for the connect, list, call, assert workflow using --format json with jq, plus the exit-code map and keeping OAuth non-interactive.

The v1 and v2 branch split is the first thing to get right

Two lines ship from this repository at once. Active development happens on v2/main, the develop branch, and all v2 pull requests target it. That branch 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, receives security fixes only, and publishes straight from that branch to the npm v1-latest tag, which the README illustrates as npx @modelcontextprotocol/inspector@v1-latest. If you file an issue or open a pull request against the wrong branch you are working against code that will not receive the change. The release cadence visible in the supplied material is weekly: 2.4.0 on 2026-08-26, 2.5.0 on 2026-09-02, 2.6.0 on 2026-09-09. That cadence matters for anyone pinning a version. A weekly minor release on a tool that speaks a protocol under active revision means the CLI flag surface is a moving target, and the existence of a dedicated v1 to v2 migration guide covering CLI flags, the config versus catalog split, the Node engine bump and what no longer ships tells you the last major transition was not a drop-in.

Where the Inspector is the wrong tool

The Inspector is an interactive client, so it is a poor fit for anything that needs to run unattended against a server it does not control. The docs table is explicit that keeping OAuth non-interactive is a topic in its own right, covered in docs/cli-smoke-testing.md, which implies the default flow expects a human to complete an authorization step. If your CI has no way to hold and refresh credentials, the CLI path needs work before it is usable. The second boundary is scope: this tool inspects, it does not host. There is no server implementation here, so it will not help you decide whether your transport choice is correct under load, and nothing in the supplied material describes load generation, latency measurement or concurrency testing. The third boundary is the one the repository is most candid about. The README states that there is no aggregate root test script, and that each client self-validates from its own folder while root scripts chain them. Anyone expecting a single npm test at the root will not find one. The quality gate compensates with npm run validate for the fast inner loop, npm run coverage for a per-file gate at 90% or above on lines, statements, functions and branches, and npm run local:gate, described as mandatory before pushing and a strict superset of GitHub CI. That gate is a real cost for contributors: the README notes two stages are local-only, and docs/quality-gate.md is where the stage list lives.

How it differs from a general HTTP debugging proxy

The obvious alternative for inspecting a server is a general-purpose network tool, a proxy or an HTTP client that records requests and responses. The difference is protocol awareness. A proxy sees bytes; the Inspector sees MCP concepts, which is why the CLI can express a connect, list, call, assert workflow as discrete steps and why the README describes a CLI-first then one-shot-web recipe for automated App-tool review in docs/mcp-app-review.md. A proxy cannot tell you that a tool's input schema is malformed for the protocol, because it has no notion of a tool. The second alternative is writing a throwaway client against the MCP SDK. That gives you full control and no dependency on a weekly release cadence, at the cost of rebuilding session handling, output formatting and the exit-code conventions the Inspector already defines. The supplied material does not name a competing inspector, so treat this as a build versus adopt comparison rather than a product comparison. If your inspection needs are one-off and narrow, a short script against the SDK is defensible. If you want the same output shape across many servers, the Inspector's --format json mode is the reason to adopt it.

Maintenance cost, licensing and what the material does not say

Contributing here has an unusual shape. AGENTS.md is described as the contract for changing the codebase, applying to humans and AI agents alike, and it holds the version and label conventions, the TypeScript and Mantine and React standards, the testing and coverage requirements, and the mandatory pre-push gate. The repository also keeps its procedures as skills under .claude/skills/, invokable by name, with docs/skill-authoring.md covering how to write a skill description that fires and how to build eval cases that measure it. A contributor who ignores AGENTS.md will fail the gate rather than a review comment. On dependency hygiene, the README references automated dependency, Dependabot-alert and SDK sweeps run from CI, which suggests dependency churn is handled centrally rather than per client. The licence is the gap. The supplied material does not state a licence for this repository, and the docs table lists a publishing guide covering what ships in the tarball and packaging invariants but says nothing about licence terms. If you need to redistribute the package or vendor any part of it, confirm the licence from the repository itself before you rely on it. Nothing here should be read as legal advice.

Editorial conclusion

Adopt it if you are building or operating an MCP server and need to see what a client actually receives, or if you want a scriptable connect, list and call loop inside CI. Do not adopt it as a library or as a runtime dependency of your own server; it is a developer tool, and its CLI and launcher clients carry no runtime dependencies of their own by design. Before you commit, check three things: which branch your pinned version came from, since v1 lives on v1/main and publishes to the v1-latest npm tag while v2 publishes to latest; that your Node runtime satisfies >=22.19.0; and that the config file format in docs/mcp-server-configuration.md matches whatever server list you already keep elsewhere.

Official sources

1. Issues
2. modelcontextprotocol/inspector on GitHub
3. Project website
4. README
5. Releases