How to Debug Common MCP Server Connection and Handshake Issues

Debug MCP server connection failures by validating transport layers, inspecting TLS certificates, and analyzing JSON-RPC handshake payloads using automated tools like MCP Doctor or manual openssl and curl diagnostics.

Model Context Protocol (MCP) servers enable secure tool invocation for AI clients, but connection failures often occur during the initial handshake phase. According to the punkpeye/awesome-mcp-servers repository, most issues stem from transport misconfiguration, certificate errors, or JSON-RPC protocol mismatches. Understanding the exact failure point—whether during discovery, transport setup, or the initialize request—allows you to apply targeted fixes without guessing.

Understanding the MCP Connection Lifecycle

MCP communication follows a strict four-phase lifecycle. When any phase breaks, the connection fails before tool invocation begins.

Discovery

The client locates the server endpoint via URL (HTTP/SSE) or local executable path (stdio). Discovery failures typically result from incorrect configuration paths or DNS resolution errors.

Transport Setup

The client establishes a TCP connection for HTTP servers or spawns a subprocess for local executables. At this stage, firewalls, port mismatches, or missing binaries trigger immediate timeouts.

JSON-RPC Handshake

The client sends an initialize request with protocol version requirements. The server must respond with a JSON-RPC 2.0 payload containing its capabilities. Handshake rejection occurs when authentication is missing, parameters are malformed, or the server returns an incompatible protocol version.

Tool Invocation

Once the handshake succeeds, subsequent requests use the established channel. Failures here are rare and usually indicate server-side logic errors rather than connection issues.

Common Symptoms and Root Causes

Connection and handshake issues manifest through specific error patterns. Identifying your symptom narrows down the diagnostic path:

• Connection timeout: Indicates network firewalls, incorrect URLs, or servers not listening on the expected port. Verify with curl or nc to probe endpoint reachability.
• TLS/SSL errors: Stem from expired certificates, mismatched domains, or missing SNI. Use openssl s_client -connect host:port to inspect the certificate chain.
• JSON-RPC version mismatch: Occurs when the client expects RPC 2.0 but the server implements an older specification. Examine the initialize response—field jsonrpc must equal "2.0".
• Handshake rejection: Results from authentication failures, malformed requests, or security policies like mcp-guardian blocking the connection. Look for error codes -32602 (Invalid params) or -32000 (Server error) in the response payload.
• Unexpected payload: Signals transport framing issues, such as using HTTP when the server expects stdio or vice versa. Verify transport mode in your client configuration.

Step-by-Step Diagnosis with MCP Doctor

The punkpeye/awesome-mcp-servers repository lists MCP Doctor (realwigu/mcp-doctor) as the recommended first-line diagnostic tool. This utility automatically discovers local MCP configurations across Claude Code, Cursor, VS Code, Windsurf, and Claude Desktop, then performs a full JSON-RPC handshake test.

Run MCP Doctor without installation:

npx -y realwigu/mcp-doctor

The tool outputs a comprehensive report including handshake latency, TLS certificate validity, and protocol version compliance. When the handshake fails, MCP Doctor displays the exact JSON-RPC error payload, allowing you to distinguish between transport errors, authentication failures, and protocol incompatibility.

A successful handshake produces output similar to:

✔️  Discovered 3 MCP configs
🕒  Handshake latency: 42 ms
✅  JSON-RPC version: 2.0
🔐  TLS cert is valid until 2027-03-12

Failure output reveals specific error codes:

✖️  Handshake failed: {"jsonrpc":"2.0","id":1,"error":{"code":-32602,"message":"Invalid params"}}

Manual Troubleshooting Techniques

When automated tools are unavailable or you need to verify specific transport layers, manual diagnostics provide granular insight.

Validating Endpoint Reachability

Test basic connectivity before debugging protocol logic:

# HTTP endpoint check

curl -I https://my-mcp-server.example.com/mcp

# TCP port verification

nc -zv my-mcp-server.example.com 443

If these commands fail, the issue resides at the network or DNS layer rather than in MCP-specific logic.

Inspecting TLS Certificates

Certificate validation errors prevent secure HTTP connections. Inspect the full certificate chain and expiration dates:

openssl s_client -connect my-mcp-server.example.com:443 -servername my-mcp-server.example.com

Pay attention to Verify return code in the output. A value other than 0 indicates certificate trust issues that will cause MCP clients to reject the connection.

Testing the JSON-RPC Handshake Manually

For stdio-based servers, pipe a raw initialize request directly to the server executable:

cat <<EOF | node my-mcp-server.js
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
EOF

Valid responses contain {"jsonrpc":"2.0","id":1,"result":{...}}. Missing jsonrpc fields or error objects indicate protocol implementation bugs in the server.

Analyzing Error Codes and Payloads

JSON-RPC defines specific error codes that MCP servers use to report handshake failures. Check your server logs or MCP Doctor output for these values:

• -32602 (Invalid params): The initialize request is malformed or missing required fields. Verify your client sends the correct parameter structure.
• -32000 (Server error): Generic server-side failure during capability negotiation. Check the server's implementation of the initialize method for unhandled exceptions.
• -32700 (Parse error): Invalid JSON received by the server. Ensure proper content-type headers and newline framing for stdio transports.

For servers protected by mcp-guardian, review the policy configuration files. Security policies may explicitly reject clients based on origin headers or authentication tokens, resulting in handshake failures before JSON-RPC negotiation completes.

Summary

• MCP connections proceed through four phases: Discovery, Transport Setup, JSON-RPC Handshake (initialize), and Tool Invocation.
• Common failure points include network timeouts, TLS certificate errors, protocol version mismatches, and authentication rejections.
• MCP Doctor (realwigu/mcp-doctor) automates diagnosis by testing local configurations and reporting handshake latency, TLS validity, and JSON-RPC compliance.
• Manual debugging uses curl for reachability, openssl s_client for certificates, and raw JSON-RPC requests to isolate transport versus protocol issues.
• Error codes like -32602 and -32000 pinpoint whether failures stem from client parameters or server implementation bugs.

Frequently Asked Questions

What transport protocols do MCP servers support?

MCP servers support stdio (standard input/output) for local process communication and HTTP/SSE (Server-Sent Events) for remote network connections. Some servers, such as those listed in the punkpeye/awesome-mcp-servers collection, implement both transports simultaneously. Verify your client configuration matches the server's expected transport mode—using HTTP when the server expects stdio results in immediate payload errors.

How do I fix a JSON-RPC version mismatch error?

Ensure your client and server both implement JSON-RPC 2.0. When testing manually, your initialize request must include "jsonrpc":"2.0", and the server response must contain the same field. If the server omits this field or returns "2.0" in a different key, upgrade the server package to the latest MCP SDK version or patch the server's initialize method to return the correct protocol version.

Why does my MCP server reject the initialize request?

Handshake rejection typically stems from missing authentication headers, invalid parameter structures, or security policies like mcp-guardian. Capture the raw request/response pair using MCP Doctor or manual stdio piping. If the error code is -32602, inspect the params object for missing required fields. If using a security proxy, verify that your client presents valid credentials or origin headers as configured in the guardian policy.

Can I use MCP Doctor with Claude Desktop and VS Code?

Yes. MCP Doctor automatically discovers configurations for Claude Desktop, VS Code, Cursor, Windsurf, and Claude Code without requiring manual path entry. Run npx -y realwigu/mcp-doctor from any directory, and the tool scans standard configuration locations for each client, validating every discovered MCP server in sequence.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}