feat: implement SEP-1699 SSE polling via server-side disconnect #1129

felixweinberger · 2025-11-17T14:45:20Z

Summary

Implements SEP-1699 which enables servers to disconnect SSE connections at will by sending priming events and retry fields.

Motivation and Context

SEP-1699 introduces SSE polling behavior that allows servers to control client reconnection timing and close connections gracefully. This enables more efficient resource management on the server side while maintaining resumability.

We implement this on the POST SSE stream as implied by the SEP language linked above. I.e. when a server establishes an SSE stream:

It's first message will be an event including no data, only an event ID.
After that, it may call cancelSSEStream to close the stream while still gathering the events.
The client can start "polling" the SSE stream based on the retryInterval supplied by the server before disconnection.

How Has This Been Tested?

Added e2e integration tests demonstrating the initial priming message, disconnection initiated by the server, and subsequent reconnection via polling by the client.
[currently WIP] upcoming conformance tests in feat: add conformance tests for SEP-1699 SSE polling conformance#35

Breaking Changes

None. Client falls back to exponential backoff if no retry field is provided.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

pkg-pr-new · 2025-11-17T14:46:05Z

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1129

commit: 2516b88

felixweinberger · 2025-11-17T21:16:22Z

src/server/streamableHttp.test.ts

+        toolResolve!();
+    });
+
+    it('should support POST SSE polling with client reconnection', async () => {


probably the most interesting test

felixweinberger · 2025-11-17T21:22:15Z

src/server/streamableHttp.test.ts

+        const primingEventId = primingIdMatch![1];
+
+        // Server closes the stream to trigger polling
+        transport.closeSSEStream(100);


this feels slightly weird. The whole point is for the server to be able to close SSE streams, so maybe this method should be exposed on server?

On the other hand, this disconnection only makes sense in the SHTTP transport - whereas the server is actually transport agnostic.

Maybe the correct expectation is to have the server call this method directly via its reference to the transport if necessary and actually available, so this might be fine actually.`

I think this should be called by the user on the server. A bunch of frameworks dont give the user easy access to the transport but they do the server. Proxy by reference is good

To me it would feel very weird to have a closeSSEStream on the server that should have no knowledge of sessions let alone streams.

A bunch of frameworks dont give the user easy access to the transport but they do the server. Proxy by reference is good

This is a good point but maybe the right API is to expose the transport from the server?

Add support for SSE retry field to enable server-controlled client reconnection timing. Client changes: - Capture server-provided retry field from SSE events - Use retry value for reconnection delay instead of exponential backoff - Reconnect on graceful stream close with Last-Event-ID header Server changes: - Add retryInterval option to StreamableHTTPServerTransportOptions - Send priming events with id/retry/empty-data when eventStore is configured - Add closeSSEStream(requestId) API to close POST SSE streams for polling - Priming events establish resumption capability before actual messages Tests: - Client: retry field capture, exponential backoff fallback, graceful reconnection - Server: priming events, retry field, stream closure, POST SSE polling flow

felixweinberger · 2025-11-18T11:30:12Z

Hi @jonathanhefner would love feedback on whether this accurately captures the intent of your original SEP

@paoloricciuti in case you want to TAL as you had valuable input on modelcontextprotocol/conformance#35

paoloricciuti

So we actually had a brief discussion about this on discord and I think the spec should be clearer here: from the discussion we had the reconnection should be different from the standalone stream. So if the client was doing two POST requests each POST would have it's own lastEventId.

On reconnect this should basically result in 3 new GET SSE streams, two to get the remaining notificiations/responses from the POST requests and one as a standalone stream for the new notifications (and to resume the notifications eventually sent during the disconnection period).

However right now the server still errors out if there's more that one SSE stream. Should this be fixed? Is this even the right interpretation of the spec?

paoloricciuti · 2025-11-18T11:51:10Z

src/server/streamableHttp.test.ts

+        const primingEventId = primingIdMatch![1];
+
+        // Server closes the stream to trigger polling
+        transport.closeSSEStream(100);


To me it would feel very weird to have a closeSSEStream on the server that should have no knowledge of sessions let alone streams.

A bunch of frameworks dont give the user easy access to the transport but they do the server. Proxy by reference is good

This is a good point but maybe the right API is to expose the transport from the server?

src/server/streamableHttp.test.ts

jonathanhefner

would love feedback on whether this accurately captures the intent of your original SEP

Yes, looks great! Thank you! 😃

jonathanhefner · 2025-11-18T21:10:18Z

src/server/streamableHttp.test.ts

+        toolResolve!();
+
+        // Give the tool time to complete and store the result
+        await new Promise(resolve => setTimeout(resolve, 50));


Not sure if this is a concern, but this could lead to flaky tests. I'm not sure what we could await as an alternative though.

Addresses PR feedback from paoloricciuti requesting test coverage for the scenario where multiple messages are sent while the SSE client is disconnected. Uses a batch of tool calls to generate multiple responses that get stored and replayed on reconnection.

felixweinberger · 2025-11-19T00:21:57Z

So we actually had a brief discussion about this on discord and I think the spec should be clearer here: from the discussion we had the reconnection should be different from the standalone stream. So if the client was doing two POST requests each POST would have it's own lastEventId.

On reconnect this should basically result in 3 new GET SSE streams, two to get the remaining notificiations/responses from the POST requests and one as a standalone stream for the new notifications (and to resume the notifications eventually sent during the disconnection period).

However right now the server still errors out if there's more that one SSE stream. Should this be fixed? Is this even the right interpretation of the spec?

Ack, after the discusson on Discord seems clear we need to not error out on multiple streams. Still figuring out the right way to do that on this PR, will come back with an update soon, moving to draft for now.

- Fix replayEvents to use streamId from last-event-id header - Add conflict check per streamId (not global) - Add missing close handler to clean up stream mapping - Add test demonstrating concurrent GET streams resuming different POST streams This aligns with the spec: "The client MAY remain connected to multiple SSE streams simultaneously."

felixweinberger · 2025-11-19T00:56:17Z

Horrible timeout based tests - but looking for feedback on the implementation before figuring out prettier tests.

- Add closeStandaloneSSEStream() method to allow server to close the standalone GET notification stream, triggering client reconnection - Send priming event with retry field on GET streams (when eventStore configured) for resumability - Add tests for GET stream priming events and closeStandaloneSSEStream - Fix flaky test timeout for POST SSE polling test

Keep PR focused on POST stream resumability only: - Remove closeStandaloneSSEStream() method - Remove priming event from GET notification stream - Remove GET stream polling tests - Update resumability tests to not expect GET priming events

The server's replayEvents now requires getStreamIdForEventId to resolve the stream ID from an event ID. Without this, the fallback parsing with '::' separator doesn't match InMemoryEventStore's '_' separator, causing the resumability test to fail.

When getStreamIdForEventId is not implemented, fall back to using the streamId returned by replayEventsAfter() instead of requiring a specific event ID format. This preserves compatibility with existing EventStore implementations that don't implement the new optional method.

The test was incorrectly calling client.request() with resumptionToken expecting a POST response. Per the spec's "Resumability and Redelivery" section, resumption uses GET with Last-Event-ID header: > If the client wishes to resume after a broken connection, it SHOULD > issue an HTTP GET to the MCP endpoint, and include the Last-Event-ID > header to indicate the last event ID it received. See: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#resumability-and-redelivery When resumptionToken is provided, the client's send() method only reconnects the GET SSE stream and returns early - it never sends the POST request. Fix by using transport.send() with a notification (no response expected) to properly trigger GET-based SSE reconnection.

felixweinberger · 2025-11-20T16:13:19Z

src/integration-tests/taskResumability.test.ts

+            // Per spec, resumption uses GET with Last-Event-ID header, not POST
+            // When resumptionToken is provided, send() only triggers GET reconnection and returns early
+            // We use a notification (no id) so we don't expect a response
+            await transport2.send(


fixed this test to use GET for resumption as required by the spec: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#resumability-and-redelivery

cc: @mattzcarey as we chatted about this weirdness between POST & GET

It feels weird to have to send a notification to resume the stream...wouldn't it make sense to have a specific method to resume?

felixweinberger mentioned this pull request Nov 17, 2025

feat: add conformance tests for SEP-1699 SSE polling modelcontextprotocol/conformance#35

Closed

9 tasks

felixweinberger closed this Nov 17, 2025

felixweinberger reopened this Nov 17, 2025

felixweinberger force-pushed the fweinberger/sep-1699 branch 4 times, most recently from ebd4179 to 0b61e98 Compare November 17, 2025 21:02

felixweinberger commented Nov 17, 2025

View reviewed changes

felixweinberger linked an issue Nov 18, 2025 that may be closed by this pull request

Implement SEP-1699: Support SSE Polling via Server-Side Disconnect #1061

Open

felixweinberger force-pushed the fweinberger/sep-1699 branch from a556d78 to 6368bfa Compare November 18, 2025 11:07

felixweinberger force-pushed the fweinberger/sep-1699 branch from 6368bfa to 464b1f8 Compare November 18, 2025 11:16

felixweinberger marked this pull request as ready for review November 18, 2025 11:29

felixweinberger requested a review from a team as a code owner November 18, 2025 11:29

felixweinberger requested a review from jonathanhefner November 18, 2025 11:29

paoloricciuti reviewed Nov 18, 2025

View reviewed changes

jonathanhefner reviewed Nov 18, 2025

View reviewed changes

felixweinberger marked this pull request as draft November 19, 2025 00:22

felixweinberger force-pushed the fweinberger/sep-1699 branch from 151614e to 6d32c15 Compare November 19, 2025 00:53

felixweinberger marked this pull request as ready for review November 19, 2025 00:56

felixweinberger mentioned this pull request Nov 19, 2025

Clarify scope of SEP-1699: SSE Polling modelcontextprotocol/modelcontextprotocol#1847

Closed

felixweinberger added 2 commits November 20, 2025 14:51

chore: remove SEP-1699 references from test comments

78d116f

Merge branch 'main' into fweinberger/sep-1699

8469a85

felixweinberger marked this pull request as draft November 20, 2025 15:15

felixweinberger added 4 commits November 20, 2025 15:29

Remove standalone GET stream polling features

55b9e30

Keep PR focused on POST stream resumability only: - Remove closeStandaloneSSEStream() method - Remove priming event from GET notification stream - Remove GET stream polling tests - Update resumability tests to not expect GET priming events

felixweinberger commented Nov 20, 2025

View reviewed changes

felixweinberger marked this pull request as ready for review November 20, 2025 16:14

felixweinberger requested review from mattzcarey and paoloricciuti November 20, 2025 16:21

felixweinberger mentioned this pull request Nov 20, 2025

Clarify SEP-1699: SSE stream resumption and polling modelcontextprotocol/modelcontextprotocol#1852

Merged

9 tasks

Merge main and resolve conflict in streamableHttp.ts

2516b88

feat: implement SEP-1699 SSE polling via server-side disconnect #1129

Are you sure you want to change the base?

feat: implement SEP-1699 SSE polling via server-side disconnect #1129

Conversation

felixweinberger commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

pkg-pr-new bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

felixweinberger Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paoloricciuti Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

felixweinberger commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paoloricciuti left a comment

Choose a reason for hiding this comment

Uh oh!

paoloricciuti Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Uh oh!

jonathanhefner Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

felixweinberger commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger commented Nov 19, 2025

Uh oh!

felixweinberger Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paoloricciuti Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

felixweinberger commented Nov 17, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 17, 2025 •

edited

Loading

mattzcarey Nov 18, 2025 •

edited

Loading

felixweinberger commented Nov 18, 2025 •

edited

Loading

felixweinberger commented Nov 19, 2025 •

edited

Loading

felixweinberger Nov 20, 2025 •

edited

Loading