Third-party toolUpdated 2026.11.16

MCP Inspector Guide: Install, Test MCP Tools and Fix Errors

MCP Inspector installation and getting started: client setup or a local workflow, three practical examples, tested findings, common errors, costs and alternatives.

Aaron recommends Open official GitHub

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

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.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Or follow us on: