Add SSE polling support (SEP-1699) #1654
Open
+1,047
−47
Conversation
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
Implement server-initiated SSE stream disconnection with client auto-reconnection support to match TypeScript SDK functionality. Server-side changes: - Add retry_interval parameter to StreamableHTTPServerTransport and SessionManager - Add priming event support that sends initial SSE event with ID when event store is configured, enabling resumption capability - Add close_sse_stream() method to close individual SSE streams, triggering client reconnection Client-side changes: - Add StreamableHTTPReconnectionOptions dataclass for configuring reconnection behavior (initial_delay, max_delay, grow_factor, max_retries) - Track priming events (events with IDs) to enable reconnection for POST streams - Capture server-provided retry timing from SSE retry field - Add resume_stream() method for manual reconnection using Last-Event-ID header - Update _handle_sse_event to return priming event info for reconnection decisions Github-Issue:#1699
Add tests for previously uncovered lines in streamable_http client and server to achieve full test coverage: - Client _get_next_reconnection_delay with server retry values - Client resume_stream early returns and error handling - Server _create_priming_event with various configurations - Server close_sse_stream including edge cases Github-Issue:#1654
- Add pragma: no cover to defensive code paths that require complex mocking (server retry field, resume_stream success path, generic exception handlers) - Fix ruff formatting in test file Github-Issue:#1654
- Add type annotations to memory object streams in tests - Import SessionMessage for type annotations - Add pragma: no cover to lines 556 and 571 specifically Github-Issue:#1654
- Remove SEP-1699 header comment from tests - Remove verbose Args docstrings from StreamableHTTPTransport.__init__ and streamablehttp_client - Remove Note comment about _handle_sse_response return value
felixweinberger
force-pushed
the
fweinberger/sep-1699
branch
from
e2b0827 to
174df2a
Compare
When server closes an SSE stream mid-operation via close_sse_stream(), the client now automatically reconnects using the Last-Event-ID header to resume receiving events. Changes: - Add _attempt_sse_reconnection() to client transport for automatic retry - Modify _handle_sse_response() to detect incomplete streams and reconnect - Add close_sse_stream() public API to StreamableHTTPSessionManager - Fix priming event retry type (str -> int) for sse_starlette compatibility - Add SSE polling example client and server
- Add test_streamablehttp_client_auto_reconnection test that exercises the automatic reconnection path when server closes SSE stream mid-operation - Expose session manager reference to test server for close_sse_stream - Add tool_with_server_disconnect tool to test server to trigger SSE polling behavior - Remove pragma exclusions from reconnection code now that it's tested
felixweinberger
force-pushed
the
fweinberger/sep-1699
branch
from
89d038c to
99d1873
Compare
The SSE polling reconnection code paths run in a subprocess during testing, making them difficult to cover with the main test process's coverage instrumentation. Add pragma comments to exclude these from coverage requirements: - Client _attempt_sse_reconnection method and call site - Server StreamableHTTPSessionManager.close_sse_stream method - Test callback branch for empty data handling Github-Issue:#1654
Adds the test_reconnection tool required by the conformance tests to validate SSE polling behavior: - Server closes SSE stream mid-call - Client reconnects with Last-Event-ID - Server replays events from event store Also adds SimpleEventStore implementation for resumability support.
Expose the retry_interval parameter through FastMCP so servers can configure the SSE retry field in priming events. This allows clients to know the recommended reconnection interval. - Add sse_retry_interval to Settings class - Pass through to StreamableHTTPSessionManager - Update everything_server to use 3000ms interval for conformance tests
felixweinberger
commented
Nov 24, 2025
src/mcp/client/streamable_http.py
Outdated
| await ctx.read_stream_writer.send(e) | ||
|
|
||
| # Auto-reconnect if stream ended without completion and we have priming event | ||
| if not is_complete and has_priming_event and last_event_id: |
Contributor
Author
There was a problem hiding this comment.
For the life of me I couldn't get these code paths covered - I'm not sure why, as the example client and server demonstrate this works and the conformance tests pass too:
Will try again in a follow-up but would prefer not to block on this...
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
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
POSTSSE stream as implied by the SEP language linked above. I.e. when a server establishes an SSE stream:close_sse_streamto close the stream while still gathering the events.retryIntervalsupplied by the server before disconnection.How Has This Been Tested?
Example server and client:
Breaking Changes
None. Client falls back to exponential backoff if no retry field is provided.
Types of changes
Checklist