Skip to content

Stream the notifications of a request as they are emitted - #703

Open
koic wants to merge 1 commit into
modelcontextprotocol:mainfrom
koic:stream_the_notifications_of_a_request_as_they_are_emitted
Open

koic wants to merge 1 commit into
modelcontextprotocol:mainfrom
koic:stream_the_notifications_of_a_request_as_they_are_emitted

Conversation

@koic

@koic koic commented Nov 21, 2026

Copy link
Copy Markdown
Member

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 #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.

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

## 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

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Stream modern-request notifications as they are emitted (opt-in)

1 participant