# 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:

```bash
claude mcp list
```

returns:

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

Logs show:

```bash
[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:

```bash
✗ Failed to connect
```

**Quick summary:**

| **Protocol** | **Works with SSE** |
| --- | --- |
| HTTP/1.1 | ✅ Yes |
| HTTP/2 | ❌ No |

---

## **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.
    

<details>
<summary>Why WebSocket Makes Sense</summary>

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.

</details>

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:**

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

**Correct:**

```bash
{
  "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:**

```bash
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:**

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

<details>
<summary>More on nginx and SSL setup</summary>
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.
</details>

---

## **Connection Testing**

Test the SSE stream manually:

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

Expected output:

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

If that works, check via CLI:

```bash
claude mcp list
```

Result:

```bash
✓ Connected
```

---

## **Security and Alternatives**

If exposing a public port isn’t ideal:

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

Then connect locally:

```bash
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](https://modelcontextprotocol.io/)
    
* [MCP SDK (TypeScript)](https://github.com/modelcontextprotocol/typescript-sdk)
    
* [Anthropic Claude Code Docs](https://claude.ai/docs)
    
* [Server-Sent Events vs WebSocket – MDN Overview](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)
    
* [nginx Proxying and HTTP/2 Limitations](https://nginx.org/en/docs/http/ngx_http_proxy_module.html)
    

---

**Full nginx configuration and MCP Server Template:**

[github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk)