Skip to main content

How to Test an MCP Server with MCP Inspector

Short answer

MCP Inspector is the official tool for checking an MCP server before an AI app depends on it. Run npx @modelcontextprotocol/inspector@2.11.0 with your server's start command, then open the URL it prints to use the web UI. Add --cli to list tools and call them from your terminal. Check both protocol eras, --protocol-era modern and --protocol-era legacy, because the Inspector defaults to the older legacy era.

Tested withMCP spec 2026-07-28MCP Inspector 2.11.0Python SDK (mcp) 2.3.0TypeScript SDK (@modelcontextprotocol/server) 2.3.1Node.js 24.19Python 3.14Checked 20 Oct 2026

By Tony LewisHow we test these guides

What you'll have at the end​

A server you've checked in the Inspector's web UI and from the command line. This is the output of a save_bookmark call from the CLI, trimmed:

{
  ...
  "content": [
    {
      "type": "text",
      "text": "Saved 'MCP docs'. Total bookmarks: 1"
    }
  ],
  "structuredContent": {
    "result": "Saved 'MCP docs'. Total bookmarks: 1"
  },
  "isError": false
}

The Inspector acts as an MCP client. For a local server it starts your server as a child process and sends it JSON-RPC messages over standard input and output. For a remote server it connects to a URL, and you start that server yourself. Either way it calls your tools directly, so no AI model is involved.

Before you start

  • Node.js 22.19 or later. The Inspector package requires it.
  • A server to test. This guide uses the bookmarks server from Build an MCP server, in Python or TypeScript. The remote section uses the Python version.
  • For the Python server: uv.

1. Open the web UI​

Run this from the folder that holds your server. The Inspector starts the server for you.

npx @modelcontextprotocol/inspector@2.11.0 uv run bookmarks.py

The command prints a line like this, with a token that changes on every launch:

MCP Inspector Web is up and running at:
   http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=...

Open that exact URL. The token is what lets the page talk to the Inspector's backend, so don't type localhost:6274 from memory. The Inspector opens the browser for you by default. Set MCP_AUTO_OPEN_ENABLED=false if you'd rather open it yourself.

Once the page is open, use these tabs:

TabWhat you use it for
ServersTurn on the switch beside your server to connect. Its label reads Connect or disconnect, followed by the server's name.
ToolsSelect a tool to see its description and its input schema as a form. Fill the form and call the tool. The result appears below the form.
ProtocolThe JSON-RPC traffic: each request, its response and any notifications. Use it to see exactly what your server returned.
ConsoleFor stdio servers, the server's stderr. Your logs appear here.
NetworkFor HTTP servers, the status codes, headers and bodies of each request.

Prompts, Resources, Tasks and Logs appear when your server offers those features.

If you start the Inspector with a command, as above, the server list is read-only, so changes you make in the UI aren't saved. Use --catalog if you want a list you can edit.

2. Check the server from the command line​

The CLI connects, runs one method, prints the result and exits. That makes it the right tool for a quick check, or for a script that runs in CI. These are the flags used in this guide:

FlagWhat it does
--cliRuns in CLI mode instead of opening the web UI.
--methodThe MCP method to run, such as tools/list, tools/call, resources/list or prompts/list.
--tool-nameThe tool to call, used with --method tools/call.
--tool-arg key=valueOne tool argument. Repeat it for each argument.
-e KEY=VALUEAn environment variable for a stdio server.
--protocol-eralegacy (the default), auto or modern. See the next section.
--format jsonPrints one JSON object with no extra text, so you can pipe it to jq.

In the examples, -e comes before the server's start command, and the other flags come after it.

Test both protocol eras​

The Inspector speaks one of three protocol eras to your server:

EraWhat the Inspector does when it connects
legacyThe default. Sends a plain initialize request and nothing else.
autoAsks the server about server/discover first, then falls back to initialize if the server isn't modern.
modernPins the 2026-07-28 revision. There's no fallback, so a server that doesn't offer that revision fails.

The default is legacy because a debugging tool shouldn't guess. Run both eras, because some AI apps still use the older handshake and the 2026-07-28 revision is the current one. A server that works in only one era is worth fixing before a user finds it.

npx @modelcontextprotocol/inspector@2.11.0 --cli uv run bookmarks.py --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector@2.11.0 --cli uv run bookmarks.py --protocol-era legacy --method tools/list

Both commands list save_bookmark and search_bookmarks, along with each tool's parameters and their descriptions. The output starts like this:

{
  "tools": [
    {
      "name": "save_bookmark",
      "description": "Save a web page to the user's bookmarks.\n\nUse this when the user asks to save, bookmark or remember a link.\n",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": {
            "description": "Full URL of the page, including https://",
            "title": "Url",
            "type": "string"
          },
          ...

Call a tool​

Add --method tools/call, the tool's name and its arguments. Point BOOKMARKS_FILE at a scratch file so your real bookmarks stay untouched:

npx @modelcontextprotocol/inspector@2.11.0 --cli -e BOOKMARKS_FILE=./scratch-bookmarks.json \
  uv run bookmarks.py --protocol-era modern \
  --method tools/call --tool-name save_bookmark \
  --tool-arg url=https://modelcontextprotocol.io --tool-arg title="MCP docs"

--tool-arg reads each value as JSON when it can, so count=1 is sent as a number. If you need a value sent exactly as typed, such as the string 012, pass all the arguments as one object with --tool-args-json '{"query":"012"}' instead.

A tool that returns isError: true still prints its result, but the CLI exits with code 5, so a && chain in your shell stops there.

3. Test a remote server over Streamable HTTP​

For a remote server the Inspector doesn't start anything. You start the server, then point the Inspector at its URL. Save this file next to bookmarks.py. It serves the same bookmarks tools over Streamable HTTP:

http_server.py
import os

from bookmarks import mcp

PORT = int(os.environ.get("PORT", "8000"))

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=PORT)

In one terminal, start it. It listens on http://127.0.0.1:8000/mcp. Set PORT to use a different port.

uv run python http_server.py

In a second terminal, run the CLI against that URL. The --transport http flag tells the Inspector to use Streamable HTTP:

npx @modelcontextprotocol/inspector@2.11.0 --cli http://127.0.0.1:8000/mcp --transport http --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector@2.11.0 --cli http://127.0.0.1:8000/mcp --transport http --protocol-era legacy --method tools/list

To open the web UI against the same server, use --server-url in place of the positional URL:

npx @modelcontextprotocol/inspector@2.11.0 --server-url http://127.0.0.1:8000/mcp --transport http

The Network tab shows the HTTP side of each request, and the Protocol tab shows the JSON-RPC side. Stop the server with Ctrl-C when you're done.

This guide's HTTP example is in Python. Deploy a remote MCP server covers hosting it and running it in a container.

Common problems​

{"error":{"code":"error","message":"spawn no-such-server-cmd ENOENT"}} The command you gave the Inspector doesn't exist on your PATH. Run the same command in your terminal to check it. Use which uv or which node to find the full path.

Version negotiation failed: the server did not offer pinned protocol version 2026-07-28 You ran with --protocol-era modern, and the server doesn't offer the 2026-07-28 revision. modern never falls back to an older revision. Either run that server with --protocol-era legacy, or use --protocol-era auto so the Inspector probes first and falls back when needed.

{"error":{"code":"tool_not_found","message":"Tool 'nope' not found on server."}} The tool name doesn't match one the server offers. Run --method tools/list and copy the name exactly from the name field.

"text": "Error executing tool save_bookmark: 1 validation error ... url Field required" with "isError": true You left out a required argument. The server's own validation rejected the call and returned the error as a tool error, so the Inspector exits with code 5. Compare your --tool-arg flags with the required list in the inputSchema from tools/list.

{"error":{"code":"unreachable","message":"fetch failed","cause":"connect ECONNREFUSED 127.0.0.1:8999"}} Nothing is listening at the URL, so the CLI exits with code 4. This output came from a run against port 8999, where no server was running. Start the HTTP server first, and check that the port in your URL matches the PORT the server uses.

"code":"auth_required" with exit code 3 The server answered with HTTP 401 or 403. For a server that uses OAuth, sign in through the web UI, or let the CLI finish the browser sign-in in an interactive terminal. In a script, --stored-auth-only makes the CLI fail right away instead of waiting for a browser. The authorization guide covers the server side.

Stray output on stdout Over stdio, standard output carries the protocol messages, so a stray print() or console.log() puts a non-protocol line in that stream. In our run, a line that an echo wrote to stdout before the server started didn't stop the Inspector from listing the tools. Don't rely on that, because other clients may handle it differently. Log to stderr, which the Console tab shows, as the bookmarks server does with logging in Python and console.error() in TypeScript.

Exit codes from the CLI, from the Inspector's documentation:

CodeMeaning
0Success.
1A usage error or an unexpected error.
3The server requires authentication.
4The server can't be reached.
5A tool error, or the tool wasn't found.

The CLI also has codes 2 and 6 to 9 for MCP Apps and for schema and skill checks.

FAQ​

What is MCP Inspector?

MCP Inspector is the reference developer tool for testing and debugging MCP servers. The npm package @modelcontextprotocol/inspector gives you a web UI, a command-line client and a terminal UI, all built on the same core. Use it to check tools, resources and prompts before an AI app uses them.

Which protocol era should I test with?

Test both. The Inspector defaults to legacy, which uses the older initialize handshake. Modern pins the 2026-07-28 revision and fails if the server doesn't offer it. Running both shows whether your server works for apps on either handshake.

Do I need an AI app to use MCP Inspector?

No. The Inspector connects to your server and calls its tools directly, so you can test without an AI model. Connect your server to an AI app once the Inspector checks pass.

Can I test a server that needs sign-in?

Yes. For HTTP servers that use OAuth, the Inspector runs the sign-in flow and keeps the tokens on your machine. The OAuth guide covers what your server has to do to support it.