Test and debug an MCP server from the command line or a UI with npx @modelcontextprotocol/inspector

Details

1. Use the web UI

npx @modelcontextprotocol/inspector node build/index.js

The command prints a URL that contains a one-time session token. Open that URL rather than typing localhost:6274 yourself, because the backend rejects requests without the token. In the UI, connect, open Tools, pick a tool, fill the form and call it.

2. Call a tool from the command line

The CLI connects, sends the one request named by --method, prints the result and exits.

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

For a remote server, use a URL and --transport http. This is the live endpoint of this wiki (tools search_answers and get_answer), which we ran on 2026-09-28:

npx @modelcontextprotocol/inspector --cli https://wiki.drfritzi.at/mcp --transport http \
  --method tools/call --tool-name search_answers --tool-arg query=inspector --format json

It printed one JSON object of the form {"result":{"content":[{"type":"text","text":"[...]"}],"isError":false}} and exited 0. --tool-arg key=value parses the value as JSON, so count=1 is a number. --tool-args-json '{"zip":"10001"}' passes the object as is.

The mode flag (--web, --cli, --tui) is only recognised at the front of the command line. Everything after the first other token goes to the client, so a later --cli reaches your server as its own argument.

3. Choose the protocol era

The Inspector connects as a legacy client by default and does not probe. Our run of --method initialize against the endpoint above reported protocolVersion 2025-11-25. To test the 2026-07-28 behaviour, put "protocolEra": "auto" (probe server/discover, fall back to initialize) or "modern" (pin 2026-07-28, no fallback) on the server entry in a config file:

{ "mcpServers": { "wiki": { "type": "http", "url": "https://wiki.drfritzi.at/mcp", "protocolEra": "auto" } } }

Then run --cli --config ./servers.json --server wiki --method initialize. With auto we got 2026-07-28 back.

4. Fail a CI job on a wrong answer

--format json prints a single JSON object with no banners, so it pipes into jq. Exit codes are stable: 3 needs authentication, 4 server unreachable, 5 tool error or tool not found. A close variant of this script (with two extra jq checks) passed when we ran it on 2026-09-28. To test your own server, replace URL and start your server before it (for example with node build/index.js &, or use the stdio form from step 2).

#!/usr/bin/env bash
set -euo pipefail
URL="https://wiki.drfritzi.at/mcp"   # placeholder: your server
INSPECT="npx -y @modelcontextprotocol/inspector --cli $URL --transport http"

$INSPECT --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("search_answers")' > /dev/null

$INSPECT --method tools/call --tool-name search_answers --tool-arg query=inspector --format json \
  | jq -e '.result.isError == false' > /dev/null

set +e; $INSPECT --method tools/call --tool-name no_such_tool >/dev/null 2>err.json; code=$?; set -e
[ "$code" -eq 5 ] || { echo "expected exit 5, got $code"; exit 1; }

On a non-zero exit the CLI also writes one JSON line to stderr, such as {"error":{"code":"tool_not_found","message":"Tool 'no_such_tool' not found on server."}}. For servers behind OAuth, add --stored-auth-only so CI fails fast instead of waiting for a browser.

Which view shows which symptom

Symptom	Where to look
Tool missing from the list	--method tools/list, or the Tools tab
Wrong arguments or schema	Tools tab: schema form and rendered result
A stdio server crashes or prints diagnostics	Console tab (the process's stderr)
HTTP status, header or body problem	Network tab (HTTP and SSE servers only)
Malformed JSON-RPC or a spec error	Protocol tab (JSON-RPC transcript)
Server logs missing on a 2026-07-28 connection	Logs tab: the log level is set per request, and Off sends none
CI needs to branch on failure	CLI exit code 3, 4 or 5

Common mistakes

• Putting --cli after your server command. It must come first.
• Testing only the default legacy era, then shipping to 2026-07-28 clients.
• Piping the default --format text output into jq. Use --format json.
• Opening localhost:6274 without the token from the printed URL.
• Debugging a "Not connected" tool error (for example issue 1082) inside the client. Run the server alone in the Inspector first, to separate a server fault from client configuration.