Test and debug an MCP server with MCP Inspector, including scripted CLI mode for CI

Documented steps

1. One npx binary ships three clients — Web (default), CLI, and TUI — sharing transports, config files, and OAuth state; Node 22.19.0+ required. Docs: https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector
2. Interactive: npx @modelcontextprotocol/inspector node path/to/server/index.js — prints a URL with a one-time session token to open in the browser.
3. Scripted: npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list. For remote servers use --server-url <url> --transport http|sse; for a named server from a file use --config ./mcp.json --server myserver. Repeatable -e KEY=VALUE sets env vars, --cwd sets the stdio process working directory, --header "Name: Value" adds HTTP/SSE headers, and a bare -- separator passes flags through to the target command.
4. --method picks exactly one request per run: tools/list, tools/call (with --tool-name plus --tool-arg key=value [JSON-coerced] or --tool-args-json '{...}' [verbatim; mutually exclusive with --tool-arg]), resources/list, resources/read --uri <uri>, resources/templates/list, prompts/list, prompts/get, initialize, servers/list, servers/show. CLI reference: https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli
5. Machine-readable output: --format json, e.g. ... --method tools/list --format json | jq '.result.tools[].name'. Stream-only methods (logging/tail) are rejected in CLI mode since an exiting process can't hold a stream.
6. CI auth: pass --stored-auth-only to use only already-stored tokens and fail fast with auth_required instead of opening a browser; --use-stored-auth reuses/refreshes a token the web Inspector obtained on the same machine.
7. Branch on exit codes: 0 success, 1 usage/unexpected error, 2 no MCP App found, 3 auth required, 4 server unreachable, 5 tool error (tools/call returned isError:true or tool not found). On non-zero exit one JSON error line is written to stderr — parse with 2>&1 | tail -1 | jq .error.
8. CI recipe: mcp-inspector --cli --config ./ci-servers.json --server my-server --stored-auth-only --method tools/list --format json | jq -e '.result.tools | map(.name) | index("get_weather")' > /dev/null — fails the build if the tool is missing or the server unreachable.