MCP server WebSockets

How StreamableHTTP works

The StreamableHTTP transport uses two HTTP routes on the same server:

The mcp-session-id header correlates POSTs with the GET SSE stream. A client opens a GET connection to receive server-initiated notifications (progress updates, tool list changes), then sends all requests as individual POSTs. The session is symmetric in that both parties can initiate communication — the client via POST, the server via the SSE stream — but the transport itself is plain HTTP, not a WebSocket.

// Express StreamableHTTP setup — two routes, same path, different methods
import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const app = express();
const sessions = new Map<string, { server: McpServer; transport: StreamableHTTPServerTransport }>();

// POST /mcp — handle incoming requests and initialize new sessions
app.post('/mcp', express.json(), async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string;

  if (sessionId && sessions.has(sessionId)) {
    // Existing session — route to existing transport
    const { transport } = sessions.get(sessionId)!;
    await transport.handleRequest(req, res);
  } else {
    // New session — create server + transport
    const server = new McpServer({ name: 'my-server', version: '1.0.0' });
    const transport = new StreamableHTTPServerTransport({ sessionIdHeader: 'mcp-session-id' });
    res.on('close', () => sessions.delete(transport.sessionId!));
    await server.connect(transport);
    sessions.set(transport.sessionId!, { server, transport });
    await transport.handleRequest(req, res);
  }
});

// GET /mcp — SSE stream for server-to-client notifications
app.get('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string;
  const session = sessions.get(sessionId);
  if (!session) return res.status(404).end();
  await session.transport.handleRequest(req, res);
});

Proxy configuration for SSE

The most common operational issue with MCP servers is a reverse proxy that buffers the SSE response before forwarding it to the client — the client waits for the entire response instead of receiving events as they arrive. Each proxy requires one change:

For Cloudflare's 100-second proxy timeout on SSE streams, send a keep-alive comment event at a cadence shorter than the timeout:

// Keep-alive ping for long-lived SSE streams behind Cloudflare
setInterval(() => {
  for (const [sessionId, { transport }] of sessions) {
    transport.sendPing?.(); // SDK method if available, or write raw SSE comment
  }
}, 90_000); // every 90 seconds — under Cloudflare's 100s limit

These are the same infrastructure requirements as any other SSE-based service (stock tickers, live dashboards). If you have existing SSE infrastructure, your MCP server reuses the same configuration. If this is your first SSE service, the AliveMCP streaming guide has the full configuration table for each proxy.

Using WebSocket backends inside MCP tool handlers

Some services you want to expose as MCP tools use WebSocket APIs — real-time trading feeds, live collaborative editing, game server state. The MCP transport being HTTP+SSE does not prevent you from connecting to these services from inside a tool handler. The WebSocket connection is a detail of the tool's implementation, not the MCP transport:

// Tool handler that connects to a WebSocket backend
import WebSocket from 'ws';
import { z } from 'zod';

server.tool(
  'get_live_price',
  'Get the current live price of a ticker symbol',
  { symbol: z.string().toUpperCase() },
  async ({ symbol }) => {
    return new Promise((resolve) => {
      const ws = new WebSocket('wss://feeds.example.com/prices');

      const timeout = setTimeout(() => {
        ws.close();
        resolve({ isError: true, content: [{ type: 'text', text: 'Price feed timeout' }] });
      }, 5_000);

      ws.on('message', (data) => {
        const msg = JSON.parse(data.toString());
        if (msg.symbol === symbol) {
          clearTimeout(timeout);
          ws.close();
          resolve({ content: [{ type: 'text', text: JSON.stringify(msg) }] });
        }
      });

      ws.on('error', (err) => {
        clearTimeout(timeout);
        resolve({ isError: true, content: [{ type: 'text', text: `WebSocket error: ${err.message}` }] });
      });
    });
  }
);

Two things to note: (1) open and close the WebSocket connection inside the tool handler — do not hold a persistent WebSocket connection at module scope per-tool, as this creates N open connections for N concurrent sessions even when no tool calls are active; (2) always set a timeout and handle the error case as isError: true, not a thrown exception, so the session stays open if the WebSocket backend is down.

Why MCP chose HTTP+SSE over WebSockets

HTTP+SSE has three operational advantages over WebSockets for the MCP use case: (1) standard HTTP request-response semantics mean each tool call has an obvious correlation between request and response, making tracing and logging straightforward; (2) HTTP load balancers distribute POST requests across instances without sticky routing — only the GET SSE stream requires session affinity (usually solved with mcp-session-id header routing), whereas WebSockets require per-connection routing for all messages; (3) HTTP is universally supported by infrastructure tooling — health checks, rate limiters, auth middleware, and observability tools all work on HTTP requests natively. AliveMCP's probe uses standard POST /mcp with a JSON-RPC initialize body — the same request a real client sends — because HTTP makes that trivially implementable without a WebSocket client.

Related questions

Further reading

• MCP server streaming — SSE infrastructure requirements and progress notifications
• MCP server SDK — StreamableHTTP transport internals and session lifecycle
• MCP server error handling — handling WebSocket backend failures as isError results
• MCP server timeout — timeout configuration for tool calls including WebSocket backends
• MCP server health check — how initialize-based probes work without WebSocket
• AliveMCP — HTTP-based MCP server monitoring with initialize + tools/list verification