fix: address keep-alive lifecycle review findings

- startKeepAlive is a no-op after transport close: a deferred arm (e.g.
  resuming after an event-store replay await that straddled close())
  would otherwise create a timer that close()'s sweep can never clear.
- The POST SSE path arms keep-alive after the fallible awaits (priming
  event write, message dispatch) instead of before them, so an error
  path that discards the Response cannot leak a permanently-firing
  timer against a stream nothing can cancel.
- createMcpHandler's keepAliveMs now also reaches the legacy stateless
  fallback's per-request transport, instead of governing only
  subscriptions/listen streams while the legacy leg silently used the
  transport default.
- Documents the keep-alive behavior and the 'SSE stream disconnected:
  TypeError: terminated' symptom in docs/troubleshooting.md.

Author: mattzcarey

docs/troubleshooting.md

@@ -154,6 +154,14 @@ Rewrite the imports:
 
 The Resource Server helpers did not move there: `requireBearerAuth`, `mcpAuthMetadataRouter` and `OAuthTokenVerifier` are first-class in `@modelcontextprotocol/express` — see [Authorization](./serving/authorization.md). `@modelcontextprotocol/server-legacy` is frozen and receives no new features; serve new code over [Streamable HTTP](./serving/http.md), which still reaches 2025-era clients through [legacy client support](./serving/legacy-clients.md). A client limited to the HTTP+SSE transport is the one case that still needs the frozen `@modelcontextprotocol/server-legacy/sse` import above.
 
+## `SSE stream disconnected: TypeError: terminated`
+
+An idle SSE stream was killed by an intermediary or an idle-connection timeout — Node's `server.requestTimeout` defaults to 300 seconds, and reverse proxies and cloud load balancers have similar watchdogs. The client observes the dropped socket as this error (typically every ~5 minutes) and reconnects in a loop.
+
+`WebStandardStreamableHTTPServerTransport` prevents this by writing an SSE comment frame (`: keepalive`) to every open SSE stream every 15 seconds by default. Comment frames are dropped by SSE parsers before event dispatch, so they never surface as protocol messages. Tune or disable the interval with the transport's `keepAliveMs` option (`0` disables); `createMcpHandler`'s `keepAliveMs` option covers both its `subscriptions/listen` streams and the legacy fallback's per-request transport.
+
+If you still see this error, either keep-alive is disabled (`keepAliveMs: 0`) or an intermediary between client and server buffers or strips SSE data — check for proxies that buffer streaming responses (e.g. nginx without `proxy_buffering off`).
+
 ## Recap
 
 - Every heading on this page is the exact message you searched for.

packages/server/src/server/createMcpHandler.ts

@@ -194,8 +194,9 @@ export interface CreateMcpHandlerOptions {
      */
     maxSubscriptions?: number;
     /**
-     * SSE comment-frame keepalive interval for `subscriptions/listen` streams,
-     * in milliseconds. Set to `0` to disable.
+     * SSE comment-frame keepalive interval, in milliseconds, applied to
+     * `subscriptions/listen` streams and to the SSE streams of the legacy
+     * stateless fallback's per-request transport. Set to `0` to disable.
      * @default 15000
      */
     keepAliveMs?: number;
@@ -306,7 +307,11 @@ function internalServerErrorResponse(id: RequestId | null = null): Response {
  * The entry passes its own `onerror` here when expanding the default, so
  * legacy-leg failures are never silently swallowed.
  */
-export function legacyStatelessFallback(factory: McpServerFactory, onerror?: (error: Error) => void): LegacyHttpHandler {
+export function legacyStatelessFallback(
+    factory: McpServerFactory,
+    onerror?: (error: Error) => void,
+    transportOptions?: { keepAliveMs?: number }
+): LegacyHttpHandler {
     return async (request, options) => {
         if (request.method.toUpperCase() !== 'POST') {
             return jsonRpcErrorResponse(405, -32_000, 'Method not allowed.');
@@ -317,7 +322,10 @@ export function legacyStatelessFallback(factory: McpServerFactory, onerror?: (er
                 ...(options?.authInfo !== undefined && { authInfo: options.authInfo }),
                 requestInfo: request
             });
-            const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            const transport = new WebStandardStreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                ...(transportOptions?.keepAliveMs !== undefined && { keepAliveMs: transportOptions.keepAliveMs })
+            });
             await product.connect(transport);
 
             const teardown = () => {
@@ -632,7 +640,12 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
 
     // The default posture is the stateless fallback; 'reject' is the only way
     // to turn legacy serving off (modern-only strict).
-    const legacyHandler: LegacyHttpHandler | undefined = legacy === 'reject' ? undefined : legacyStatelessFallback(factory, reportError);
+    const legacyHandler: LegacyHttpHandler | undefined =
+        legacy === 'reject'
+            ? undefined
+            : legacyStatelessFallback(factory, reportError, {
+                  ...(options.keepAliveMs !== undefined && { keepAliveMs: options.keepAliveMs })
+              });
 
     async function serveModern(route: InboundModernRoute, request: Request, authInfo: AuthInfo | undefined): Promise<Response> {
         const claimedRevision = route.classification.revision;

packages/server/src/server/streamableHttp.ts

@@ -298,7 +298,9 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
         controller: ReadableStreamDefaultController<Uint8Array>,
         encoder: InstanceType<typeof TextEncoder>
     ): void {
-        if (this._keepAliveMs <= 0) {
+        // A deferred arm (e.g. after an event-store await) must not outlive the
+        // transport: close()'s timer sweep has already run and never runs again.
+        if (this._keepAliveMs <= 0 || this._closed) {
             return;
         }
         this.stopKeepAlive(streamId);
@@ -939,8 +941,6 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                 }
             }
 
-            this.startKeepAlive(streamId, streamController!, encoder);
-
             // Write priming event if event store is configured (after mapping is set up)
             await this.writePrimingEvent(streamController!, encoder, streamId, clientProtocolVersion);
 
@@ -966,6 +966,14 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             // The server SHOULD NOT close the SSE stream before sending all JSON-RPC responses
             // This will be handled by the send() method when responses are ready
 
+            // Arm keep-alive only after the fallible awaits above — an error
+            // path returning 400 discards the Response, so nothing could ever
+            // cancel the stream and clear an already-armed timer. Skip if the
+            // responses already completed and cleaned the stream up.
+            if (this._streamMapping.get(streamId)?.controller === streamController!) {
+                this.startKeepAlive(streamId, streamController!, encoder);
+            }
+
             return new Response(readable, { status: 200, headers });
         } catch (error) {
             // return JSON-RPC formatted error

packages/server/test/server/streamableHttp.test.ts

@@ -1522,3 +1522,93 @@ describe('WebStandardStreamableHTTPServerTransport SSE keep-alive', () => {
         await transport.close();
     });
 });
+
+describe('WebStandardStreamableHTTPServerTransport SSE keep-alive lifecycle', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('should not arm keep-alive when the transport closes during an event-store replay await', async () => {
+        let releaseReplay: (() => void) | undefined;
+        const eventStore: EventStore = {
+            async storeEvent(): Promise<EventId> {
+                return 'evt-1';
+            },
+            async replayEventsAfter(): Promise<StreamId> {
+                await new Promise<void>(resolve => {
+                    releaseReplay = resolve;
+                });
+                return 'stream-1';
+            }
+        };
+        const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), eventStore });
+        await new McpServer({ name: 'test-server', version: '1.0.0' }).connect(transport);
+        const initResponse = await transport.handleRequest(createRequest('POST', TEST_MESSAGES.initialize));
+        const sessionId = initResponse.headers.get('mcp-session-id') as string;
+
+        // Enter replayEvents and park on the replayEventsAfter await
+        const pendingGet = transport.handleRequest(
+            createRequest('GET', undefined, { sessionId, extraHeaders: { 'Last-Event-ID': 'evt-1' } })
+        );
+        await vi.advanceTimersByTimeAsync(0);
+        expect(releaseReplay).toBeDefined();
+
+        // Close the transport mid-await, then let the replay continuation run
+        await transport.close();
+        releaseReplay?.();
+        await pendingGet;
+
+        // The deferred continuation must not have armed a timer close() can never sweep
+        expect(vi.getTimerCount()).toBe(0);
+    });
+
+    it('should not leak a keep-alive timer when the priming event write fails on a POST SSE stream', async () => {
+        // Healthy during initialization, then the store starts failing — the
+        // tool call's priming event write must reject inside handlePostRequest
+        let storeFails = false;
+        const eventStore: EventStore = {
+            async storeEvent(): Promise<EventId> {
+                if (storeFails) {
+                    throw new Error('event store unavailable');
+                }
+                return `evt-${randomUUID()}`;
+            },
+            async replayEventsAfter(): Promise<StreamId> {
+                return 'stream-1';
+            }
+        };
+        const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), eventStore });
+        const mcpServer = new McpServer({ name: 'test-server', version: '1.0.0' });
+        mcpServer.registerTool('noop', { description: 'noop' }, async (): Promise<CallToolResult> => ({ content: [] }));
+        await mcpServer.connect(transport);
+
+        const initResponse = await transport.handleRequest(createRequest('POST', TEST_MESSAGES.initialize));
+        expect(initResponse.status).toBe(200);
+        const sessionId = initResponse.headers.get('mcp-session-id') as string;
+        // Let the init response finish sending (its send() stores an event and
+        // then cleans up the init stream's keep-alive) before failing the store
+        await vi.advanceTimersByTimeAsync(0);
+        expect(vi.getTimerCount()).toBe(0);
+        storeFails = true;
+
+        const response = await transport.handleRequest(
+            createRequest(
+                'POST',
+                { jsonrpc: '2.0', method: 'tools/call', params: { name: 'noop', arguments: {} }, id: 'call-1' } as JSONRPCMessage,
+                {
+                    sessionId
+                }
+            )
+        );
+        expect(response.status).toBe(400);
+
+        // The discarded stream must not carry a permanently-firing timer
+        expect(vi.getTimerCount()).toBe(0);
+
+        await transport.close();
+    });
+});