fix: extend SSE keep-alive to the modern per-request leg; address review round 2

- PerRequestHTTPServerTransport gains keepAliveMs (default 15000, 0
  disables): while an exchange's SSE stream is open, an interval drives
  writeCommentFrame so a long-running handler with no mid-call output
  doesn't idle past intermediary/server timeouts — the same failure the
  session transport fix targets, previously unaddressed on the modern
  serving path. Threaded from createMcpHandler through invoke(), so the
  handler's keepAliveMs now uniformly covers listen streams, modern
  per-request exchanges, and the legacy stateless fallback.
- Keep-alive guards use the > 0 polarity (matching listenRouter) so a
  non-finite keepAliveMs disables keep-alive instead of arming a Node-
  clamped ~1ms interval.
- The close-during-replay regression test resumes the standalone GET
  stream so the continuation genuinely reaches the keep-alive arm
  (mutation-verified: removing the _closed guard now fails the test).
- Reworded the two stale legacy-fallback doc blocks that still claimed
  the transport is constructed 'with only sessionIdGenerator: undefined',
  documented legacyStatelessFallback's transportOptions parameter, and
  scoped the troubleshooting entry to match actual coverage.

Author: mattzcarey

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

@@ -2,4 +2,4 @@
 '@modelcontextprotocol/server': patch
 ---
 
-`WebStandardStreamableHTTPServerTransport` now writes SSE keep-alive comment frames (`: keepalive`) to open SSE streams so idle connections (e.g. the standalone GET stream, or a POST stream during a long-running tool call) are not killed by intermediaries or server idle timeouts. Configurable via the new `keepAliveMs` option (default 15000; set 0 to disable).
+SSE streams served by the SDK now emit keep-alive comment frames (`: keepalive`) so idle connections (e.g. the standalone GET stream, or a stream during a long-running tool call) are not killed by intermediaries or server idle timeouts. `WebStandardStreamableHTTPServerTransport` and `PerRequestHTTPServerTransport` gain a `keepAliveMs` option (default 15000; set 0 to disable), and `createMcpHandler`'s existing `keepAliveMs` now covers modern per-request exchange streams and the legacy stateless fallback in addition to `subscriptions/listen` streams.

docs/troubleshooting.md

@@ -158,7 +158,7 @@ The Resource Server helpers did not move there: `requireBearerAuth`, `mcpAuthMet
 
 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.
+The SDK's HTTP serving prevents this by writing an SSE comment frame (`: keepalive`) to every open SSE stream every 15 seconds by default — `WebStandardStreamableHTTPServerTransport` on all of its streams, and `createMcpHandler` on `subscriptions/listen` streams, modern per-request exchange streams, and the legacy fallback's per-request transport. Comment frames are dropped by SSE parsers before event dispatch, so they never surface as protocol messages. Tune or disable the interval with the `keepAliveMs` option on the transport or handler (`0` disables).
 
 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`).
 

packages/server/src/server/createMcpHandler.ts

@@ -145,8 +145,9 @@ export interface CreateMcpHandlerOptions {
      * - `'stateless'` (the default, also when the option is omitted) —
      *   old-school stateless serving: each legacy request is answered by a
      *   fresh instance from the same factory over a streamable HTTP transport
-     *   constructed with only `sessionIdGenerator: undefined` (the established
-     *   stateless idiom). Because serving is per-request and stateless, GET and
+     *   constructed with `sessionIdGenerator: undefined` (the established
+     *   stateless idiom), plus the handler's `keepAliveMs` when provided.
+     *   Because serving is per-request and stateless, GET and
      *   DELETE (2025 session operations) are answered with `405` /
      *   `Method not allowed.`.
      * - `'reject'` — modern-only strict: legacy-classified requests are
@@ -194,9 +195,10 @@ export interface CreateMcpHandlerOptions {
      */
     maxSubscriptions?: number;
     /**
-     * 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.
+     * SSE comment-frame keepalive interval, in milliseconds, applied to every
+     * SSE stream this handler serves: `subscriptions/listen` streams, modern
+     * per-request exchange streams, and the legacy stateless fallback's
+     * per-request transport. Set to `0` to disable.
      * @default 15000
      */
     keepAliveMs?: number;
@@ -296,16 +298,20 @@ function internalServerErrorResponse(id: RequestId | null = null): Response {
  * strict modern endpoint).
  *
  * Each POST is served by a fresh instance from the factory connected to a
- * fresh streamable HTTP transport constructed with only
- * `sessionIdGenerator: undefined` — the established stateless idiom, unchanged.
- * Because serving is per-request and stateless, GET and DELETE (2025 session
- * operations) are answered with `405` / `Method not allowed.`, exactly like the
- * canonical stateless example.
+ * fresh streamable HTTP transport constructed with
+ * `sessionIdGenerator: undefined` (the established stateless idiom) plus any
+ * `transportOptions`. Because serving is per-request and stateless, GET and
+ * DELETE (2025 session operations) are answered with `405` /
+ * `Method not allowed.`, exactly like the canonical stateless example.
  *
  * The optional `onerror` callback receives factory and serving failures on
  * this leg (reporting only — the response stays the 500 internal-error body).
  * The entry passes its own `onerror` here when expanding the default, so
  * legacy-leg failures are never silently swallowed.
+ *
+ * The optional `transportOptions` are threaded into each per-request
+ * transport; currently just `keepAliveMs`, the SSE keep-alive comment-frame
+ * interval (the entry forwards its own `keepAliveMs` option here).
  */
 export function legacyStatelessFallback(
     factory: McpServerFactory,
@@ -791,7 +797,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,12 @@ export interface InvokeContext {
     authInfo?: AuthInfo;
     /** Response shaping for the exchange; defaults to `auto` (lazy SSE upgrade). */
     responseMode?: PerRequestResponseMode;
+    /**
+     * SSE keep-alive comment-frame interval for the exchange's stream, in
+     * milliseconds; passed through to the per-request transport. `0` disables.
+     * @default 15000
+     */
+    keepAliveMs?: number;
 }
 
 /**
@@ -58,7 +64,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

@@ -79,8 +79,19 @@ export interface PerRequestHTTPServerTransportOptions {
     classification: MessageClassification;
     /** Response shaping for the exchange; defaults to `auto`. */
     responseMode?: PerRequestResponseMode;
+    /**
+     * Interval in milliseconds between SSE keep-alive comment frames
+     * (`: keepalive`) written while the exchange's SSE stream is open, so a
+     * long-running handler with no mid-call output doesn't idle past
+     * intermediary and server idle timeouts. Set to `0` to disable.
+     * @default 15000
+     */
+    keepAliveMs?: number;
 }
 
+/** Default interval between SSE keep-alive comment frames. */
+const DEFAULT_KEEP_ALIVE_MS = 15_000;
+
 /** Per-exchange context handed to {@linkcode PerRequestHTTPServerTransport.handleMessage}. */
 export interface PerRequestMessageExtra {
     /**
@@ -140,10 +151,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_KEEP_ALIVE_MS;
     }
 
     async start(): Promise<void> {
@@ -342,6 +356,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,6 +397,7 @@ export class PerRequestHTTPServerTransport implements Transport {
             }
         });
         this._sse = { controller, encoder: new TextEncoder(), closed: false };
+        this.startKeepAlive();
 
         this.settleResponse(
             new Response(readable, {
@@ -398,7 +414,34 @@ export class PerRequestHTTPServerTransport implements Transport {
         );
     }
 
+    /**
+     * Arms the exchange's keep-alive interval, writing an SSE comment frame
+     * every `keepAliveMs` while the stream is open. `writeCommentFrame`
+     * already drops frames once the exchange is closed or the stream is
+     * finalized, so the interval body needs no extra guards; the timer itself
+     * is cleared on stream finalization and transport close.
+     * Uses the `> 0` polarity so a non-finite value disables keep-alive
+     * instead of arming a clamped ~1ms interval.
+     */
+    private startKeepAlive(): void {
+        if (!(this._keepAliveMs > 0) || this._closed) {
+            return;
+        }
+        const timer = setInterval(() => this.writeCommentFrame('keepalive'), this._keepAliveMs);
+        // Don't let the keep-alive timer hold the process open (Node.js only)
+        (timer as { unref?: () => void }).unref?.();
+        this._keepAliveTimer = timer;
+    }
+
+    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/test/server/perRequestStreaming.test.ts

@@ -11,7 +11,7 @@ import {
     PROTOCOL_VERSION_META_KEY,
     setNegotiatedProtocolVersion
 } from '@modelcontextprotocol/core-internal';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { PerRequestResponseMode } from '../../src/server/perRequestTransport';
 import { PerRequestHTTPServerTransport } from '../../src/server/perRequestTransport';
@@ -46,14 +46,16 @@ interface StreamingSetup {
 
 async function setup(
     handler: (ctx: ServerContext) => Promise<CallToolResult>,
-    responseMode?: PerRequestResponseMode
+    responseMode?: PerRequestResponseMode,
+    keepAliveMs?: number
 ): Promise<StreamingSetup> {
     const server = new Server({ name: 'streaming-test', version: '1.0.0' }, { capabilities: { tools: {} } });
     server.setRequestHandler('tools/call', async (_request, ctx) => handler(ctx));
     setNegotiatedProtocolVersion(server, MODERN_REVISION);
     const transport = new PerRequestHTTPServerTransport({
         classification: MODERN,
-        ...(responseMode !== undefined && { responseMode })
+        ...(responseMode !== undefined && { responseMode }),
+        ...(keepAliveMs !== undefined && { keepAliveMs })
     });
     await server.connect(transport);
     return { server, transport };
@@ -249,3 +251,102 @@ describe('disconnect is cancellation', () => {
         expect(observedSignal?.aborted).toBe(true);
     });
 });
+
+describe('keep-alive', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('writes keep-alive comment frames while a forced-sse exchange is streaming', async () => {
+        let release!: () => void;
+        const gate = new Promise<void>(resolve => {
+            release = resolve;
+        });
+        const { transport } = await setup(async () => {
+            await gate;
+            return { content: [] };
+        }, 'sse');
+
+        const responsePromise = transport.handleMessage(toolsCall());
+        // The stream opened at dispatch end; the handler now idles past the
+        // default interval with no mid-call output.
+        await vi.advanceTimersByTimeAsync(15_000);
+        release();
+        const response = await responsePromise;
+        const frames = await sseFrames(response);
+        expect(frames[0]).toBe(': keepalive');
+
+        // The exchange completed and closed the transport: no timer survives.
+        expect(vi.getTimerCount()).toBe(0);
+    });
+
+    it('writes keep-alive frames after an auto exchange upgrades to SSE', async () => {
+        let release!: () => void;
+        const gate = new Promise<void>(resolve => {
+            release = resolve;
+        });
+        const { transport } = await setup(async ctx => {
+            await ctx.mcpReq.notify(progressNotification(1));
+            await gate;
+            return { content: [] };
+        });
+
+        const responsePromise = transport.handleMessage(toolsCall());
+        // Let the handler run, emit the upgrading notification, then idle.
+        await vi.advanceTimersByTimeAsync(15_000);
+        release();
+        const response = await responsePromise;
+        const frames = await sseFrames(response);
+        expect(frames).toContain(': keepalive');
+        expect(vi.getTimerCount()).toBe(0);
+    });
+
+    it('does not write keep-alive frames when keepAliveMs is 0', async () => {
+        let release!: () => void;
+        const gate = new Promise<void>(resolve => {
+            release = resolve;
+        });
+        const { transport } = await setup(
+            async () => {
+                await gate;
+                return { content: [] };
+            },
+            'sse',
+            0
+        );
+
+        const responsePromise = transport.handleMessage(toolsCall());
+        await vi.advanceTimersByTimeAsync(60_000);
+        release();
+        const response = await responsePromise;
+        const frames = await sseFrames(response);
+        expect(frames.some(frame => frame.startsWith(': keepalive'))).toBe(false);
+    });
+
+    it('disables keep-alive for a non-finite keepAliveMs instead of arming a clamped interval', async () => {
+        let release!: () => void;
+        const gate = new Promise<void>(resolve => {
+            release = resolve;
+        });
+        const { transport } = await setup(
+            async () => {
+                await gate;
+                return { content: [] };
+            },
+            'sse',
+            Number.NaN
+        );
+
+        const responsePromise = transport.handleMessage(toolsCall());
+        expect(vi.getTimerCount()).toBe(0);
+        await vi.advanceTimersByTimeAsync(1_000);
+        release();
+        const response = await responsePromise;
+        const frames = await sseFrames(response);
+        expect(frames.some(frame => frame.startsWith(': keepalive'))).toBe(false);
+    });
+});

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

@@ -1542,7 +1542,11 @@ describe('WebStandardStreamableHTTPServerTransport SSE keep-alive lifecycle', ()
                 await new Promise<void>(resolve => {
                     releaseReplay = resolve;
                 });
-                return 'stream-1';
+                // Resume the standalone GET stream: it skips the
+                // no-in-flight-request early close unconditionally, so the
+                // continuation genuinely reaches the keep-alive arm and only
+                // the closed-transport guard keeps the timer count at zero.
+                return '_GET_stream';
             }
         };
         const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), eventStore });