MCP server Streamable HTTP transport

Why Streamable HTTP replaces the SSE transport

The SSE transport had three deployment friction points: (1) it required two separate HTTP endpoints with coordinated routing; (2) persistent SSE connections break serverless execution models; (3) load balancers needed sticky session configuration so the GET and POST requests for the same session always hit the same server instance. Streamable HTTP addresses all three:

Express + StreamableHTTPServerTransport setup

The stateful version — one transport per client session, appropriate for long-running agents with session-scoped state:

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { randomUUID } from 'node:crypto';

const app = express();
app.use(express.json());

// Active sessions: sessionId → transport
const sessions = new Map<string, StreamableHTTPServerTransport>();

function createMcpServer(): McpServer {
  const server = new McpServer({ name: 'my-server', version: '1.0.0' });
  // Register tools here...
  return server;
}

app.post('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;

  if (sessionId) {
    // Existing session — route to existing transport
    const transport = sessions.get(sessionId);
    if (!transport) {
      res.status(404).json({ error: 'Session not found or expired' });
      return;
    }
    await transport.handleRequest(req, res, req.body);
    return;
  }

  // New session — initialize request with no session header
  const newSessionId = randomUUID();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => newSessionId,
    onsessioninitialized: (id) => {
      sessions.set(id, transport);
    },
  });

  transport.onclose = () => {
    sessions.delete(newSessionId);
  };

  const server = createMcpServer();
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

// Explicit session termination
app.delete('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string;
  const transport = sessions.get(sessionId);
  if (transport) {
    await transport.close();
    sessions.delete(sessionId);
  }
  res.status(200).end();
});

app.listen(3000);

The transport sends the session ID back to the client in the Mcp-Session-Id response header of the initialize response. The client stores this ID and includes it in all subsequent requests.

Stateless mode for serverless deployments

Serverless functions (Lambda, Cloudflare Workers, Vercel Functions) have no persistent memory between requests. Streamable HTTP supports a stateless mode where each POST is fully self-contained — no session state, no transport map, no cleanup. Set sessionIdGenerator: undefined:

// serverless-handler.ts — one McpServer per request, stateless
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

export async function handler(req: Request): Promise<Response> {
  const server = new McpServer({ name: 'my-server', version: '1.0.0' });
  // Register tools...

  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // stateless — no session header assigned
  });

  // handleRequest returns a Response in the serverless adapter
  return transport.handleRequest(req, server);
}

In stateless mode: the server creates a fresh McpServer instance per request; there is no session ID in the response headers; each POST must be self-contained (client sends the full request context every time). This is appropriate for stateless tools (web search, API wrappers, calculations) but not for tools that accumulate state across calls in the same session.

Stateless mode also cannot deliver progress notifications, because there is no persistent channel to push events on — the response body either contains an inline JSON result or an SSE stream that closes with the final response. For stateless tools with long computation times, SSE streaming still works within the single request's response body.

Response modes: inline JSON vs SSE stream

The transport automatically selects the response mode based on what the server sends during request handling:

• Inline JSON — if the tool handler returns a result immediately with no progress notifications, the transport sends Content-Type: application/json with the result as the response body. This is the common case for fast, synchronous tools.
• SSE stream — if the server sends any notifications (progress updates, resource change events) before the final result, the transport switches to Content-Type: text/event-stream and streams events. The client reads the stream until the final result event arrives.

The client must declare it accepts both formats via the Accept header: Accept: application/json, text/event-stream. The transport uses the inline format by default and upgrades to SSE only when needed.

// Tool that triggers SSE streaming via progress notifications
server.tool(
  'process_document',
  'Process a large document with progress updates',
  { url: z.string().url() },
  async ({ url }, { sendNotification }) => {
    await sendNotification({
      method: 'notifications/progress',
      params: { progressToken: 1, progress: 0, total: 100 },
    });

    const result = await processDocument(url, async (pct) => {
      await sendNotification({
        method: 'notifications/progress',
        params: { progressToken: 1, progress: pct, total: 100 },
      });
    });

    return { content: [{ type: 'text', text: result }] };
    // Transport automatically selected SSE mode because of the notifications
  }
);

Session management details

The session lifecycle in stateful mode:

1. Client sends POST /mcp with an initialize request body and no Mcp-Session-Id header.
2. Server creates a new transport and session ID, connects the McpServer, and calls transport.handleRequest().
3. The transport sends the initialized response with Mcp-Session-Id: <id> in the response headers.
4. All subsequent client requests include Mcp-Session-Id: <id>. The server looks up the transport by ID and calls transport.handleRequest().
5. Client sends DELETE /mcp with the session ID header to terminate. Or the transport's onclose fires when a streaming response ends.

Session expiry: unlike SSE (where a dropped connection is immediately visible), stateful Streamable HTTP sessions can be "orphaned" if the client drops without sending DELETE. Add a TTL-based cleanup using a timestamp updated on each request:

const sessionLastSeen = new Map<string, number>();

// Update on each request
sessionLastSeen.set(sessionId, Date.now());

// Evict sessions idle for over 30 minutes
setInterval(() => {
  const cutoff = Date.now() - 30 * 60 * 1000;
  for (const [id, ts] of sessionLastSeen) {
    if (ts < cutoff) {
      const transport = sessions.get(id);
      transport?.close();
      sessions.delete(id);
      sessionLastSeen.delete(id);
    }
  }
}, 60_000);

Load balancer configuration

For stateful Streamable HTTP behind a load balancer, all requests for a session must reach the same server instance — the session state is in-memory. Configure sticky sessions using the Mcp-Session-Id header or a cookie:

For stateless mode, sticky sessions are unnecessary — route freely across instances. This is the main scaling advantage of stateless mode.

If you need stateful sessions without sticky routing (for true horizontal scaling), move session state to an external store: serialize the transport's session context to Redis and restore it on each request. The MCP SDK does not support this natively — you would need to implement serialization at the application layer.

Security setup

Streamable HTTP servers are HTTP APIs — apply the same hardening you would to any REST API:

• Authentication — validate an Authorization: Bearer <token> header before creating a new session. Reject unauthenticated initialize requests with 401. See MCP server authentication and OAuth 2.1 integration.
• Rate limiting — apply rate limiting per IP and per session ID to prevent tool-call flooding.
• Input validation — validate all tool arguments with Zod schemas before processing. The transport delivers raw JSON-RPC bodies — validation is your responsibility.
• CORS — if browser clients connect, set Access-Control-Allow-Origin to specific origins, not *, especially for authenticated servers.
• TLS — serve over HTTPS in production. AliveMCP probes only HTTPS endpoints for HTTP-based transports.

Migrating from SSE transport

If you have an existing SSE transport server, migration to Streamable HTTP is straightforward because the McpServer core doesn't change — only the transport layer:

1. Replace SSEServerTransport imports with StreamableHTTPServerTransport.
2. Replace the dual-endpoint (GET /sse + POST /messages) handlers with a single POST /mcp handler.
3. Update the session map logic to use the Mcp-Session-Id header instead of the session ID query parameter.
4. Add a DELETE /mcp handler for explicit session termination.
5. Run both transports simultaneously during the transition: mount both sets of handlers, let clients negotiate via their Accept headers.

Client libraries updated to MCP SDK 1.1.0+ automatically prefer Streamable HTTP when the server supports it. Older clients fall back to SSE.

AliveMCP monitoring for Streamable HTTP servers

AliveMCP probes Streamable HTTP servers by sending an initialize request to POST /mcp and validating the response. The probe tests both the inline JSON path (no session, stateless-compatible) and the session header path (stateful sessions). Monitored metrics include:

• Initialize handshake latency (p50/p95/p99)
• Session creation success rate
• TLS certificate validity and expiry date
• HTTP response codes (4xx and 5xx trigger alerts)

Once your Streamable HTTP server is deployed, add it to AliveMCP to get 60-second uptime probes, a public status page, and downtime alerts via webhook or Slack.

Related questions

Further reading

• MCP server stdio transport — local process communication guide
• MCP server SSE transport — HTTP+SSE remote server setup
• MCP server transport comparison — stdio vs SSE vs Streamable HTTP
• MCP server JSON-RPC 2.0 — protocol messages and lifecycle
• MCP server authentication — OAuth 2.1 and API key validation
• MCP server streaming — progress notifications in long tool calls
• MCP server load balancing — horizontal scaling patterns
• MCP server Redis — shared state for multi-instance deployments
• AliveMCP — uptime monitoring for Streamable HTTP MCP servers