MCP Inspector is a development client for testing MCP servers independently of an AI conversation. Use it to list tools, inspect their schemas and compare successful and failing calls. If Inspector works but your AI host does not, investigate the host’s launch configuration and permissions next.
Install and choose a working environment
Tool version 2.15.0. Documentation checked 2026-11-16. The upstream source snapshot and installed package are pinned separately; the snapshot is not claimed to be the package’s release commit.
node --version
npm install --ignore-scripts --save-exact @modelcontextprotocol/inspector@2.15.0 @modelcontextprotocol/server-filesystem@2.3.0
npx --no-install mcp-inspector --cli --help
Inspector is already an MCP client. Run the CLI examples below against the server you want to test; do not register Inspector as a server in Claude Code, Codex or Cursor. After a server works here, register that server’s launch command in your AI client.
Three practical uses
1. Discover a server’s tools
npx --no-install mcp-inspector --cli --format json --protocol-era legacy --method tools/list -- node node_modules/@modelcontextprotocol/server-filesystem/dist/index.js /absolute/path/test-project
Expected: Expect tools and their schemas. Replace the path with an existing test directory.
2. Call a read-only tool
npx --no-install mcp-inspector --cli --format json --protocol-era legacy --method tools/call --tool-name read_text_file --tool-args-json '{"path":"/absolute/path/test-project/README.md"}' -- node node_modules/@modelcontextprotocol/server-filesystem/dist/index.js /absolute/path/test-project
Expected: Expect the README contents. This uses POSIX shell quoting; adapt JSON quoting for your shell.
3. Separate tool failure from connection failure
Call read_text_file with a nonexistent or disallowed synthetic path. Record the process exit code and result.isError separately.
Expected: a response that follows the stated scope and exposes the requested source or tool result. Verify those references before acting.
What our tests established
The 2.15.0 CLI/stdio run listed Filesystem tools and read a known file. An outside-path call returned isError and exit 5. Web UI, TUI, HTTP and OAuth were not tested.
Tests were run by Codex on synthetic data; no claim of the owner personally testing or reviewing this guide. Examples added above are documentation-based unless included in that recorded scope.
Common errors and fixes
Old v1 flags fail
Read the v1-to-v2 guide; flags such as --config have changed meaning.
Unsupported Node runtime
Use an officially supported patched Node line: ^22.23.4, ^24.22.1 or >=26.12.1.
JSON output hides a failed operation
Check both the exit status and result.isError. The recorded tool failure exited with code 5.
Limits, costs and license
MIT. Inspector is a test client, not an AI model or a server to register inside Claude Code/Codex/Cursor. Follow official network/authentication guidance if using its web interface.
When to choose an alternative
-
For building a server: FastMCP.
-
For exposing file tools to an AI client: Filesystem MCP.
FAQ
Can I launch Inspector with npx?
Yes. This guide installs a pinned version first and uses --no-install for reproducibility.
Does Inspector create MCP tools?
No. It discovers and exercises tools implemented by your server.
Why do these commands differ from older tutorials?
This guide uses 2.15.0. The v1/v2 CLI, ports and configuration differ.
Official sources
For a practice example you control, start with FastMCP's minimal server. For a documentation lookup tool, compare Context7's query workflow.