fix: align SSE keep-alive delivery safeguards

Reject sub-millisecond intervals that Node clamps to 1ms and disable nginx-style buffering on GET, POST, and replay SSE responses so heartbeat frames reach clients.

Author: mattzcarey

.changeset/keepalive-lifecycle-hardening.md

@@ -2,4 +2,4 @@
 '@modelcontextprotocol/sdk': patch
 ---
 
-Hardens the Streamable HTTP server transport's SSE keep-alive lifecycle: keep-alive timers can no longer be armed after the transport closes or leak when a priming event write fails, and a non-finite `keepAliveMs` disables keep-alive instead of arming a clamped ~1ms interval.
+Hardens the Streamable HTTP server transport's SSE keep-alive lifecycle: timers can no longer be armed after transport close or leak when a priming event write fails, invalid timer delays safely disable keep-alive, and SSE responses disable nginx-style proxy buffering.

src/server/webStandardStreamableHttp.ts

@@ -156,7 +156,8 @@ export interface WebStandardStreamableHTTPServerTransportOptions {
      *
      * Comment frames are ignored by SSE parsers and never surface as messages.
      * Defaults to 15000 (per the WHATWG SSE spec recommendation of roughly every
-     * 15 seconds). Set to 0 to disable keep-alive frames.
+     * 15 seconds). Set to 0 to disable keep-alive frames; values below 1, above
+     * 2147483647, or non-finite values also disable the timer.
      */
     keepAliveMs?: number;
 }
@@ -276,7 +277,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
         // close()) must not outlive the transport: close()'s timer sweep has
         // already run. Invalid timer delays disable keep-alive rather than
         // letting setInterval clamp them to ~1ms and flood every stream.
-        if (!Number.isFinite(this._keepAliveMs) || this._keepAliveMs <= 0 || this._keepAliveMs > 2_147_483_647 || this._closed) {
+        if (!Number.isFinite(this._keepAliveMs) || this._keepAliveMs < 1 || this._keepAliveMs > 2_147_483_647 || this._closed) {
             return;
         }
         this.stopKeepAlive(streamId);
@@ -493,7 +494,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
@@ -552,7 +554,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) {
@@ -839,7 +842,8 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             const headers: Record<string, string> = {
                 'Content-Type': 'text/event-stream',
                 'Cache-Control': 'no-cache',
-                Connection: 'keep-alive'
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no'
             };
 
             // After initialization, always include the session ID if we have one

test/server/streamableHttp.test.ts

@@ -270,6 +270,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
 
             expect(response.status).toBe(200);
             expect(response.headers.get('content-type')).toBe('text/event-stream');
+            expect(response.headers.get('x-accel-buffering')).toBe('no');
             expect(response.headers.get('mcp-session-id')).toBeDefined();
         });
 
@@ -486,6 +487,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
 
             expect(sseResponse.status).toBe(200);
             expect(sseResponse.headers.get('content-type')).toBe('text/event-stream');
+            expect(sseResponse.headers.get('x-accel-buffering')).toBe('no');
 
             // Send a notification (server-initiated message) that should appear on SSE stream
             const notification: JSONRPCMessage = {
@@ -1444,6 +1446,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
             });
 
             expect(reconnectResponse.status).toBe(200);
+            expect(reconnectResponse.headers.get('x-accel-buffering')).toBe('no');
 
             // Read the replayed notification
             const reconnectReader = reconnectResponse.body?.getReader();
@@ -3452,7 +3455,7 @@ describe('WebStandardStreamableHTTPServerTransport SSE keep-alive', () => {
         await transport.close();
     });
 
-    it.each([Number.NaN, Number.POSITIVE_INFINITY, 2_147_483_648])(
+    it.each([0.5, Number.NaN, Number.POSITIVE_INFINITY, 2_147_483_648])(
         'should disable keep-alive for invalid keepAliveMs %s instead of arming a clamped interval',
         async keepAliveMs => {
             const { transport, sessionId } = await createTransport({ keepAliveMs });