Search

Home › Learn › How to use the MCP Inspector

How to use the MCP Inspector

Updated 2026-11-01

The MCP Inspector is the reference developer tool for testing and debugging MCP servers. It talks to a server the way a client does, so you can list its tools, call them with your own arguments and read the raw protocol traffic without involving a model. The details below come from the official Inspector documentation as read on 2026-11-01.

One package, three clients

The package is @modelcontextprotocol/inspector, and it needs Node 22.19.0 or newer. It runs through npx with no install step.

ClientCommandUse it for
Web (default)npx @modelcontextprotocol/inspectorExploring a server in a browser
CLInpx @modelcontextprotocol/inspector --cliCI, shell pipelines, coding agents
TUInpx @modelcontextprotocol/inspector --tuiA terminal UI when a browser isn't available

The docs state that all three share one core, so transports, config files and stored OAuth state behave the same across them. Mode flags only count at the front of the command line: the first token that isn't --web, --cli or --tui ends launcher parsing, and everything after it goes to the client.

Connect to a server

Pass the command that starts a local server as arguments:

# A server you are developing
npx @modelcontextprotocol/inspector node path/to/server/index.js

# A published npm package
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

# A published PyPI package
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

Point it at a remote server with --server-url:

npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

With no target, the web client opens its server list, where you can add servers in the UI. On first launch that list is seeded with three samples: a filesystem server scoped to /tmp, the "everything" reference server, and the MCP organization's hosted example server.

Every server takes different arguments, so read its README first. On mcpnav, a server's detail page shows its install command when the Registry lists one; that command is what goes after @modelcontextprotocol/inspector.

Open the printed URL

The web client's backend can spawn processes on your machine, so it guards its API with a token generated at each launch. The launcher prints a URL containing that token and opens it. Use that URL rather than typing localhost:6274 from memory. DANGEROUSLY_OMIT_AUTH=true turns the check off, and the docs limit that to machines where nothing else can reach the port.

What each tab shows

Which tabs appear depends on the capabilities the server reports, which is itself useful: a missing tab means the server didn't declare that capability.

TabShows
ToolsEach tool's description, input schema as a form, annotations and call results
ResourcesResources and templates, reading them, and subscriptions where supported
PromptsPrompt templates and the messages they generate from your arguments
LogsThe server's log notifications
ProtocolThe JSON-RPC transcript: requests, responses and notifications
NetworkHTTP status, headers and bodies, for HTTP and SSE servers only
ConsoleThe server process's stderr, for stdio servers only

A debugging order that works

These steps are our suggestion, built on the tabs above:

  1. The server won't connect (stdio). Read Console first, since stderr is where most stdio servers put their diagnostics.
  2. The server won't connect (remote). Read Network for the status code. A 401 or 403 points at authentication rather than the server's tools.
  3. A tool is missing. Check the Tools list. If it isn't there, the problem is in the server or its configuration, not in your AI client.
  4. A tool returns the wrong thing. Call it from the form, then compare the request and response in Protocol.
  5. It works here but not in your client. The server is likely fine, so look at that client's configuration.

Script it with the CLI

Each CLI run connects, sends the one request named by --method, prints the result and exits:

# List tools
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# Call a tool on a remote server and pipe the JSON result
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http \
  --method tools/call --tool-name get_weather --tool-arg city=Boston --format json | jq .result

Other methods include initialize, resources/list, resources/read, prompts/list and prompts/get. Note that --tool-arg parses values as JSON where it can, so zip=10001 is sent as a number. Use --tool-args-json to pass the whole argument object instead.

Where secrets go

The Inspector keeps OAuth tokens, OAuth client secrets and stdio env: values in the OS keychain when one is available. Without one (headless and SSH sessions, containers, Linux without a Secret Service) they go to ~/.mcp-inspector/secrets.json, which the docs warn is unencrypted unless you supply a key. Keep that in mind on shared machines, and see the security checklist.

What is not covered here

This article did not read the Inspector's pages on the TUI, the mcpdo connection client, protocol eras or authorization. For those, and for the full flag reference, see the official docs.

Sources

Sources