Repository navigation
Conversation
## Motivation On the 2026-07-28 lifecycle the notifications a handler emits ride the response of its own request. The transport collected them and sent them with the result once the handler had returned, so the progress of a long-running tool reached the client only when the tool was done: it could not reset a client timeout or show anything while the call ran, and past 1,000 notifications the rest were dropped. The TypeScript and Python SDKs write them to the response stream as they are emitted. `stream_request_notifications: true` on `StreamableHTTPTransport` does the same for a request that asks for progress: a `tools/call`, `prompts/get` or `resources/read` carrying `_meta.progressToken` is answered on an SSE stream that stays open until the result, its last event. It is opt-in because it changes how such a request is served: - The handler runs inside the streaming body, on the thread the host writes the response from. No thread or fiber is added for it, so an application keeps its thread-bound state, but the host has to serve streaming bodies. The option raises `ArgumentError` together with `serve_subscriptions_listen: false`. - Opening the stream commits HTTP 200 before the handler runs. The answers the spec ties to another status are ruled out first where they can be told ahead of the handler (an unimplemented method, a missing or malformed envelope, a custom header that disagrees with the body), and those requests keep the buffered exchange. Any other error of a streamed request is the last event of the stream. One of them departs from the spec, which asks HTTP 400 for a missing client capability (`-32021`): only the handler finds that out, so a streamed request carries it on the stream, as the buffered exchange does once a notification was sent. - The headers of a `tools/call` are compared ahead of the stream only on a tool that is known without running the request. With a `tools_list_handler` the tool is the one the block returns for the dispatch itself, so such a server keeps the buffered exchange for `tools/call`, and an unknown tool is answered the same with and without the option. Each write waits for the client within `stream_write_timeout:`, so the notifications of a streamed request are not counted. A write that fails or stalls cancels the request, since closing the response stream is how a client cancels on this lifecycle. Keepalive comment frames are written every `listen_keepalive_interval:` seconds while the handler is quiet, by one thread per streamed request, which also notices a client that went away. Closes modelcontextprotocol#702. ## Tested `test/mcp/server/transports/streamable_http_stream_request_notifications_test.rb` covers the option; without the change the constructor refuses the keyword. ## Breaking Changes None. The option is off by default, and a transport constructed without it serves every request as before.
This branch has not been deployed
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
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.
Motivation
On the 2026-07-28 lifecycle the notifications a handler emits ride the response of its own request. The transport collected them and sent them with the result once the handler had returned, so the progress of a long-running tool reached the client only when the tool was done: it could not reset a client timeout or show anything while the call ran, and past 1,000 notifications the rest were dropped. The TypeScript and Python SDKs write them to the response stream as they are emitted.
stream_request_notifications: trueonStreamableHTTPTransportdoes the same for a request that asks for progress: atools/call,prompts/getorresources/readcarrying_meta.progressTokenis answered on an SSE stream that stays open until the result, its last event. It is opt-in because it changes how such a request is served:ArgumentErrortogether withserve_subscriptions_listen: false.-32021): only the handler finds that out, so a streamed request carries it on the stream, as the buffered exchange does once a notification was sent.tools/callare compared ahead of the stream only on a tool that is known without running the request. With atools_list_handlerthe tool is the one the block returns for the dispatch itself, so such a server keeps the buffered exchange fortools/call, and an unknown tool is answered the same with and without the option.Each write waits for the client within
stream_write_timeout:, so the notifications of a streamed request are not counted. A write that fails or stalls cancels the request, since closing the response stream is how a client cancels on this lifecycle. Keepalive comment frames are written everylisten_keepalive_interval:seconds while the handler is quiet, by one thread per streamed request, which also notices a client that went away.Closes #702.
Tested
test/mcp/server/transports/streamable_http_stream_request_notifications_test.rbcovers the option; without the change the constructor refuses the keyword.Breaking Changes
None. The option is off by default, and a transport constructed without it serves every request as before.
Types of changes
Checklist