How to test an MCP server: the Inspector, raw requests and the failures to check before you submit

A directory reviewer tests your MCP server by using it, so test it the same way first. That means five checks: the server connects and lists its tools, every tool works, bad input fails cleanly, a reviewer can sign in, and all of it still holds after your next release. Every command below was run against our own server, mcp.invokary.com, on October 10 and 11, 2026, with MCP Inspector 2.10.1 and curl. Your server's answers will differ; what they should look like comes from the MCP specification, linked in each section.

1. List the tools with the MCP Inspector

The MCP Inspector is the protocol's reference testing tool. One package gives you a web UI, a terminal UI and a command-line client, and it needs Node 22.19.0 or newer. For a remote server, point the CLI at its URL:

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

For a server that runs on your own machine, pass the command that starts it instead of the URL, and leave out --transport. Run npx @modelcontextprotocol/inspector with no arguments for the web UI, which shows the same list and the raw JSON-RPC messages side by side.

Then read every tool the way a reviewer will:

• The name is 64 characters or fewer, and the tool has a title.
• The description says what the tool does and when to use it, and gives the model no orders.
• readOnlyHint, destructiveHint and openWorldHint are set, and true to what the tool does.
• No single tool both reads and writes.

2. Call every tool with good input, then bad

A good call should return what its description promises:

npx @modelcontextprotocol/inspector --cli https://mcp.invokary.com/mcp --transport http \
  --method tools/call --tool-name get_platform_requirements --tool-arg platform=cursor --format json

Then call each tool with input that's wrong: a value outside an enum, a missing required field, an id that doesn't exist. The specification separates two kinds of error. Bad input to a real tool should come back as a normal result with isError: true and a message the model can act on. A call to a tool that doesn't exist is a protocol error. With platform=myspace, our server returned this as the result's text, with isError: true:

Input validation error: Invalid arguments for tool get_platform_requirements: platform: Invalid option: expected one of "claude"|"chatgpt"|"cursor"|"mcp-registry"|"ecosystem"

The Inspector's CLI exits with code 5 on a result like this, and writes a one-line JSON error to stderr:

{"error":{"code":"tool_is_error","message":"Tool 'get_platform_requirements' returned isError:true."}}

A good error names the allowed values or the closest match, so the agent can retry without asking the user. Our guide to MCP server best practices shows the pattern.

3. Check the transport with raw requests

The Inspector speaks the protocol correctly, so it can hide transport mistakes that another client or a proxy will hit. A raw request shows exactly what the endpoint expects. In the 2026-07-28 revision of Streamable HTTP, every request is a POST to one endpoint, the Accept header lists both application/json and text/event-stream, and the protocol version, the method and (for a tool call) the tool name are sent both as headers and in the body:

curl -s https://mcp.invokary.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl-test","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

Then send the requests a careless client or an attacker would, and compare the answers with the specification:

• An Mcp-Name header that differs from the tool name in the body. The specification asks for 400 with JSON-RPC error -32020 (HeaderMismatch). Ours answered 400 and -32020, naming both values.
• No Mcp-Method header. Expected: 400 with -32020. Ours: 400, -32020.
• tools/call for a tool that doesn't exist. Expected: a protocol error. Ours: JSON-RPC error -32602, "Tool no_such_tool not found".
• Arguments that fail validation. Expected: a result with isError: true. Ours: isError: true, listing the allowed values.
• A GET to the endpoint. Expected: 405 from a server that supports only this revision. Ours: 405.
• An initialize request from a 2025-11-25 client, with none of the new headers. Expected: either the old protocol, or an error the client can recognize. Ours: 200, negotiated 2025-11-25.
• An Origin header from a site you don't trust. Expected: 403 when the origin is invalid, to block DNS rebinding. Ours: 200, because our server is public, read-only and has no sign-in, so every origin is allowed on purpose.

The Origin answer is a choice each server makes. A server that reaches user data, or one that runs on a developer's machine, must reject origins it doesn't trust.

4. Sign in the way a reviewer will

If your server needs sign-in, the reviewer will use the test account you give them, from a browser that has never seen your product:

• Claude asks for test credentials for a fully populated account. An empty account gives the reviewer nothing to check.
• ChatGPT asks for credentials that work without MFA, SMS or email codes, or private-network access, on a dedicated test account with sample data.

So sign in to the test account from a fresh browser profile, outside your office network, and connect the server through the Inspector's web UI, which runs the full OAuth flow. Then run the same tool calls as in section 2. In CI, the CLI's --stored-auth-only flag reuses a token you saved earlier and fails with exit code 3 instead of waiting for a browser. Our guide to MCP OAuth for SaaS connectors covers what the sign-in itself has to do.

5. Test what the model does with your tools

A server can pass every check above and still go unused, because the model never picks it, or picks it at the wrong time. ChatGPT's submission makes this explicit: it requires exactly five positive and three negative test cases. Each positive case names the tools it should trigger and the behavior you expect. A negative case is a prompt where your tools should not be used.

Write those eight cases even if you start with Claude, and run each one by hand in every client you'll list in. Note which tool the model called and whether the answer matched what you expected. Our own server's eval set uses the same five positive and three negative cases.

6. Run the checks in CI

The Inspector's CLI is built for scripts: every run connects, makes one request, prints the result and exits with a code that says what went wrong. This fails the build when a tool you rely on disappears:

npx @modelcontextprotocol/inspector --cli https://mcp.invokary.com/mcp --transport http \
  --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("get_requirement")'

The exit codes, from the Inspector's documentation:

• 0: success.
• 3: the server needs sign-in.
• 4: the server can't be reached.
• 5: a tool returned isError: true, or wasn't found.
• 6: --strict found a tool schema that won't work in every client.

We saw 0, 4 and 5 in our runs. Add --strict to the tools/list step to catch schema problems too. Directories keep reading your tools after launch (OpenAI rescans its listed servers), so this gate belongs on every release, not just the first.

Checklist before you submit

1. The Inspector lists every tool, and each has a name of 64 characters or fewer, a title, a description that says when to use it, and explicit hints.
2. Every tool returns what its description promises for a good input.
3. Bad input returns isError: true with a message that says how to fix the call.
4. A call to a tool that doesn't exist returns a protocol error, not a crash.
5. Raw POSTs with the 2026-07-28 headers work, and mismatched or missing headers get 400.
6. GET on the endpoint answers 405, and old clients either work or get a clear error.
7. The Origin policy is a deliberate choice, and any server with user data rejects origins it doesn't trust.
8. The test account signs in from a fresh browser outside your network, with no second factor, and has real-looking data.
9. Five positive and three negative prompts run in each client, with the tool called and the result written down.
10. CI runs tools/list on every release and fails on a missing tool or a schema problem.

Where we come in

The Agent Distribution Audit runs these checks on your server and turns the failures into a fix list, priced. After launch, Connector Care keeps running them. Each directory's own rules, with their sources and check dates, are on our Claude and ChatGPT pages.