# How to Debug Common MCP Server Connection and Handshake Issues > Fix common MCP server connection and handshake problems. Learn to debug transport layers, TLS certificates, and JSON-RPC payloads with MCP Doctor, openssl, and curl. - Repository: [Frank Fiegel/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) - Tags: how-to-guide - Published: 2026-09-05 --- **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: ```bash 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: ```bash # 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: ```bash 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: ```bash cat <