Lesson 19: Test With the MCP Inspector

In this lesson you will learn the MCP Inspector properly. You will use the web UI to explore a server, the CLI to script checks, and the exit codes to catch failures. Then you will write a short smoke test you can run on every commit.

The MCP Inspector is the official developer tool for testing and debugging MCP servers. You have used it in lessons 14 to 18 already. This lesson fills in what you skipped.

Commands come from the Inspector docs and its CLI smoke-testing guide. They ran on 28 October 2026 with @modelcontextprotocol/inspector 2.13.0 against the servers from earlier lessons.

Step 1: Pick the right client for the job

The Inspector docs describe three clients behind one binary:

The docs say the Inspector requires Node.js 22.19.0 or newer. That is higher than the SDK's Node.js 20 floor, so check your CI image.

Python users have a shortcut. uv run mcp dev server.py launches your server under the web Inspector, per the Python SDK's running guide.

Step 2: Explore a server in the web UI

Start the web UI with your server's launch command after the package name:

npx @modelcontextprotocol/inspector npx tsx src/index.ts

The docs say this prints a URL carrying a per-launch API token and opens it in your browser. In the UI, connect, then walk through the tabs for tools, resources and prompts. Call each tool with good input and bad input. Watch how the server answers.

Things to look for while exploring:

• Does every tool have a clear description, and does every argument have one?
• Do bad arguments come back as readable tool errors, not crashes?
• Do resource templates appear under templates, not in the plain resource list?

Step 3: Script checks with the CLI

The CLI runs one method per process and prints the result. These are the methods you will use most. The resource and prompt examples assume a server that has them, such as the lesson 16 and 17 code.

Handshake only, which proves the server starts and speaks MCP:

npx @modelcontextprotocol/inspector --cli node build/index.js --method initialize

List what the server offers:

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

Call a tool, read a resource and render a prompt:

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name search_books --tool-args-json '{"query":"dune"}'
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method resources/read --uri books://Dune
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method prompts/get --prompt-name recommend --prompt-args title=Dune

For an HTTP server, replace the command with --transport http --server-url https://example.com/mcp.

One trap from the smoke-testing guide: --tool-arg key=value parses each value as JSON when it can. So zip=10001 arrives as the number 10001, and a string schema rejects it. Prefer --tool-args-json, which sends exactly what you write.

Step 4: Test both protocol eras every time

The Inspector's server configuration reference says protocolEra defaults to "legacy". A plain Inspector run therefore tests the 2025-era handshake, not the 2026-07-28 one.

npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method initialize --format json
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era legacy --method initialize --format json

The protocolVersion in each result should read 2026-07-28 and 2025-11-25. The capabilities can differ too. The Python bookshop server reported listChanged: true in the modern era and false in the legacy era, because change notifications work differently in each.

Step 5: Read the exit codes

The smoke-testing guide defines stable exit codes:

All of these showed up in earlier lessons. A get_author call with a bad title exited 5. A missing resource exited 1, because it is a protocol error rather than a tool error. A call to an OAuth-protected server with no token and --stored-auth-only exited 3.

The CLI also writes a one-line JSON error envelope as the last line of stderr, such as {"error":{"code":"tool_is_error",...}}. Read that line, not the whole stream.

Step 6: Write a CI smoke test

A smoke test proves the server starts, offers what you depend on, and answers one safe call. Here is one for the TypeScript bookshop server:

#!/usr/bin/env bash
set -euo pipefail
INSPECT="npx --yes @modelcontextprotocol/inspector@2.13.0 --cli"
SERVER=(node build/index.js)

for era in modern legacy; do
  # 1. The server starts and speaks MCP.
  $INSPECT "${SERVER[@]}" --protocol-era "$era" --method initialize --format json > /dev/null

  # 2. The tools we depend on exist.
  $INSPECT "${SERVER[@]}" --protocol-era "$era" --method tools/list --format json \
    | jq -e '[.result.tools[].name] | index("search_books")' > /dev/null

  # 3. One safe, read-only call returns what we expect.
  out=$($INSPECT "${SERVER[@]}" --protocol-era "$era" --method tools/call \
    --tool-name search_books --tool-args-json '{"query":"dune"}' --format json)
  jq -e '.result.content[0].text | test("Dune")' <<<"$out" > /dev/null

  echo "smoke ok ($era)"
done

On 28 October 2026 it printed smoke ok (modern) and smoke ok (legacy) and exited 0.

Why each choice, per the smoke-testing guide:

• Pinned version. A bare npx call resolves the latest release, so the same commit could test differently next week. --yes stops the first-run install prompt from hanging CI.
• set -o pipefail. Without it, a failing Inspector on the left of a pipe is ignored.
• A read-only call. A smoke test runs on every commit, so never call the tool that sends email or charges a card.

Step 7: Handle auth and secrets safely

For servers behind OAuth, two flags matter:

• --header "Authorization: Bearer <token>" sends a token you already have.
• --stored-auth-only never opens a browser. If the server challenges and no stored token fits, the run fails fast with exit 3. The guide warns that interactive OAuth would otherwise wait up to 15 minutes.

The Inspector docs also carry a warning worth repeating. The Inspector stores OAuth tokens, client secrets and stdio environment values in the OS keychain when one exists. On machines without one, such as many containers and SSH sessions, they go to ~/.mcp-inspector/secrets.json, unencrypted unless you supply a key.

Try it

1. Copy the smoke script and point it at your Python server: SERVER=(uv --directory /ABSOLUTE/PATH/TO/bookshop run server.py).
2. Add a check that get_author with "Dun" exits with code 5. Capture the status with || status=$? rather than letting set -e stop the script.
3. Add a resources/read check for books://Dune.
4. Break the server on purpose, such as by renaming a tool, and confirm the script fails.

Recap

• Web UI to explore, CLI to script, TUI when there is no browser.
• Always run checks with --protocol-era modern and --protocol-era legacy.
• Use --format json, read results from stdout and the error envelope from stderr.
• Pin the Inspector version in CI and use --stored-auth-only for protected servers.

Next step

Lesson 20 explains the difference between exit codes 1 and 5 from the server's side: protocol errors and tool errors. For background on capabilities you saw in initialize results, read MCP capabilities explained and MCP server discovery. Before you install third-party servers, our guide to choosing MCP servers explains what to check.

Course navigation

Previous lesson: Lesson 18: Ask the User With Elicitation.

Next lesson: Lesson 20: Handle Errors Well.

Back to the Learn MCP course outline.

Frequently asked questions