MCP course: build, test and connect MCP serversLesson 3 of 4

MCP Inspector: test and debug an MCP server

Mindket editors · Published November 4, 2026 · Updated November 6, 2026 · 11 min read

A black banner titled "MCP course". Its line reads "Build an MCP server in Python or TypeScript, test it, connect it".

MCP Inspector is the official developer tool for testing MCP servers. Start it with npx @modelcontextprotocol/inspector followed by your server's start command, then open the URL it prints. You can list and call tools, read prompts and resources, and watch the JSON-RPC messages. A --cli mode runs single requests from scripts and CI.

In this lesson

You will launch the Inspector on your own server, call a tool and read the raw JSON-RPC messages behind the call.
Keep Node patched for it, even when your server is written in Python.
The Console tab shows a stdio server's stderr, and the Network tab shows HTTP traffic. They never appear together.
The --cli mode runs one request and exits, so it fits shell scripts and CI.

All courses

On this page

Before you start
Step by step, with screenshots
Run it on your own server
A tour of the tabs
Finding a fault with it
The command line mode
Protocol eras: legacy, auto and modern
Keep the Inspector safe
David Soria Parra on the stateless protocol behind the Inspector's eras
Common mistakes
Try it yourself
Next: connect your server to a real app
Check yourself
Frequently asked questions
Sources

Before you start

The Inspector is the reference developer tool for MCP servers, and the MCP debugging guide calls it the first stop when something is wrong. One package, @modelcontextprotocol/inspector, holds three clients behind one binary: a web UI, a command line client and a terminal UI. They share the same transports and the same configuration.

Node.js 22.23.4, 24.22.1 or 26.12.1, or a later release on the same line. The Inspector runs through npx, so there is nothing to install.
A server to test. The weather servers from lesson 1 and lesson 2 both work, and so does any published server.
A browser, for the default web mode. The command line and terminal modes need none.

Step by step, with screenshots

The pictures use the published filesystem server on a folder of sample notes, so you can follow along without writing a server first. Put a few files in a folder, then install the server in another folder with npm install @modelcontextprotocol/server-filesystem. Your own server works the same way. Its start command goes where the pictures show node and a path.

Check that node --version prints one of the versions listed above, or a later one on the same line. Type npx -y @modelcontextprotocol/inspector, then node, the full path to dist\index.js under node_modules\@modelcontextprotocol\server-filesystem, and the folder of files. The launcher prints an address with a token in it. The token in the picture belongs to a launch that has ended, so yours will differ.
The launcher then opens that address in your browser by itself. If no tab opens, copy the address from the terminal. Do not type localhost:6274 from memory, because the token changes with each launch. On the Servers screen, flip the toggle on your server's card to connect. The card is named node and shows the command the Inspector will run. A Read-only session note is normal when the Inspector launches the server for you.
Once connected, the page shows the server's own name, secure-filesystem-server here. Open the Tools tab. The list heading gives the number of tools, 16 in this case, and each tool shows a title above its name. The Protocol column on the right has already logged the tools/list request that fetched the list.
Type list in the search box and select List Directory. Fill the path field with a folder the server may read, here the one from the launch command, then select Execute Tool.
$The Tools tab with List Directory selected. Its path field holds C:\tmp\learn-walk-mcp\files, and the Execute Tool button is ringed in gold.$
The result appears under Results. For this server it is one line for each file or folder, marked [FILE] or [DIR].
If the Protocol tab is not already open in the right column, select it. Then select Expand, the up-and-down arrow at the right of the tools/call card, to open the card. Each call is one card with its Parameters, which the client sent, and its Response, which the server sent back. Both are JSON-RPC. In the response, content holds the text the tool returned and structuredContent repeats it. The LEGACY badge is the protocol era, covered further down.
Select the Console tab. It shows what the server wrote to stderr. This server named the folder it may read, noted that the client gave it no root directories and said it is running on stdio. A server that fails to start leaves its reason here.

Screenshots of MCP Inspector 2.14.0 on Windows, taken on 6 November 2026 with the published filesystem server. The terminal picture is a frame drawn around the real command and its output. That launch ran with the browser auto-open turned off, so its output has no Opening browser... line.

Run it on your own server

The pictures launch a published server with the built Node server command below. For yours, put your server's own start command after the Inspector's name. The Inspector runs that command for you, so you do not start the server separately. The commands below are the ones the SDKs and the Inspector's page give.

# A local TypeScript server (the TypeScript SDK's tutorial)
npx @modelcontextprotocol/inspector npx tsx src/index.ts

# A local Python server, through the mcp command (the Python SDK's README)
uv run mcp dev server.py

# A built Node server
npx @modelcontextprotocol/inspector node path/to/server/index.js

# A published npm server, with an argument
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

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

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

Launch the Inspector with one of the commands above, using your own server's start command. Then connect and call a tool as the pictures do.
Try a bad input on purpose. A tool that answers it with a clear message is one a model can recover from.

A tour of the tabs

Which tabs you see depends on what the server reports when you connect. A server with no prompts has no Prompts tab. The Apps tab needs a server with MCP App tools, the Skills tab needs the Skills extension, and the Tasks tab needs task support.

The monitoring group, which holds Tasks, Logs, Protocol, Network and Console, opens as a column on the right when you connect, as in the pictures. You can then watch the traffic while you work in Tools.

The Inspector's main tabs, per its web client page
Tab	Shown when	Use it to
Servers	Always	Add, edit, import and connect servers, and open per-server settings
Tools	The server has tools	Read a tool's schema as a form, fill it in, call it and inspect the result
Prompts	The server has prompts	Supply arguments and preview the messages a prompt generates
Resources	The server has resources	Browse and read resources, and subscribe where the server allows it
Logs	The server has logging	Read the server's log notifications
Protocol	Always	Read the JSON-RPC transcript: requests, responses and notifications
Network	HTTP and SSE servers	Read status codes, headers and bodies at the HTTP layer
Console	stdio servers	Read the server process's stderr

Finding a fault with it

A call that fails shows up in Protocol first. It pairs each request with its response, so you see the arguments the client sent and the error the server sent back. A call rejected with error code -32602 gets its own panel: Unknown Tool when the name is missing from tools/list, and Invalid Parameters for anything else.

If the tool works here and fails in Claude Desktop, compare what differs. The debugging guide says a host may start a server from an undefined working directory, with only a limited set of environment variables. That is why it asks for absolute paths and an env key in the config.

Where to look first, by symptom
Symptom	Look at	What it shows
A tool is missing from the list	Tools, then Protocol	What the server returned for `tools/list`
A call returns an error	Protocol	The request and the error, paired
A stdio server crashes or prints nothing	Console	The process's stderr
An HTTP server answers 400 or 401	Network	The status code, headers and body
It works here but fails in the host	The host's config	Launch command, working directory and environment

The command line mode

Each --cli run connects to the server, sends the one request you name with --method, prints the result and exits. That suits CI pipelines, shell one-liners and coding agents that need to check a server change at once. --format json prints one JSON object with no banners, so it pipes cleanly into jq. --tui opens the terminal UI instead.

A tools/call that returns isError: true still prints its payload, but the run exits with 5, so an && chain stops on a failed call. On any non-zero exit the CLI also writes one JSON line to stderr that names the failure class.

# List a server's tools and exit
npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list

# Call a tool and pipe the result into jq
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

Exit codes worth knowing, per the CLI page
Code	Meaning
0	Success
1	Usage or unexpected error
3	The server requires authentication
4	The server is unreachable
5	A tool error, or the tool was not found

Protocol eras: legacy, auto and modern

The 2026-07-28 revision of MCP changed the protocol, so the Inspector treats the era as a setting on each server. Set it in Server Settings, or pass --protocol-era with legacy, auto or modern to the CLI or the terminal UI.

The default is legacy, and the page explains why. A debugging tool must not probe on its own, because a server/discover probe stalls against silent legacy stdio servers and clutters the transcript you came to read. For a new server, run the check twice. The MCP build guide does exactly that and says both runs should list the same tools.

npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era legacy --method tools/list

What each era does at connect
Era	What the Inspector does
`legacy`	The default. A plain `initialize`, no probing
`auto`	Probes `server/discover` first, then falls back to `initialize` on any answer that is not modern
`modern`	Pins exactly 2026-07-28 with no fallback, so a server that is not modern fails loudly

Keep the Inspector safe

The Inspector's web backend can start processes on your machine, which is why every route is guarded by a per-launch token and the server binds to 127.0.0.1 by default. Binding all interfaces is refused unless you set DANGEROUSLY_BIND_ALL_INTERFACES=true, and DANGEROUSLY_OMIT_AUTH=true belongs only on a machine where nothing else can reach the port.

It also stores secrets. OAuth tokens, OAuth client secrets and stdio env: values go to the OS keychain when one is available. Without a keychain they land in ~/.mcp-inspector/secrets.json, unencrypted unless you supply a key. Point it only at commands and servers you trust, because it runs the command you give it.

Security fixes land often, as the timeline shows, so launch it as npx @modelcontextprotocol/inspector@latest, the upgrade line in the 2.14.0 release notes.

Inspector v2 releases

July 28, 2026
Version 2.0.0
The v2 Inspector became the default release, with its web, command line and terminal clients in one package.
Source: MCP Inspector release 2.0.0 (read November 5, 2026)
October 7, 2026
Version 2.10.0
Added mcpdo, an experimental command line client that keeps one connection open across commands.
Source: MCP Inspector release 2.10.0 (read November 5, 2026)
October 21, 2026
Version 2.12.0
Fixed three vulnerabilities in every v2 release up to 2.11.0, among them a DNS-rebinding route to the API token.
Source: MCP Inspector release 2.12.0 (read November 5, 2026)
October 28, 2026
Version 2.13.0
Asked everyone to run Node.js 22.23.4, 24.22.1 or 26.12.1, or later.
Source: MCP Inspector release 2.13.0 (read November 5, 2026)
November 4, 2026
Version 2.14.0
Fixed three more security problems, including navigation inside the MCP App sandbox frame.
Source: MCP Inspector release 2.14.0 (read November 5, 2026)

David Soria Parra on the stateless protocol behind the Inspector's eras

David Soria Parra, a member of technical staff at Anthropic and co-creator of MCP, posted on X on 22 May 2026 that the release candidate for the 2026-07-28 revision was out. His summary: no handshake, no session id, and any request can reach any server instance. That is the split the era setting tests. legacy opens with the old initialize handshake, and modern pins the stateless revision with no fallback.

The same post made MCP Apps and Tasks first-class extensions. They are the Apps and Tasks tabs from the tour, shown only when a server supports them, so a server you build with either one gets checked there.

The Inspector's maintainers added a Node advisory to release 2.13.0 on 28 October, a week after the Node.js security releases. The package still accepts older Node versions, so npm will not warn you. Run node --version before each session and compare it with the versions this lesson asks for.

no handshake, no session id, any request can hit any server instance

David Soria Parra, Member of technical staff at Anthropic, co-creator of MCP · X (read November 5, 2026)

David Soria Parra (@dsp_) on X, 22 May 2026. The release candidate for MCP 2026-07-28 is out. The protocol is now stateless: no handshake, no session id, any request can hit any server instance. Plus extensions as first-class (MCP Apps, Tasks), auth hardening, and a proper deprecation policy so we don't have to do this again. — David Soria Parra on X, 22 May 2026

A screenshot of X's own embed of the post, taken on 5 November 2026, with the time in UTC. X cuts the post short with Show more. Select it to open the post on X.

Common mistakes

Starting it on an older Node, even if your own server runs on Node 20 or is written in Python.
Typing the address from memory or reusing an old tab. Every launch prints a new token in its URL.
Looking for Console on an HTTP server. Console is for stdio servers and Network is for HTTP and SSE servers.
Testing one era only. The default legacy exercises just the 2025-era handshake, so run the check once more with modern.
Reading only the final result. The request in Protocol shows the arguments that were sent, and a wrong argument often shows there first.

Try it yourself

Launch the Inspector on the weather server from lesson 1 or 2, call the tool and open Protocol. Find the tools/call request and its response.
List only the tool names from the command line with --cli node build/index.js --method tools/list --format json piped into jq '.result.tools[].name', using your own start command.
Call a tool name that does not exist and check the exit code with echo $?. The CLI page lists 5 for a tool that was not found.

Next: connect your server to a real app

The Inspector proves the server works on its own. Lesson 4 puts it into Claude Desktop, Cursor and VS Code, and shows where each app keeps its config. If you work in a terminal, adding an MCP server to Claude Code covers that route.

Check yourself

You want to test a server that starts with node build/index.js. What do you run?
Show answer
A. npx @modelcontextprotocol/inspector node build/index.js You put the server's own start command after the Inspector's name, and the Inspector runs it for you.
A stdio server crashes and the tool result shows nothing. Which tab shows its stderr?
Show answer
C. Console Console shows a stdio server's stderr, while Network is for HTTP and SSE servers.
Which mode fits a CI job that checks the server's tool list and then exits?
Show answer
D. --cli with --method tools/list The --cli mode connects, sends the one request you name, prints the result and exits.
You tested a new server with the default settings. What else should you do?
Show answer
B. Run the check again with --protocol-era modern The default legacy era exercises only the older handshake, so run the check once more with modern and expect the same tools.

Frequently asked questions

How do I run MCP Inspector on a Python server?

Run uv run mcp dev server.py with the mcp[cli] package, or put the launch command after the Inspector's name, such as uvx mcp-server-git --repository ~/code/mcp/servers.git for a PyPI package. The Inspector is a Node.js program, so Node has to be installed even for a Python server.

How do I test a remote MCP server with the Inspector?

Pass its address with --server-url and the transport, as in --server-url https://api.example.com/mcp --transport http. If the server asks for OAuth, all three clients run the flow. The Inspector opens the authorization URL in a browser, you sign in, and it keeps the token on disk for later runs. A CI job cannot complete that sign-in, so use --stored-auth-only there.

Can I use the Inspector without a browser?

Yes. Add --cli for single requests from a script, or --tui for an interactive terminal UI. Both use the same core as the web client.

Which port does the Inspector use?

The launcher prints the full address, token included, and the docs' examples show port 6274 on 127.0.0.1. Open the printed URL rather than typing the port yourself, because the page refuses requests without the token.

Why does the Inspector show no Console tab?

A server you reach by URL writes its error output wherever it runs. The Inspector reads stderr only from a process it launched, so such a server gets Network in place of Console.

Why does my server work in the Inspector but not in Claude Desktop?

Check the host's config before the code. Write the full path to the server file, give command the full path to node or uv if the host cannot find it, and put each variable the server reads in the entry's env key. Then quit the app completely and open it again.

Can I run the Inspector in CI?

Yes. The CLI exits with a code for each failure class, and --stored-auth-only stops it from opening a browser for OAuth. Add --strict to tools/list and it exits with 6 when a tool's schema has an error-level portability problem.

Sources

MCP docs: MCP Inspector (read November 4, 2026)https://modelcontextprotocol.io/docs/tools/inspector
MCP docs: Inspector web client (read November 4, 2026)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/web
MCP docs: Inspector CLI client (read November 4, 2026)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli
MCP docs: Inspector protocol eras (read November 4, 2026)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/protocol-eras
MCP docs: Inspector authorization (read November 4, 2026)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/authorization
MCP docs: Debugging (read November 4, 2026)https://modelcontextprotocol.io/docs/2026-07-28/tools/debugging
MCP Inspector: README (read November 4, 2026)https://github.com/modelcontextprotocol/inspector
MCP TypeScript SDK docs: Build your first server (read November 4, 2026)https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/get-started/first-server.md
MCP Python SDK: README (read November 4, 2026)https://github.com/modelcontextprotocol/python-sdk
MCP docs: Build an MCP server (read November 4, 2026)https://modelcontextprotocol.io/docs/develop/build-server
MCP Inspector release 2.0.0 (read November 5, 2026)https://github.com/modelcontextprotocol/inspector/releases/tag/2.0.0
MCP Inspector release 2.10.0 (read November 5, 2026)https://github.com/modelcontextprotocol/inspector/releases/tag/2.10.0
MCP Inspector release 2.12.0 (read November 5, 2026)https://github.com/modelcontextprotocol/inspector/releases/tag/2.12.0
MCP Inspector release 2.13.0 (read November 5, 2026)https://github.com/modelcontextprotocol/inspector/releases/tag/2.13.0
MCP Inspector release 2.14.0 (read November 5, 2026)https://github.com/modelcontextprotocol/inspector/releases/tag/2.14.0
David Soria Parra on X: the release candidate for MCP 2026-07-28 (read November 5, 2026)https://x.com/dsp_/status/2057780712187580924

Find MCP servers worth testing

Browse the MCP servers on Mindket, then point the Inspector at the ones you want to try.

Browse MCP servers

This lesson as Markdown · MCP course: build, test and connect MCP servers · All courses