To debug an MCP server, run the MCP Inspector against it with npx, connect, list the tools, call each one with test inputs, and read the request and response messages. The Inspector is the reference developer tool in the Model Context Protocol docs, with web, command line and terminal clients.
What is the MCP Inspector?
According to the Model Context Protocol documentation, the MCP Inspector is the reference developer tool for testing and debugging MCP servers. It ships as one package, @modelcontextprotocol/inspector, with three clients behind one binary: a web client, a command line client and a terminal interface. All three share the same core, so a connection behaves the same across them, including transports and OAuth state.
The docs list a requirement of Node 22.19.0 or newer, and the tool runs through npx with no install. Check the current page before you start, since versions and flags change.
How do you start it?
For a local server that runs over standard input and output, give the Inspector the command that launches your server:
npx @modelcontextprotocol/inspector node path/to/server/index.js
The command prints a URL that carries a per-launch API token and opens it in your browser. The token is there so other software on your machine cannot drive the tool. Do not paste that URL into chat or tickets.
For a remote server, pass the server URL and transport. For automation, the command line client can list tools and exit, or call one tool and print JSON, which suits continuous integration checks.
What should you check, in what order?
1. Does it connect? If the connection fails, look at the transport first. A stdio server that prints stray text to standard output corrupts the message stream, because that channel is reserved for protocol messages. Send logs to standard error instead.
2. Do the tools list? Open the tools view and confirm names, descriptions and input schemas are what you meant. Models choose tools by reading these descriptions, so vague text causes wrong calls.
3. Does each tool work with good input? Call it with a normal value and read the result.
4. Does it fail well with bad input? Send missing fields, wrong types, empty strings and oversized values. A good server returns a clear error. A bad one crashes or hangs.
5. What do the raw messages say? The web client has a monitoring view of the JSON-RPC exchange. When something looks wrong, the answer is usually visible there.
What are the security cautions?
The Inspector stores secrets such as OAuth tokens and environment values in the operating system keychain when one is available. On machines without a keychain, the docs say they are saved to a file in the home directory, unencrypted unless you supply a key. Be careful on shared or headless machines.
The Inspector can run an arbitrary command to start a server, so only launch servers you trust. The MCP security guidance page warns that local servers may have direct access to the user's system, and that malicious startup commands are an attack path. Read a server's README and source before running it.
What does a constructed session look like?
A developer writes an MCP server with a tool that looks up an order by identifier. In the Inspector the tool lists correctly. A call with a valid identifier works. A call with an empty string returns a database error that includes the connection string in its message. The developer fixes that by returning a generic error and logging the detail privately, then adds a test that calls the tool with an empty value and checks the message.
How do you keep the checks repeatable?
Turn your manual routine into a script with the command line client. List tools, assert the expected names exist, call each with a fixed input and compare the result. Run it in your pipeline so a change to a schema or an error format is noticed.
How to check or apply this
- Read the Inspector documentation page and confirm your Node version.
- Launch it against your server and record the connection transport.
- Verify tool names, descriptions and schemas.
- Call each tool with valid, missing, wrong type and oversized input.
- Inspect messages for secrets or internal details in errors.
- Script the same calls with the command line client and run them on every change.
If your server will be used by AI agents, a policy layer such as Safeguard's MCP Guardrail can check tool calls in production, which complements the development-time checks above.
Quick check
Do I need to install the Inspector?
No. The documentation says it runs directly through npx.
Why does my stdio server fail to connect?
A common cause is writing non-protocol output to standard output. Send logs to standard error so the message stream stays clean.
Sources
Last reviewed: 18 October 2026.
