How to test an MCP server

An MCP server can pass a unit test and still fail in a real client because of a stray log line on stdout, a bad schema or a protocol-version mismatch. This is a practical test routine using the official MCP Inspector, from first run to CI.

Lint the tool definitions#

Start with the cheapest check. Get your server's tools/list output (step 3 shows how) and paste it into the MCP tool linter. It catches invalid names, missing or broken inputSchema, x-mcp-header mistakes and missing annotations, all in your browser.

Explore it in MCP Inspector#

MCP Inspector is the official interactive tool for testing and debugging MCP servers. It needs Node.js 22.19.0 or newer. Run it with your server's start command:

npx @modelcontextprotocol/inspector node build/index.js

This opens a web UI where you can list tools, call them with your own arguments, and see the raw requests and responses. Inspector also has a terminal UI (--tui). For a remote server, pass its URL:

npx @modelcontextprotocol/inspector --server-url https://example.com/mcp --transport http

Script checks with the Inspector CLI#

The --cli mode makes one request and prints the result, which is what you want for scripts:

# List tools as JSON
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list --format json

# Call one tool with arguments
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name get_alerts --tool-arg state=CA

--tool-arg key=value values are parsed as JSON where possible, so numbers and booleans arrive with the right type. For nested arguments use --tool-args-json. Save the tools/list output and paste it into the linter.

Test both protocol eras#

Inspector defaults to the legacy protocol era, which only exercises the 2025-era initialize handshake. The official quickstart recommends running the same check twice so you know the server answers both kinds of client:

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

If the modern run fails on a TypeScript server, check that you're using serveStdio with a factory rather than wiring the transport by hand. See MCP server examples.

Run a smoke test in CI#

The Inspector repository has a guide to smoke-testing servers from the shell. The key points:

• Pin an exact Inspector version rather than using latest, so a new release can't break your build.
• Pass --yes so npx doesn't stop to ask for confirmation.
• The CLI exits with a non-zero code on failure, including exit code 5 when a tool returns a result with isError: true. Let that fail the job.

# .github/workflows/mcp-smoke.yml (excerpt)
- run: npm ci && npm run build
- run: npx --yes @modelcontextprotocol/inspector@X.Y.Z --cli node build/index.js --protocol-era modern --method tools/list
- run: npx --yes @modelcontextprotocol/inspector@X.Y.Z --cli node build/index.js --protocol-era modern --method tools/call --tool-name get_alerts --tool-arg state=CA

Replace X.Y.Z with the version you've tested against.

Try it in a real client#

Finally, connect the server to a host using its config file (see Claude Desktop and Cursor setup). If it doesn't appear or calls fail silently, Claude Desktop writes MCP logs to ~/Library/Logs/Claude/mcp*.log on macOS, with a separate log of each server's stderr.

Common failures#

Frequently asked questions#

Sources#

• MCP docs: MCP Inspector (checked 20 Oct 2026)
• MCP Inspector repository: Smoke-testing an MCP server from the shell (checked 20 Oct 2026)
• MCP docs: Build an MCP server (checked 20 Oct 2026)
• MCP specification: Server / Tools (checked 20 Oct 2026)