MCP Inspector

What It Does

The MCP Inspector is the official developer tool for interactively testing and debugging Model Context Protocol servers. It is maintained by the modelcontextprotocol organization, the same group that owns the protocol specification, and it is the debugger the protocol's own documentation points readers to. The tool has two faces. The first is a React web UI (the MCP Inspector Client) that opens in a browser and lets you connect to any MCP server, browse its tools, resources, and prompts, fill in parameters through forms, and watch the JSON responses stream back. The second is a CLI mode that does the same work from the command line and emits machine-readable JSON, which makes it scriptable in CI pipelines and usable by coding agents. A proxy layer bridges the browser UI to servers that speak stdio, SSE, or streamable-HTTP transports. The audience is MCP server authors who need to verify their implementations, agent developers wiring servers into Claude Desktop or Cursor, and platform teams running MCP smoke checks in CI.

The Good

85 CLI tests, all passing, in 31 seconds. The repository ships four vitest test files under cli/__tests__/ (cli.test.ts, tools.test.ts, headers.test.ts, metadata.test.ts) that cover the full surface: tools/list, tools/call, resources, prompts, environment-variable handling (including base64 and equals-sign edge cases), config files, transport inference from URLs, log-level validation, and explicit failure paths for missing methods and wrong transports. When GearScope ran npm run test-cli, every one of the 85 tests passed with zero failures. For a debugger that other tools depend on, this test discipline is exactly what you want to see.

Every core MCP operation works on the first try against a real server. GearScope connected the inspector to the official @modelcontextprotocol/server-everything reference server over stdio and exercised all four operations. tools/list returned complete JSON schemas including additionalProperties: false, required arrays, and $schema references. tools/call --tool-name echo --tool-arg message=HelloFromGearScope returned {content: [{type: text, text: "Echo: HelloFromGearScope"}]}. resources/list and prompts/list both returned their full hierarchies. Eight of eight functional checks passed with no retries and no documentation lookups.

Error handling and env-var injection behave correctly. Calling a nonexistent tool returned a proper structured error: isError: true with MCP error -32602: Tool does_not_exist not found. Passing -e GEARSCOPE_TEST=abc123 and then calling the get-env tool confirmed the variable reached the spawned server process verbatim. These are the two paths most likely to break silently in an MCP client, and both work exactly as documented.

Security hardening is serious and visible, not bolted on. The proxy authenticates by default with a random session token printed to the console, binds to localhost only, and validates the Origin header to block DNS-rebinding attacks. The README explicitly calls out CVE-2025-49596, the remote-code-execution hole that an unauthenticated proxy exposed, and warns in bold that disabling auth with DANGEROUSLY_OMIT_AUTH is "incredibly dangerous" because it can be exploited through a browser visiting a malicious page. The fix shipped as the default posture, not as an opt-in. This is the right way a security-sensitive debugger should be shipped.

Official lineage and real adoption. The package is published by Anthropic and modelcontextprotocol maintainers, sits at 10,248 GitHub stars and 1,393 forks, and records 765,119 npm downloads in the trailing 30 days (about 25,500 per day, with weekday peaks around 31,000). The current version is 0.22.0, the repo was pushed the same day as this review, and 55 npm versions have been published. It is the debugger the MCP docs site links to under its own "Inspector" and "Debugging" sections.

The Bad

The dependency tree is heavy for a debugger. A clean npm install @modelcontextprotocol/inspector pulls 258 packages into node_modules (195 top-level entries under node_modules) and occupies roughly 16 MB. For comparison, the PrefectHQ/fastmcp framework GearScope reviewed pulls 25 Python packages, roughly a tenth of this footprint. The inspector bundles three internal workspaces (client, server, cli), the full MCP SDK, concurrently, spawn-rx, ts-node, zod, and node-fetch. None of this breaks anything, but a developer who only wants the CLI to run tools/list in a CI step still downloads a quarter-thousand packages to do it.

The Node version floor is strict and excludes older LTS. The engines field requires node >=22.7.5. Node 22.7.5 shipped in mid-2024, which means anyone still on the Node 20 LTS line (still in maintenance through April 2026) cannot run the inspector without upgrading. A developer who manages multiple Node versions will handle this fine, but teams with pinned older runtimes hit an EBADENGINE wall. The CLI, which is the CI-friendly surface, shares this floor.

The license is documented inconsistently across three places. The README's final "License" section states flatly, "This project is licensed under the MIT License." The actual LICENSE file opens by explaining the project "is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0," with new contributions under Apache-2.0. And GitHub's license detector reports NOASSERTION because of this split. A reviewer, a legal team, or a downstream packager reading any one of these three sources gets a different answer. The correct position is the LICENSE file's transition statement, but the README has not been updated to match it.

326 open issues signal a support backlog. The issue tracker has 326 open items against 1,393 forks. Many are feature requests and transport edge cases rather than defects, and the maintainers are visibly active on the main branch, but the open count is high for a tool this central. Teams relying on the inspector for production CI should expect to read issue threads rather than get rapid fixes.

Smoke Test Results

Tested on macOS host (aarch64), Node v24.13.1, npm 11.8.0. The package was installed from the npm registry into a local project directory.

Run A. Fresh install, no deps preinstalled

$ npm install @modelcontextprotocol/inspector@0.22.0

PASS (258 packages, 0 vulnerabilities, 11s)

$ ls node_modules/.bin/mcp-inspector

PASS (symlink to cli/build/cli.js present)

$ cat node_modules/@modelcontextprotocol/inspector/package.json | grep version

PASS (0.22.0)

$ mcp-inspector --help

PASS (options: -e, --config, --server, --cli, --transport, --server-url, --header, -h)

Pass rate: 4 of 4. Clean install with zero configuration. The npm cache on this host had a pre-existing root-ownership issue unrelated to the package that was worked around with a custom cache directory; the package itself installed without error.

Run B. Sandbox with deps preinstalled

$ npm install @modelcontextprotocol/server-everything (reference server)

PASS (13 packages, bin: mcp-server-everything -> dist/index.js)

$ mcp-inspector --cli .../server-everything/dist/index.js --method tools/list

PASS (full tool schemas: echo, get-annotated-message, get-env, and more, with required fields and additionalProperties:false)

$ mcp-inspector --cli .../server-everything/dist/index.js --method resources/list

PASS (resources returned with uri, name, description, mimeType)

$ mcp-inspector --cli .../server-everything/dist/index.js --method prompts/list

PASS (prompts returned with arguments and required flags)

$ mcp-inspector --cli --config mcp-config.json --server everything --method tools/call --tool-name echo --tool-arg message=ConfigModeWorks

PASS ({content:[{type:text,text:"Echo: ConfigModeWorks"}]})

Pass rate: 5 of 5. Every operation against a live server produced correct, schema-validated output on the first attempt. Config-file mode resolved the named server and injected its environment block correctly.

Run C. Functional verification (does it do what it claims?)

$ mcp-inspector --cli ... --method tools/call --tool-name echo --tool-arg message=HelloFromGearScope

PASS (returned "Echo: HelloFromGearScope")

$ mcp-inspector --cli ... --method tools/call --tool-name does_not_exist

PASS (isError:true, "MCP error -32602: Tool does_not_exist not found")

$ mcp-inspector --cli -e GEARSCOPE_TEST=abc123 ... --method tools/call --tool-name get-env

PASS ("GEARSCOPE_TEST":"abc123" present in server's environment dump)

$ mcp-inspector --cli ... --method tools/call --tool-name echo --tool-arg 'options={"format":"json"}'

PASS (server-side Zod validation surfaced correctly: "Required" error on missing message field, proving the JSON arg reached the server)

$ npm run test-cli (project's own suite)

PASS (Test Files 4 passed, Tests 85 passed, Duration 31.27s)

Functional pass rate: 8 of 8. All tool, resource, prompt, error-handling, env-injection, config-file, and project-suite paths verified with assertions on actual return values.

What the runs tell you

The inspector installs in one command, connects to a real MCP server over stdio, and correctly lists and invokes every component type the protocol defines. The CLI is self-documenting: every method GearScope tried produced schema-validated JSON on the first attempt, and the project's own 85-test suite passed without a single failure. The only friction is environmental (a strict Node version and a large dependency tree), not functional. Nothing in the core claim, "interactively test and debug MCP servers," went unverified.

Setup Walkthrough

1. Check your Node version: node --version. You need 22.7.5 or newer. Node 24 satisfies this. If you are on Node 20 or older, upgrade first or use a version manager.
2. Inspect a server without installing anything: npx @modelcontextprotocol/inspector node build/index.js. This launches the web UI at http://localhost:6274 and the proxy at http://localhost:6277. The console prints a session token you paste into the UI on first connect.
3. Use the CLI for scripting and CI: npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list. Add --method tools/call --tool-name NAME --tool-arg key=value to invoke a tool.
4. Manage multiple servers with a config file: write an mcp.json with an mcpServers object, then run npx @modelcontextprotocol/inspector --cli --config mcp.json --server myserver --method tools/list. A single-server config auto-selects that server.
5. Pass environment variables with -e KEY=VALUE (repeatable). Pass HTTP headers on remote servers with --header "Name: Value". Use --transport sse|http for remote URLs.

Gotcha: the npm package name is @modelcontextprotocol/inspector but the installed binary is mcp-inspector and the --help usage line calls it inspector-bin. All three refer to the same tool. Do not disable proxy auth with DANGEROUSLY_OMIT_AUTH=true; it reopens the CVE-2025-49596 attack surface through any web page your browser loads.

Alternatives

1. mcp-use/mcp-use (github.com/mcp-use/mcp-use) - a TypeScript framework for building MCP apps and clients that also exposes programmatic server introspection. Prefer it when you need a client embedded in your own application rather than a standalone debugger.
2. MCP TypeScript SDK client (github.com/modelcontextprotocol/typescript-sdk) - the low-level client the inspector is built on. Use it directly when you want zero debugging UI and full programmatic control with a minimal dependency surface.
3. Raw JSON-RPC over stdio - the MCP protocol is documented and small. For a one-off check of a single tool, sending a hand-written initialize and tools/call over stdio is a few dozen lines and adds no dependencies. The inspector's value is the interactive UI, schema rendering, and config management, which matter once you are iterating on a server.