How to Test an MCP Server With MCP Inspector

The fastest way to test an MCP server is to connect it to the official MCP Inspector, confirm initialization and capability negotiation, inspect every exposed schema, run one safe valid call, and then repeat the call with invalid input. Do this before adding the server to Claude Code, Codex, or another agent client. It separates server and protocol failures from client configuration problems.

This guide covers local stdio servers, remote Streamable HTTP servers, repeatable command-line checks, expected results, and the failures that usually reveal the real bug.

Prerequisites

You need:

• Node.js 22.7.5 or later;

• a built MCP server command or a remote MCP endpoint;

• test credentials with the least privilege needed;

• one harmless tool call with a predictable result;

• a terminal that can run npx.

Do not test a destructive tool against production data. Use a sandbox account or a read-only operation first. Never paste production tokens into screenshots, issue reports, or shell history.

Step 1: Start MCP Inspector

For a local TypeScript server built at build/index.js, run:

npx @modelcontextprotocol/inspector node build/index.js

The Inspector starts a browser UI on http://localhost:6274 and a local proxy on port 6277. Expected result: the browser opens with the proxy session token already filled in and the connection reaches the server.

If your server needs arguments, put them after the server command. Pass test-only environment variables with -e:

npx @modelcontextprotocol/inspector \
  -e API_BASE_URL=https://sandbox.example.com \
  -e API_TOKEN="$TEST_API_TOKEN" \
  node build/index.js --read-only

Use -- when a server argument could be mistaken for an Inspector flag:

npx @modelcontextprotocol/inspector -- node build/index.js -e server-flag

Expected result: the server stays running and the Inspector shows its negotiated capabilities. If the process exits immediately, solve that before changing any agent client configuration.

Step 2: Verify Initialization Before Testing Tools

Connect, then inspect the initialization exchange and server capabilities. Check that:

1. the client and server agree on a protocol version;

2. the server advertises only features it implements;

3. tools, resources, or prompts appear when you expect them;

4. the notification pane does not show a startup exception.

MCP requires initialization to be the first client-server interaction. A connection can exist while capability negotiation is still wrong, so a green process alone is not enough.

Expected result: the Inspector lists the capabilities your server advertised. If the Tools tab is missing, inspect the initialization response instead of debugging tools/list in the agent client.

For stdio, keep logs on stderr. The MCP transport reserves stdout for valid JSON-RPC messages. A single debug console.log on stdout can corrupt the stream and make a healthy tool look disconnected.

Step 3: Inspect Every Tool Schema

Open the Tools tab and select each tool. Check its name, description, input schema, required fields, enum values, defaults, and annotations.

A schema should answer these questions without guesswork:

• What operation will run?

• Which inputs are required?

• Which values are valid?

• Is the operation read-only, destructive, or idempotent?

• What does a successful result contain?

Expected result: every tool returned by tools/list renders without a schema error, and the displayed form matches the inputs the implementation actually validates.

This is also where stale metadata becomes visible. If the server accepts a field that tools/list does not declare, an agent may never send it. If the schema marks an optional field as required, the client may reject a valid call before it reaches your code.

Step 4: Run One Valid, Harmless Call

Choose a read-only tool with a deterministic result, such as listing a small sandbox collection or fetching a known record. Enter the smallest valid input and run it.

Record four things:

Expected result: the tool returns the known record or small list, isError is not true, and the notification pane contains no hidden exception.

A successful HTTP status is not sufficient. MCP distinguishes protocol errors from tool execution errors. An API failure can arrive inside a valid JSON-RPC result with isError: true, so inspect the body too.

Step 5: Test Invalid Input on Purpose

Now repeat the call with one controlled mistake:

• omit one required field;

• use an invalid enum value;

• pass the wrong scalar type;

• request a sandbox record that does not exist.

Expected result: the server rejects the request clearly, does not perform the operation, and returns enough context to fix the input without leaking secrets or internal stack traces.

Test one failure at a time. A request containing five mistakes proves only that something failed. A narrow negative test proves which contract the server enforces.

Also test a timeout or cancellation path if the tool can run for a long time. The MCP lifecycle guidance recommends a bounded timeout for every request and cancellation when the client stops waiting.

Step 6: Test Resources, Prompts, and Notifications

If the server advertises more than tools, verify those surfaces independently:

• Resources: list resources, read a known resource, inspect its MIME type, and test subscriptions only when advertised.

• Prompts: list prompts, verify arguments, render one with valid input, and omit a required argument once.

• Notifications: confirm list-change, progress, and logging notifications arrive only when the negotiated capability permits them.

Expected result: the server never sends a feature the client did not negotiate. A common -32602 Invalid params failure can come from a capability mismatch, not only a malformed tool argument.

Step 7: Test a Remote Streamable HTTP Server

For a remote endpoint, select Streamable HTTP in the UI and enter the full MCP URL, such as https://mcp.example.com/mcp. Use a test token through the Inspector's authentication field rather than placing it in the URL.

The same check can run from the command line:

npx @modelcontextprotocol/inspector --cli \
  https://mcp.example.com/mcp \
  --transport http \
  --method tools/list

Expected result: the endpoint accepts initialization, preserves the negotiated protocol version and session state, and returns its tool list.

For HTTP authorization, distinguish these failures:

The MCP transport specification requires remote servers to validate Origin, bind local development servers to localhost when possible, and authenticate connections. Do not disable those checks to make a test pass.

Step 8: Turn the Working Check Into a Repeatable Command

Once the UI call works, capture the same contract in Inspector CLI mode:

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

Then call the harmless tool:

npx @modelcontextprotocol/inspector --cli \
  node build/index.js \
  --method tools/call \
  --tool-name list_sandbox_items \
  --tool-arg limit=1

Replace the example tool and argument with your server's real read-only contract. Add the valid call and one invalid-input assertion to the server's test suite or CI. Do not put a long-lived token directly in the command.

Expected result: a clean checkout can run the same test without opening an agent client, and a schema or transport regression fails at the MCP boundary.

Common MCP Inspector Failures

spawn ENOENT or the Server Exits Immediately

The executable, build output, or working directory is wrong. Run the server command without Inspector, use an absolute build path when necessary, and confirm its required environment variables exist.

The Server Connects but No Tools Appear

Inspect the initialization response and server logs. The server may not advertise tools, tools/list may throw, or startup logging may have polluted stdout on a stdio connection.

-32602 Invalid params

Compare the submitted JSON to the current input schema. Then inspect capability negotiation. The same code can indicate malformed arguments or a request for a capability the other side never declared.

The Tool Returns a Result but the Operation Failed

Check for isError: true in the tool result. JSON-RPC transport success does not turn an upstream API failure into an MCP tool success.

Remote Authentication Loops

Check the exact endpoint, HTTPS configuration, OAuth metadata, token audience, expiry, scopes, and redirect URI. A 401 calls for a valid token; a 403 calls for the required permission or a valid origin. Repeatedly retrying the same token does not fix either condition.

Inspector Times Out Before the Server

The Inspector and server have separate timeout settings. Set a realistic client timeout for an intentionally long test, keep a maximum bound, and verify progress notifications rather than making the timeout infinite.

The Test Works in Inspector but Fails in Claude Code or Codex

The MCP server boundary is probably healthy. Compare the client launch command, working directory, environment, transport, protocol version, and credentials. Follow the focused guide to fix an MCP server that fails to connect in Claude Code.

Why This Test Order Works

The sequence isolates one layer at a time. Startup proves the server can run. Initialization proves protocol and capability agreement. Schema inspection proves discoverability. A valid call proves execution. An invalid call proves enforcement. CLI mode makes the verified boundary repeatable.

It follows the same structure that made Aident's Ollama networking fix useful: match the reader's exact problem, give the direct answer, show reproducible steps, state the expected result, and diagnose concrete failures.

Inspector does not replace end-to-end testing in your target client. It also does not solve the operational cost of attaching many large tool catalogs. For those decisions, compare local and remote MCP servers, review MCP API keys versus OAuth, and use the MCP token-usage checklist.

After the raw server contract passes, test one managed integration through the same agent workflow:

Follow https://aident.ai/SETUP.md
Confirm my Aident Loadout account and Vault status.
Find one connected read-only Action, inspect its current input schema, and run it
once with a harmless input. Show the exact result and do not perform 

Use Aident Loadout to complete one read-only Action after your MCP Inspector check. Measure success as one schema-inspected Action that returns the expected result without copying a provider credential into the prompt.

Sources

• MCP Inspector documentation, Model Context Protocol, accessed July 25, 2026

• MCP debugging guide, Model Context Protocol, accessed July 25, 2026

• MCP Inspector repository and CLI reference, Model Context Protocol, accessed July 25, 2026

• MCP lifecycle specification, Model Context Protocol, accessed July 25, 2026

• MCP transport specification, Model Context Protocol, accessed July 25, 2026

• MCP authorization specification, Model Context Protocol, accessed July 25, 2026

• MCP tools specification, Model Context Protocol, accessed July 25, 2026

Refresh this guide when MCP Inspector changes its Node.js requirement or CLI flags, or when a new MCP specification revision changes transports, lifecycle, authorization, or tool error handling.