How to make an MCP server stateless (2026-07-28 spec)

// http-stateful.ts: the "before". Needs sticky sessions behind a load balancer.
import { randomUUID } from "node:crypto";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
import { buildServer } from "./server-core.js"; // your tools + resources, unchanged

const transports = new Map<string, StreamableHTTPServerTransport>();

async function handleMcp(req, res, body) {
  const sessionId = req.headers["mcp-session-id"] as string | undefined;

  if (sessionId && transports.has(sessionId)) {
    // Only works if this request is routed back to the instance that owns the session.
    await transports.get(sessionId)!.handleRequest(req, res, body);
    return;
  }

  if (!sessionId && isInitializeRequest(body)) {
    const transport: StreamableHTTPServerTransport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),                 // issues Mcp-Session-Id
      onsessioninitialized: (id) => { transports.set(id, transport); }, // in-memory state
    });
    const server = buildServer();
    await server.connect(transport);
    await transport.handleRequest(req, res, body);
    return;
  }

  res.writeHead(400).end(JSON.stringify({
    jsonrpc: "2.0", id: null,
    error: { code: -32000, message: "No valid session ID for a non-initialize request" },
  }));
}

- const transport = new StreamableHTTPServerTransport({
-   sessionIdGenerator: () => randomUUID(),   // issues Mcp-Session-Id, needs a session map
-   onsessioninitialized: (id) => transports.set(id, transport),
- });
+ const transport = new StreamableHTTPServerTransport({
+   sessionIdGenerator: undefined,            // stateless: no session id, no validation
+   enableJsonResponse: true,
+ });

// http-stateless.ts: the "after". Safe to run as N identical replicas.
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { buildServer } from "./server-core.js"; // same tools + resources as before

async function handleMcp(req, res, body) {
  const server = buildServer();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // <- the whole migration
    enableJsonResponse: true,
  });

  // Nothing survives the request. Close both when the client disconnects.
  res.on("close", () => { transport.close(); server.close(); });

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

# STATEFUL: initialize mints a session id you must echo on every later request
$ curl -sD- http://localhost:3000/mcp \
    -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
         "protocolVersion":"2025-06-18","capabilities":{},
         "clientInfo":{"name":"probe","version":"1"}}}'
HTTP/1.1 200 OK
mcp-session-id: 19746205-910f-4396-b456-0aff6818b7c7   # <- every later request must carry this

# tools/list WITHOUT that session id (i.e. routed to another replica) is refused
$ curl -s http://localhost:3000/mcp -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
{"jsonrpc":"2.0","id":null,
 "error":{"code":-32000,"message":"No valid session ID for a non-initialize request"}}

# STATELESS: no session id header at all
$ curl -sD- http://localhost:3000/mcp \
    -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{ ...same as above... }}'
HTTP/1.1 200 OK
content-type: application/json
# (no mcp-session-id line)

# a fresh replica answers tools/list with no prior initialize -> round-robin just works
$ curl -s http://localhost:3000/mcp -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
{"jsonrpc":"2.0","id":2,"result":{"tools":[
  {"name":"query", ...}, {"name":"list_tables", ...}, {"name":"describe_table", ...}]}}

# nginx.lb.conf: plain round-robin. No ip_hash, no sticky cookie, no affinity.
events {}
http {
  upstream mcp_backend {
    server mcp1:3000;
    server mcp2:3000;
  }
  server {
    listen 8080;
    location / {
      proxy_pass http://mcp_backend;
      proxy_http_version 1.1;
      proxy_buffering off;         # Streamable HTTP may stream via SSE
      proxy_read_timeout 3600s;
    }
  }
}

# docker-compose.lb.yml: two identical stateless replicas + one nginx.
#   docker compose -f docker-compose.lb.yml up --build
#   # then point an MCP client at http://localhost:8080/mcp
services:
  mcp1:
    build: .
    environment: { PORT: "3000", DATABASE_URL: "${DATABASE_URL}" }
  mcp2:
    build: .
    environment: { PORT: "3000", DATABASE_URL: "${DATABASE_URL}" }
  lb:
    image: nginx:1.27-alpine
    depends_on: [mcp1, mcp2]
    ports: ["8080:8080"]
    volumes:
      - ./nginx.lb.conf:/etc/nginx/nginx.conf:ro

// http-stateless.test.ts (node:test): the two assertions that prove the migration
test("stateless: no session id is issued, and any request is self-contained", async () => {
  const a = await rpc(url, INIT);
  assert.equal(a.sessionId, null);                 // no Mcp-Session-Id
  const list = await rpc(url, TOOLS_LIST);         // no prior initialize, fresh instance
  assert.deepEqual(list.json.result.tools.map(t => t.name).sort(),
    ["describe_table", "list_tables", "query"]);
});

test("stateful: initialize mints a session id, and calls without it are rejected", async () => {
  const init = await rpc(url, INIT);
  assert.ok(init.sessionId);                        // Mcp-Session-Id present
  const orphaned = await rpc(url, TOOLS_LIST);       // routed to the "wrong" replica
  assert.equal(orphaned.status, 400);
  assert.equal(orphaned.json.error.code, -32000);
});