#1MCP server testing: verify the handshake before shipping

What we tested: We counted tokens across multiple model families (GPT-4o, Claude, Gemini) using our LLM token counter. Prompt caching behavior was tested with repeated inputs of varying length.

MCP is only useful if the server behaves correctly when a real host connects to it.

The practical test is simple: check the handshake, tool listing, resource reads, and error paths before you let a client rely on the server.

#2Why MCP Matters Now

In December 2025, Anthropic donated MCP to the Linux Foundation's new Agentic AI Foundation. By Q2 2026, every major AI platform speaks it natively: Claude, ChatGPT, Cursor, Gemini, Microsoft Copilot, GitHub Copilot, VS Code, Windsurf, plus first-class client support in LangChain, LlamaIndex, AutoGen, and CrewAI. Microsoft built MCP into GitHub Copilot, Microsoft 365 Copilot, and Azure AI Foundry, putting it into Fortune 500 production at scale.

Think of MCP as USB-C for AI assistants, one connector that works across every host. The result: any new AI tool that does not publish an MCP server faces an immediate adoption barrier.

#2The Wire Format: JSON-RPC 2.0

MCP messages are JSON-RPC 2.0 over a transport. Two transports are in production:

1. stdio, local servers, launched as subprocesses by the host (Claude Desktop, Cursor, etc.)
2. HTTP with Server-Sent Events, remote servers, hosted on the network, no installation required

A request looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

A successful response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ]
  }
}

An error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

The id field must round-trip; the host correlates responses to requests by it.

#2The Three Primitives

#31. Tools, actions the model can invoke

A Tool has a name, a description (the model reads this to decide when to call it), and a JSON Schema for inputs. The host model calls tools/call:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "Bengaluru" }
  }
}

The server returns content blocks, text, images, or embedded resources, that the host injects back into the model's context.

#32. Resources, data the model can read

Resources are addressable by URI. The host lists them with resources/list and reads them with resources/read:

{
  "method": "resources/read",
  "params": { "uri": "file:///project/README.md" }
}

Resources can be static (a file) or dynamic (a database query result). Use them for read-only context; use Tools when you want side effects.

#33. Prompts, reusable templates

Prompts are pre-built message templates the user can invoke (e.g., a "summarise PR" template). They surface in the host UI as slash commands or menu entries.

#2The Handshake

Every MCP session begins with initialize:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "resources": { "subscribe": true }
    },
    "clientInfo": { "name": "your-host", "version": "1.0.0" }
  }
}

The server replies with its own capabilities. Only after initialize returns can the host call tools/list, resources/list, etc. Skipping the handshake is the #1 cause of "my server doesn't respond" bug reports.

#2Testing a Local stdio Server

When Claude Desktop or Cursor launches a local server, it pipes JSON-RPC over stdin/stdout. To test by hand:

# Send an initialize request to the server binary
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1"}}}' \
  | node ./my-mcp-server.js

A correct server will:

1. Print the initialize response to stdout
2. Wait for the next message (do not exit)
3. Honour tools/list, tools/call, etc.

If the process exits after the first response, you have a stdio buffering bug, usually missing flushes or printing to stderr. A common Python mistake is print(..., flush=True) vs forgetting flush.

#2Testing a Remote HTTP Server

Remote MCP servers shipped over HTTP+SSE are the dominant 2026 deployment pattern, no install, central updates, OAuth-friendly. To test:

curl -X POST https://mcp.example.com/sse \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

You should get a text/event-stream response with the JSON-RPC reply as the first event.

For interactive end-to-end checks, list tools, call one, watch the response, the in-browser MCP Server Tester handles the SSE plumbing and renders responses without you writing a client. The tester runs entirely client-side, so your bearer tokens never leave the browser tab.

#2The Q2 2026 Enterprise Surface

MCP's published 2026 roadmap moves the protocol into regulated industries:

• OAuth 2.1 + PKCE for browser-based agent flows, the standard pattern is now authorization_code with PKCE, refresh tokens optional
• SAML / OIDC integration for enterprise identity providers, healthcare, finance, legal, government
• Remote-first deployment, stdio servers are becoming legacy; hosted HTTP endpoints with token auth are the default
• Tool composition, agents chaining multiple MCP tools across vendors in one workflow

If you are shipping a new MCP server in 2026, design it remote-first with OAuth-protected endpoints. Verify the token, scope each tool call, and log every invocation by clientInfo.name for audit.

A clean OAuth flow check:

# Step 1, the host gets an authorization code (browser flow with PKCE)
# Step 2, exchange code for access token
curl -X POST https://auth.example.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "code_verifier=$VERIFIER" \
  -d "client_id=$CLIENT_ID"

# Step 3, call the MCP server with the token
curl -X POST https://mcp.example.com/sse \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '...'

If you need to inspect the access token returned by the OAuth provider, header, claims, expiry, paste it into the JWT Decoder, which decodes locally and never sends the token anywhere.

#2The Most Common Failure Modes

After hundreds of MCP servers in the wild, the same problems keep showing up.

#31. Missing or wrong protocolVersion

The handshake fails silently if the server replies with a version the host doesn't accept. The current stable string is 2025-06-18. Older 2024-11-05 servers still work with most hosts but are being phased out.

#32. Tool descriptions the model can't reason about

Bad: "description": "runs the function". The model has no idea when to call this. Good: "description": "Fetches the current weather (temperature, conditions, wind) for a single city. Use when the user asks about weather or planning outdoor activity.". The description is the prompt for tool selection, write it like one.

#33. JSON Schema that's almost-but-not-quite valid

additionalProperties: false strict-mode hosts will reject a tool call with an extra argument. JSON Schema dialect mismatches (draft-07 vs 2020-12) cause silent validation failures. Test every tool with a payload from your real client, not a synthetic one.

#34. Non-idempotent Tools without warnings

If a Tool sends an email or charges a card, the schema should declare it. Many hosts will retry on network blips. Hosts that support the idempotency hint will only call non-idempotent tools after user confirmation. Set the hint, or be defensive on the server.

#35. Token expiry mid-session

Long agent runs can exceed a token's lifetime. Servers should return a JSON-RPC error with code -32001 (custom) and an auth_required field; well-behaved hosts will trigger a token refresh and replay the request. Without this, the agent appears to silently stop working.

#36. SSE keep-alive missing

Remote HTTP+SSE servers must send a heartbeat (a comment line : ping\n\n) every 15–30 seconds. Without it, Cloudflare, AWS ALB, and most corporate proxies will idle-timeout the connection and the host will lose all subscribed resources.

#2A Production-Ready Checklist

Before publishing an MCP server:

• [ ] initialize returns within 100ms with the correct protocolVersion
• [ ] tools/list returns at least one tool with a model-friendly description
• [ ] Every tool has a JSON Schema validated against its real input
• [ ] At least one end-to-end tools/call works from a real host (Claude Desktop or Cursor)
• [ ] OAuth-protected if hosted; rotate tokens on expiry
• [ ] SSE heartbeat every 20 seconds for HTTP transport
• [ ] Logs every call with clientInfo, tool name, latency, and outcome
• [ ] Idempotency hints set on side-effect tools
• [ ] Rate limits enforced per client (the agent will hammer you)
• [ ] Verified with the MCP Server Tester before publishing

#2Frequently Asked Questions

Q: Does MCP require a network connection? No. The stdio transport runs entirely locally, host and server communicate over pipes, no socket. The HTTP+SSE transport is only used for hosted servers.

Q: What's the difference between an MCP Tool and an OpenAI function call? OpenAI function calls are a vendor-specific JSON shape inside a single model call. MCP is a full protocol with capability negotiation, multi-tool servers, resource streaming, and authentication. An MCP Tool can be exposed as an OpenAI function by the host, but the reverse is not true.

Q: Can I write an MCP server in any language? Yes, any language that can speak JSON-RPC over stdio or HTTP. Official SDKs exist for Python, TypeScript, Go, Rust, Java, C#, and Swift.

Q: Do I need OAuth for a local stdio server? No. Local servers inherit the trust boundary of the host application. OAuth is for hosted HTTP servers where multiple users connect.

Q: How do I debug a server that the host says is "not responding"? Run the server manually with a hand-crafted initialize request piped to stdin. If you get a reply, the bug is in the host config (path, env vars). If you don't, the bug is in your server, check stderr for crashes, and verify you are flushing stdout after each response.

Q: What's the difference between Resources and Tools? Resources are read-only data the model can pull (a file, a database row, a Notion page). Tools are actions that may have side effects (send email, create issue, run query). When in doubt: if it changes state, it's a Tool.

Q: Does the in-browser MCP tester support OAuth-protected servers? Yes, the MCP Server Tester accepts a bearer token directly. The token stays in your browser tab; nothing is uploaded.

#2Closing

MCP went from "interesting Anthropic experiment" to "the way AI assistants integrate with everything" in less than two years. If you ship developer tools in 2026, an MCP server is no longer optional, it is how Claude, ChatGPT, Cursor, and Copilot will be able to use your product without you building bespoke integrations for each. Get the handshake right, write tool descriptions a model can reason about, and test end-to-end with a real host before you publish. The protocol is simple; the corner cases are where the work lives.

Related: Server-Sent Events vs WebSockets vs Long Polling · JWT Tokens Explained · What is MCP, Complete 2026 Guide

Written by Rahul Jalavadiya, founder of AllDevToolsHub. All tools run locally in your browser.

#2Sources / Further reading

• Model Context Protocol - Official documentation
• Model Context Protocol - Inspector tool
• Anthropic - Tool use best practices

#2Try These Tools

• Json Formatter
• Http Request Builder