How do I test an MCP server?

Test an MCP server by performing the protocol lifecycle it will face in production: POST a JSON-RPC 2.0 initialize request to the streamable-HTTP endpoint, verify it returns a protocolVersion, serverInfo and capabilities; send notifications/initialized; then call tools/list and confirm every tool has a clear description and a valid inputSchema. Also check HTTPS, handshake latency and authentication. You can run all of this automatically with a free scanner like MCP Pulse.

What is the MCP initialize handshake?

initialize is the first JSON-RPC call an MCP client makes. The client sends its protocolVersion, capabilities and clientInfo; the server replies with the protocolVersion it will use, its own capabilities and serverInfo (name and version). The client then sends a notifications/initialized notification before making further calls like tools/list.

Why won't my MCP server connect in Claude or Cursor?

The most common causes are: the endpoint isn't served over HTTPS, it doesn't return a valid JSON-RPC initialize result, it requires an Mcp-Session-Id header that the client isn't sending back, the transport is stdio/legacy-SSE rather than streamable HTTP, or CORS/auth is blocking the request. Scanning the endpoint reveals which of these is failing.

MCPPulse

Guide · Updated July 2026 · 7 min read

How to test an MCP server

Direct answer: Test your MCP server the way a real client will drive it — the full protocol lifecycle, not a ping. Four layers: (1) transport reachable over HTTPS, (2) a valid JSON-RPC initialize handshake, (3) tools/list with well-described tools and valid input schemas, (4) latency and auth. You can do it by hand with curl, with the MCP Inspector, or automatically with the free MCP Pulse scanner.

What "testing an MCP server" actually means

An MCP server isn't a normal REST API — clients like Claude, Cursor and agent frameworks speak a specific JSON-RPC 2.0 lifecycle over a transport (today: streamable HTTP, which may respond with plain JSON or an SSE stream). "It returns 200" tells you nothing. What matters is whether the client can complete the handshake, enumerate your tools, and understand them well enough to call them.

1. Transport & reachability

Served over HTTPS — most clients refuse plaintext remote endpoints.
Accepts POST with Content-Type: application/json and Accept: application/json, text/event-stream.
If you issue a session, you return an Mcp-Session-Id response header and honor it on subsequent requests.

2. The initialize handshake

This is the make-or-break call. A minimal manual test:

curl -sN https://your-server.example.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"test","version":"1.0"}}}'

A healthy response contains result.protocolVersion, result.serverInfo (name + version) and result.capabilities. If any is missing, clients and registries can't identify or route to your server.

3. tools/list and tool quality

After initialize, send the notifications/initialized notification, then call tools/list. For each tool, verify:

A meaningful description — agents choose tools by their description, not their code. An undocumented tool is invisible in an agent workflow.
A valid inputSchema (JSON Schema) so the client knows how to call it.

This is the single most common gap we see: servers that respond perfectly but ship tools with empty or one-word descriptions, then wonder why agents never call them.

4. Latency & auth

Agents run multi-step chains — a 2-second handshake compounds across every hop. Measure it. And decide your auth posture deliberately: a public read-only server answering without auth is fine; a server whose tools mutate state or reach private data should require an Authorization header.

The fast way: automated scan

Doing all four layers by hand for every deploy is tedious. MCP Pulse runs the real initialize + tools/list handshake, scores conformance, tool-doc coverage, latency, TLS and auth 0–100, and tells you exactly what to fix — in 10 seconds, no signup.

Test your MCP server now

Real protocol handshake, free, 10 seconds.

Scan my server →