fix: keep HTTP SSE streams alive

Add stream-owned keep-alive timers to session and per-request HTTP transports, propagate createMcpHandler's existing interval across its HTTP legs, and prevent proxy buffering.

Author: mattzcarey

.changeset/streamable-http-sse-keepalive.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/server': minor
+---
+
+Add configurable SSE keep-alive comment frames to Streamable HTTP transports and apply `createMcpHandler`'s existing `keepAliveMs` option to every HTTP SSE stream it serves.

docs/troubleshooting.md

@@ -154,6 +154,10 @@ 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`
+
+HTTP SSE streams emit a `: keepalive` comment every 15 seconds by default so client body-idle timeouts and intermediaries do not terminate an otherwise idle connection. Configure the interval with `keepAliveMs` on the transport or `createMcpHandler`; set it to `0` to disable heartbeats.
+
 ## Recap
 
 - Every heading on this page is the exact message you searched for.

packages/server/src/server/createMcpHandler.ts

@@ -194,8 +194,8 @@ 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 for every SSE stream this handler
+     * serves. In modern `auto` mode it starts after SSE upgrade. Set to `0` to disable.
      * @default 15000
      */
     keepAliveMs?: number;
@@ -306,7 +306,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 {
+function legacyStatelessFallbackWithKeepAlive(
+    factory: McpServerFactory,
+    onerror?: (error: Error) => void,
+    keepAliveMs?: number
+): LegacyHttpHandler {
     return async (request, options) => {
         if (request.method.toUpperCase() !== 'POST') {
             return jsonRpcErrorResponse(405, -32_000, 'Method not allowed.');
@@ -317,7 +321,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,
+                ...(keepAliveMs !== undefined && { keepAliveMs })
+            });
             await product.connect(transport);
 
             const teardown = () => {
@@ -390,6 +397,10 @@ export function legacyStatelessFallback(factory: McpServerFactory, onerror?: (er
     };
 }
 
+export function legacyStatelessFallback(factory: McpServerFactory, onerror?: (error: Error) => void): LegacyHttpHandler {
+    return legacyStatelessFallbackWithKeepAlive(factory, onerror);
+}
+
 /* ------------------------------------------------------------------------ *
  * The entry's classification step (shared with isLegacyRequest)
  * ------------------------------------------------------------------------ */
@@ -632,7 +643,8 @@ 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 : legacyStatelessFallbackWithKeepAlive(factory, reportError, options.keepAliveMs);
 
     async function serveModern(route: InboundModernRoute, request: Request, authInfo: AuthInfo | undefined): Promise<Response> {
         const claimedRevision = route.classification.revision;
@@ -778,7 +790,8 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
                 classification: route.classification,
                 request,
                 ...(authInfo !== undefined && { authInfo }),
-                ...(responseMode !== undefined && { responseMode })
+                ...(responseMode !== undefined && { responseMode }),
+                ...(options.keepAliveMs !== undefined && { keepAliveMs: options.keepAliveMs })
             });
             if (route.messageKind === 'notification') {
                 // Notification exchanges have no terminal response to ride the

packages/server/src/server/invoke.ts

@@ -35,6 +35,8 @@ export interface InvokeContext {
     authInfo?: AuthInfo;
     /** Response shaping for the exchange; defaults to `auto` (lazy SSE upgrade). */
     responseMode?: PerRequestResponseMode;
+    /** SSE keep-alive interval for the exchange. */
+    keepAliveMs?: number;
 }
 
 /**
@@ -58,7 +60,8 @@ export async function invoke(
 ): Promise<Response> {
     const transport = new PerRequestHTTPServerTransport({
         classification: ctx.classification,
-        ...(ctx.responseMode !== undefined && { responseMode: ctx.responseMode })
+        ...(ctx.responseMode !== undefined && { responseMode: ctx.responseMode }),
+        ...(ctx.keepAliveMs !== undefined && { keepAliveMs: ctx.keepAliveMs })
     });
     await server.connect(transport);
     return transport.handleMessage(message, {

packages/server/src/server/perRequestTransport.ts

@@ -58,6 +58,8 @@ import {
     SdkErrorCode
 } from '@modelcontextprotocol/core-internal';
 
+import { armSseKeepAlive, DEFAULT_SSE_KEEP_ALIVE_MS } from './sseKeepAlive';
+
 /**
  * How the transport shapes its HTTP response for a request:
  *
@@ -79,6 +81,8 @@ export interface PerRequestHTTPServerTransportOptions {
     classification: MessageClassification;
     /** Response shaping for the exchange; defaults to `auto`. */
     responseMode?: PerRequestResponseMode;
+    /** SSE keep-alive interval in milliseconds; defaults to `15000`, `0` disables. */
+    keepAliveMs?: number;
 }
 
 /** Per-exchange context handed to {@linkcode PerRequestHTTPServerTransport.handleMessage}. */
@@ -140,10 +144,13 @@ export class PerRequestHTTPServerTransport implements Transport {
     private _deferredResponse?: DeferredResponse;
     private _sse?: SseSink;
     private _abortCleanup?: () => void;
+    private readonly _keepAliveMs: number;
+    private _keepAliveTimer?: ReturnType<typeof setInterval>;
 
     constructor(options: PerRequestHTTPServerTransportOptions) {
         this._classification = options.classification;
         this._responseMode = options.responseMode ?? 'auto';
+        this._keepAliveMs = options.keepAliveMs ?? DEFAULT_SSE_KEEP_ALIVE_MS;
     }
 
     async start(): Promise<void> {
@@ -342,6 +349,7 @@ export class PerRequestHTTPServerTransport implements Transport {
 
         this._abortCleanup?.();
         this._abortCleanup = undefined;
+        this.stopKeepAlive();
 
         if (this._sse !== undefined && !this._sse.closed) {
             this._sse.closed = true;
@@ -382,13 +390,14 @@ export class PerRequestHTTPServerTransport implements Transport {
             }
         });
         this._sse = { controller, encoder: new TextEncoder(), closed: false };
+        this._keepAliveTimer = armSseKeepAlive(this._keepAliveMs, () => this.writeCommentFrame('keepalive'));
 
         this.settleResponse(
             new Response(readable, {
                 status: 200,
                 headers: {
                     'Content-Type': 'text/event-stream',
-                    'Cache-Control': 'no-cache',
+                    'Cache-Control': 'no-cache, no-transform',
                     Connection: 'keep-alive',
                     // Disable proxy buffering so streamed messages are
                     // delivered as they are written.
@@ -398,7 +407,15 @@ export class PerRequestHTTPServerTransport implements Transport {
         );
     }
 
+    private stopKeepAlive(): void {
+        if (this._keepAliveTimer !== undefined) {
+            clearInterval(this._keepAliveTimer);
+            this._keepAliveTimer = undefined;
+        }
+    }
+
     private finalizeStream(): void {
+        this.stopKeepAlive();
         if (this._sse !== undefined && !this._sse.closed) {
             this._sse.closed = true;
             try {

packages/server/src/server/sseKeepAlive.ts

@@ -0,0 +1,15 @@
+/** Default interval between SSE keep-alive comment frames. */
+export const DEFAULT_SSE_KEEP_ALIVE_MS = 15_000;
+
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+
+/** Arms an unref'd timer, or disables keep-alive for invalid delays. */
+export function armSseKeepAlive(intervalMs: number, onTick: () => void): ReturnType<typeof setInterval> | undefined {
+    if (!Number.isFinite(intervalMs) || intervalMs < 1) {
+        return undefined;
+    }
+
+    const timer = setInterval(onTick, Math.min(intervalMs, MAX_TIMER_DELAY_MS));
+    (timer as { unref?: () => void }).unref?.();
+    return timer;
+}

packages/server/src/server/streamableHttp.ts

@@ -19,6 +19,8 @@ import {
     SUPPORTED_PROTOCOL_VERSIONS
 } from '@modelcontextprotocol/core-internal';
 
+import { armSseKeepAlive, DEFAULT_SSE_KEEP_ALIVE_MS } from './sseKeepAlive';
+
 export type StreamId = string;
 export type EventId = string;
 
@@ -148,6 +150,12 @@ export interface WebStandardStreamableHTTPServerTransportOptions {
      */
     retryInterval?: number;
 
+    /**
+     * Interval in milliseconds between SSE keep-alive comment frames.
+     * Defaults to `15000`; set to `0` to disable.
+     */
+    keepAliveMs?: number;
+
     /**
      * List of protocol versions that this transport will accept.
      * Used to validate the `mcp-protocol-version` header in incoming requests.
@@ -247,6 +255,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
     private _enableDnsRebindingProtection: boolean;
     private _retryInterval?: number;
     private _supportedProtocolVersions: string[];
+    private _keepAliveMs: number;
 
     sessionId?: string;
     onclose?: () => void;
@@ -264,6 +273,23 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
         this._enableDnsRebindingProtection = options.enableDnsRebindingProtection ?? false;
         this._retryInterval = options.retryInterval;
         this._supportedProtocolVersions = options.supportedProtocolVersions ?? SUPPORTED_PROTOCOL_VERSIONS;
+        this._keepAliveMs = options.keepAliveMs ?? DEFAULT_SSE_KEEP_ALIVE_MS;
+    }
+
+    private startKeepAlive(
+        controller: ReadableStreamDefaultController<Uint8Array>,
+        encoder: InstanceType<typeof TextEncoder>
+    ): ReturnType<typeof setInterval> | undefined {
+        if (this._closed) return undefined;
+
+        const timer = armSseKeepAlive(this._keepAliveMs, () => {
+            try {
+                controller.enqueue(encoder.encode(': keepalive\n\n'));
+            } catch {
+                if (timer !== undefined) clearInterval(timer);
+            }
+        });
+        return timer;
     }
 
     /**
@@ -462,13 +488,17 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
 
         const encoder = new TextEncoder();
         let streamController: ReadableStreamDefaultController<Uint8Array>;
+        // Captured by cancel/cleanup before it is assigned after stream setup.
+        // eslint-disable-next-line prefer-const
+        let keepAliveTimer: ReturnType<typeof setInterval> | undefined;
 
         // Create a ReadableStream with a controller we can use to push SSE events
         const readable = new ReadableStream<Uint8Array>({
             start: controller => {
                 streamController = controller;
             },
             cancel: () => {
+                if (keepAliveTimer !== undefined) clearInterval(keepAliveTimer);
                 // Stream was cancelled by client. Only drop the mapping when
                 // it still points at THIS controller — a stale cancel must not
                 // delete a successor stream registered by a later GET/resume.
@@ -481,7 +511,8 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
         const headers: Record<string, string> = {
             'Content-Type': 'text/event-stream',
             'Cache-Control': 'no-cache, no-transform',
-            Connection: 'keep-alive'
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no'
         };
 
         // After initialization, always include the session ID if we have one
@@ -494,6 +525,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             controller: streamController!,
             encoder,
             cleanup: () => {
+                if (keepAliveTimer !== undefined) clearInterval(keepAliveTimer);
                 this._streamMapping.delete(this._standaloneSseStreamId);
                 try {
                     streamController!.close();
@@ -503,6 +535,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             }
         });
 
+        keepAliveTimer = this.startKeepAlive(streamController!, encoder);
         return new Response(readable, { headers });
     }
 
@@ -537,7 +570,8 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             const headers: Record<string, string> = {
                 'Content-Type': 'text/event-stream',
                 'Cache-Control': 'no-cache, no-transform',
-                Connection: 'keep-alive'
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no'
             };
 
             if (this.sessionId !== undefined) {
@@ -547,6 +581,8 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             // Create a ReadableStream with controller for SSE
             const encoder = new TextEncoder();
             let streamController: ReadableStreamDefaultController<Uint8Array>;
+            let keepAliveTimer: ReturnType<typeof setInterval> | undefined;
+            let cancelled = false;
             // Captured by the cancel closure below before it's assigned (after
             // replayEventsAfter resolves) — must be `let`.
             // eslint-disable-next-line prefer-const
@@ -557,6 +593,8 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                     streamController = controller;
                 },
                 cancel: () => {
+                    cancelled = true;
+                    if (keepAliveTimer !== undefined) clearInterval(keepAliveTimer);
                     // Stream was cancelled by client — drop the mapping so a
                     // subsequent reconnect with the same Last-Event-ID is not
                     // refused with 409 by the conflict check above. Only delete
@@ -585,11 +623,22 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                 }
             });
 
+            if (this._closed || cancelled) {
+                try {
+                    streamController!.close();
+                } catch {
+                    // Controller already closed/cancelled.
+                }
+                return this.createJsonErrorResponse(404, -32_001, 'Session not found');
+            }
+
+            this._streamMapping.get(replayedStreamId)?.cleanup();
             this._streamMapping.set(replayedStreamId, {
                 controller: streamController!,
                 encoder,
                 replayedEventIds,
                 cleanup: () => {
+                    if (keepAliveTimer !== undefined) clearInterval(keepAliveTimer);
                     this._streamMapping.delete(replayedStreamId!);
                     try {
                         streamController!.close();
@@ -618,6 +667,9 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                 }
             }
 
+            if (this._streamMapping.get(replayedStreamId)?.controller === streamController!) {
+                keepAliveTimer = this.startKeepAlive(streamController!, encoder);
+            }
             return new Response(readable, { headers });
         } catch (error) {
             this.onerror?.(error as Error);
@@ -818,12 +870,14 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             // SSE streaming mode - use ReadableStream with controller for more reliable data pushing
             const encoder = new TextEncoder();
             let streamController: ReadableStreamDefaultController<Uint8Array>;
+            let keepAliveTimer: ReturnType<typeof setInterval> | undefined;
 
             const readable = new ReadableStream<Uint8Array>({
                 start: controller => {
                     streamController = controller;
                 },
                 cancel: () => {
+                    if (keepAliveTimer !== undefined) clearInterval(keepAliveTimer);
                     // Stream was cancelled by client. Only drop the mapping
                     // when it still points at THIS controller — a stale cancel
                     // (firing after a Last-Event-ID reconnect registered a
@@ -837,8 +891,9 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
 
             const headers: Record<string, string> = {
                 'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                Connection: 'keep-alive'
+                'Cache-Control': 'no-cache, no-transform',
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no'
             };
 
             // After initialization, always include the session ID if we have one
@@ -854,6 +909,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                         controller: streamController!,
                         encoder,
                         cleanup: () => {
+                            if (keepAliveTimer !== undefined) clearInterval(keepAliveTimer);
                             this._streamMapping.delete(streamId);
                             try {
                                 streamController!.close();
@@ -891,6 +947,9 @@ 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
 
+            if (this._streamMapping.get(streamId)?.controller === streamController!) {
+                keepAliveTimer = this.startKeepAlive(streamController!, encoder);
+            }
             return new Response(readable, { status: 200, headers });
         } catch (error) {
             // return JSON-RPC formatted error