feat(server): add keepAliveInterval for standalone GET SSE stream#1726
Open
rcdailey wants to merge 2 commits intomodelcontextprotocol:mainfrom
Open
feat(server): add keepAliveInterval for standalone GET SSE stream#1726rcdailey wants to merge 2 commits intomodelcontextprotocol:mainfrom
rcdailey wants to merge 2 commits intomodelcontextprotocol:mainfrom
Conversation
🦋 Changeset detectedLatest commit: d29e61f The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
Contributor
|
@claude review |
Adds an opt-in keepAliveInterval option to WebStandardStreamableHTTPServerTransportOptions that sends periodic SSE comments (`: keepalive`) on the standalone GET SSE stream. Reverse proxies commonly close connections that are idle for 30-60s. With no server-initiated messages, the GET SSE stream has no traffic during quiet periods, causing silent disconnections. This option lets operators send harmless SSE comments at a configurable cadence to keep the connection alive. The timer is cleared on close(), closeStandaloneSSEStream(), and on stream cancellation. Disabled by default; no behavior change for existing deployments. Addresses upstream modelcontextprotocol#28, modelcontextprotocol#876.
felixweinberger
force-pushed
the
feat/sse-keepalive-interval
branch
from
941226e to
5a925e1
Compare
felixweinberger
requested changes
Mar 31, 2026
Comment on lines
489
to
+499
|
|
||
| // Start keepalive timer to send periodic SSE comments that prevent | ||
| // reverse proxies from closing the connection due to idle timeouts | ||
| if (this._keepAliveInterval !== undefined) { | ||
| this._keepAliveTimer = setInterval(() => { | ||
| try { | ||
| streamController!.enqueue(encoder.encode(': keepalive\n\n')); | ||
| } catch { | ||
| // Controller is closed or errored, stop sending keepalives | ||
| this._clearKeepAliveTimer(); | ||
| } |
Contributor
There was a problem hiding this comment.
When a client reconnects with Last-Event-ID, handleGetRequest returns early via replayEvents() at line 440 and never reaches the keepalive setup here. The replayed stream has no keepalive, so a client that reconnects once gets dropped again at the next idle timeout and ends up in a reconnect loop. I think replayEvents() should also start the timer and clear it in that stream's cancel callback.
Comment on lines
+1033
to
+1046
| it('should clear the keepalive interval when the transport is closed', async () => { | ||
| const sessionId = await setupTransport(50); | ||
|
|
||
| const getReq = createRequest('GET', undefined, { sessionId }); | ||
| const getRes = await transport.handleRequest(getReq); | ||
|
|
||
| expect(getRes.status).toBe(200); | ||
|
|
||
| // Close the transport, which should clear the interval | ||
| await transport.close(); | ||
|
|
||
| // Advancing timers after close should not throw | ||
| vi.advanceTimersByTime(200); | ||
| }); |
Contributor
There was a problem hiding this comment.
This test passes whether or not close() clears the timer. If it doesn't, the next tick's enqueue throws, the try/catch catches it, and the timer self-clears anyway. I think checking vi.getTimerCount() drops to 0 after close() would actually prove the cleanup works.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an opt-in
keepAliveIntervaloption toWebStandardStreamableHTTPServerTransportOptions. When set, the transport sends periodic SSE comments (: keepalive\n\n) on the standalone GET SSE stream to reset proxy idle timers and prevent silent disconnections.SSE comments are ignored by spec-compliant clients but keep the connection alive through reverse proxies (nginx, Envoy, HAProxy, cloud load balancers) that enforce idle timeouts.
Usage
Omitting the option preserves existing behavior (no keepalive, fully backwards compatible).
What changed
keepAliveInterval?: numberadded to the options interface (milliseconds, disabled by default)handleGetRequeststarts asetIntervalthat enqueues: keepalive\n\nto the stream controllerclose(), andcloseStandaloneSSEStream()NodeStreamableHTTPServerTransportwrapper picks this up automatically (it type-aliases and passes through the options)Related issues
Ref #28 (server-side ping automation, P1)
Ref #876 (SSE connections drop after ~5 min idle behind proxies)
This is complementary to protocol-level ping approaches (like PR #1717). SSE comments operate at the transport layer and don't require JSON-RPC round-trips, making them a lightweight way to keep the connection alive independently of protocol-level health checks.