MCP, SSE, and HTTPS: Why Claude Code Fails to Connect — and How to Fix It

A deep dive into the Model Context Protocol, SSE and HTTP/2 issues, Anthropic’s transition to WebSocket, and the nginx configuration that keeps it all running.

What is MCP

Model Context Protocol (MCP) is the bridge that allows Claude Code to connect external tools and services.

It supports two transport modes:

• stdio — standard input/output, good for local development

• sse — Server-Sent Events, used for remote or networked access

Most MCP connection issues aren’t caused by code, but by infrastructure details: HTTP protocol quirks, nginx defaults, or strict schema validation recently introduced by Anthropic.

---

Common Symptoms

Running:

claude mcp list

returns:

infonux: https://example.com/mcp_server (HTTP) - ✗ Failed to connect

Logs show:

[Error] Does not adhere to MCP server configuration schema

Meanwhile:

• nginx responds correctly

• curl returns valid SSE events

• HTTPS and tokens work normally

If all that is true, the issue isn’t networking — it’s configuration and protocol compatibility.

---

Why HTTPS Sometimes Breaks Everything

SSE only works over HTTP/1.1.

HTTP/2 uses multiplexing, which interrupts persistent streams.

When that happens, MCP CLI can’t maintain the connection and shows:

✗ Failed to connect

Quick summary:

---

SSE and Anthropic’s Shift to WebSocket

In spring 2025, Anthropic began phasing out the classic HTTP + Server-Sent Events (SSE) transport in favor of new mechanisms:

• Streamable HTTP, still MCP-compatible and supporting bidirectional traffic;

• WebSocket, which provides a more stable, persistent, and transport-independent connection.

The updated MCP specification (March 2025) introduced:

• full JSON-RPC bidirectional support,

• compatibility with standard HTTP servers (no extra SSE endpoint required),

• fewer dependencies on proxy/CDN quirks,

• no need to maintain two simultaneous channels.

Why WebSocket Makes Sense

WebSocket enables true two-way communication and eliminates HTTP transport limitations.
It fits the interactive nature of modern AI interfaces and collaborative applications.
Anthropic maintains SDK compatibility, allowing a gradual migration without breaking existing infrastructure.

SSE remains temporarily supported but is now officially deprecated.

Future SDKs (starting with 2025 releases) use WebSocket as the default transport, with Streamable HTTP available for backward compatibility.

---

Minimal Working MCP Configuration

Incorrect:

{
  "type": "sse",
  "command": "http://localhost:3010",
  "args": [],
  "env": {},
  "headers": { "Authorization": "Bearer TOKEN" }
}

Correct:

{
  "type": "sse",
  "url": "http://localhost:3010",
  "headers": { "Authorization": "Bearer TOKEN" }
}

Key differences:

• url replaces command

• args and env are removed

• headers are optional

Anthropic now enforces strict JSON schema validation — if the structure doesn’t match, MCP simply refuses to connect.

---

nginx Configuration for HTTPS and SSE

HTTPS works perfectly if the server is configured correctly for SSE.

The essentials: use HTTP/1.1, enable IPv6, and extend timeouts.

Minimal example:

server {
    listen 8443 ssl;           # HTTP/1.1 only, no http2
    listen [::]:8443 ssl;      # IPv6 required

    ssl_certificate     /etc/letsencrypt/live/your-domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain/privkey.pem;

    location / {
        proxy_pass http://localhost:3020/;
        proxy_http_version 1.1;       # required
        proxy_set_header Connection "";
        proxy_buffering off;          # must be disabled for SSE
        proxy_read_timeout 86400;     # long-lived connection
    }
}

Avoid:

listen 443 ssl http2;     # breaks SSE
proxy_buffering on;       # interrupts the stream
listen 8443 ssl;          # missing IPv6 — Claude Code won't connect

More on nginx and SSL setup

Use a dedicated HTTPS port (e.g., 8443) and force proxy_http_version 1.1. Disable buffering, gzip, and short timeouts. A full production configuration is available in the official MCP Server Template repository.

---

Connection Testing

Test the SSE stream manually:

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer TOKEN" \
  https://your-domain.com:8443/sse

Expected output:

event: endpoint
data: /messages?sessionId=template-xxx

If that works, check via CLI:

claude mcp list

Result:

✓ Connected

---

Security and Alternatives

If exposing a public port isn’t ideal:

ssh -L 3020:localhost:3020 user@your-server.com -N &

Then connect locally:

claude mcp add my-server \
  http://localhost:3020/sse \
  --transport sse \
  --header "Authorization: Bearer TOKEN"

Recommendations:

• never use HTTP in production

• rotate tokens regularly

• monitor logs for unusual activity

• use VPN or SSH tunnels for private setups

---

Summary

1. HTTPS works if:

   • you use HTTP/1.1,

   • IPv6 is enabled,

   • buffering is disabled,

   • timeouts are long enough.

2. HTTP/2 is incompatible with SSE.

3. Anthropic is migrating from SSE to WebSocket and Streamable HTTP.

4. “Failed to connect” errors usually mean configuration issues, not network problems.

5. curl remains the most reliable diagnostic tool.

---

Conclusion

MCP runs reliably over HTTPS — as long as the server doesn’t interfere with the SSE stream.

Anthropic’s move to WebSocket simplifies the protocol, improves stability, and aligns with modern real-time AI communication standards.

Stick to HTTP/1.1, follow the schema, and configure nginx carefully — the rest will just work.

---

Further Reading

• Official MCP Documentation

• MCP SDK (TypeScript)

• Anthropic Claude Code Docs

• Server-Sent Events vs WebSocket – MDN Overview

• nginx Proxying and HTTP/2 Limitations

---

Full nginx configuration and MCP Server Template:

github.com/modelcontextprotocol/typescript-sdk