Support POST response SSE streams for server-to-client messages

## Motivation and Context

The MCP Streamable HTTP specification defines that servers can return POST responses
as SSE streams and send server-to-client JSON-RPC requests and notifications through them:

> If the input is a JSON-RPC request, the server MUST either return
> `Content-Type: text/event-stream`, to initiate an SSE stream, or
> `Content-Type: application/json`, to return one JSON object.

If the server initiates an SSE stream:

> The server MAY send JSON-RPC requests and notifications before
> sending the JSON-RPC response. These messages SHOULD relate to the
> originating client request.

See: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server

Previously, when a GET SSE stream was connected, the Ruby SDK sent POST response bodies through
the GET stream and returned a 202 HTTP status for the POST itself. When no GET SSE stream was
connected, the SDK correctly returned `application/json` responses. The 202 behavior with GET SSE
was non-compliant with the specification, which requires POST requests to return `text/event-stream`
or `application/json`. Additionally, since GET SSE is optional per the specification, clients that
did not establish a GET SSE connection could not receive server-to-client messages (e.g.,
`sampling/createMessage`, log notifications) during request processing.

With this change, `handle_regular_request` always returns the POST response as an SSE stream for stateful sessions.
Each POST response stream is stored in `session[:post_request_streams]` keyed by `related_request_id` (the JSON-RPC request ID),
enabling correct routing when multiple POST requests are processed concurrently on the same session.
Server-to-client messages with a `related_request_id` are routed to the originating POST response stream only;
when `related_request_id` is nil, the GET SSE stream is used.

The TypeScript and Python SDKs already support this pattern.

### Internal Changes

`JsonRpcHandler.handle` and `JsonRpcHandler.handle_json` now pass both `method_name` and `request_id` to the method finder block.
This allows `Server#handle_request` to receive `related_request_id` directly from the protocol layer.
Without this, `related_request_id` would need to be relayed as a keyword argument through `Server#handle_json`,
`ServerSession#handle_json`, and `dispatch_handle_json`, unnecessarily exposing it on public method signatures.
This follows the same design as the TypeScript and Python SDKs, where the protocol layer extracts the request ID
and propagates it to the handler context.

## How Has This Been Tested?

Added tests for POST response stream:

- `send_request` via POST response stream (sampling with and without GET SSE)
- `send_notification` via POST response stream (logging without GET SSE)
- `progress` notification via POST response stream (without GET SSE)
- POST request returns SSE response even with GET SSE connected
- Session-scoped notifications (log, progress) are sent to POST
  response stream, not GET SSE stream
- `active_stream` does not fall back to GET SSE when
  `related_request_id` is given but request stream is missing

Updated existing tests to handle SSE response format where applicable.

## Breaking Changes (spec compliance fix)

POST responses for JSON-RPC requests in stateful sessions now return `Content-Type: text/event-stream`
instead of being sent through the GET SSE stream with a 202 HTTP status. Clients that relied on receiving responses
via the GET SSE stream will need to read the POST response body instead. This is a spec compliance fix:
the MCP specification requires POST requests to return `text/event-stream` or `application/json`,
not 202 with the response on a separate GET stream.

Author: koic

lib/json_rpc_handler.rb

@@ -92,7 +92,7 @@ def process_request(request, id_validation_pattern:, &method_finder)
     end
 
     begin
-      method = method_finder.call(method_name)
+      method = method_finder.call(method_name, id)
 
       if method.nil?
         return error_response(id: id, id_validation_pattern: id_validation_pattern, error: {

lib/mcp/progress.rb

@@ -2,9 +2,10 @@
 
 module MCP
   class Progress
-    def initialize(notification_target:, progress_token:)
+    def initialize(notification_target:, progress_token:, related_request_id: nil)
       @notification_target = notification_target
       @progress_token = progress_token
+      @related_request_id = related_request_id
     end
 
     def report(progress, total: nil, message: nil)
@@ -16,6 +17,7 @@ def report(progress, total: nil, message: nil)
         progress: progress,
         total: total,
         message: message,
+        related_request_id: @related_request_id,
       )
     end
   end

lib/mcp/server.rb

@@ -127,8 +127,8 @@ def initialize(
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
     # @return [Hash, nil] The JSON-RPC response, or `nil` for notifications.
     def handle(request, session: nil)
-      JsonRpcHandler.handle(request) do |method|
-        handle_request(request, method, session: session)
+      JsonRpcHandler.handle(request) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
@@ -140,8 +140,8 @@ def handle(request, session: nil)
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
     # @return [String, nil] The JSON-RPC response as JSON, or `nil` for notifications.
     def handle_json(request, session: nil)
-      JsonRpcHandler.handle_json(request) do |method|
-        handle_request(request, method, session: session)
+      JsonRpcHandler.handle_json(request) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
@@ -220,7 +220,8 @@ def create_sampling_message(
       stop_sequences: nil,
       metadata: nil,
       tools: nil,
-      tool_choice: nil
+      tool_choice: nil,
+      related_request_id: nil
     )
       unless @transport
         raise "Cannot send sampling request without a transport."
@@ -371,7 +372,7 @@ def schema_contains_ref?(schema)
       end
     end
 
-    def handle_request(request, method, session: nil)
+    def handle_request(request, method, session: nil, related_request_id: nil)
       handler = @handlers[method]
       unless handler
         instrument_call("unsupported_method") do
@@ -399,7 +400,7 @@ def handle_request(request, method, session: nil)
           when Methods::RESOURCES_TEMPLATES_LIST
             { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
           when Methods::TOOLS_CALL
-            call_tool(params, session: session)
+            call_tool(params, session: session, related_request_id: related_request_id)
           when Methods::COMPLETION_COMPLETE
             complete(params)
           when Methods::LOGGING_SET_LEVEL
@@ -499,7 +500,7 @@ def list_tools(request)
       @tools.values.map(&:to_h)
     end
 
-    def call_tool(request, session: nil)
+    def call_tool(request, session: nil, related_request_id: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -531,7 +532,7 @@ def call_tool(request, session: nil)
 
       progress_token = request.dig(:_meta, :progressToken)
 
-      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session)
+      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id)
     rescue RequestHandlerError
       raise
     rescue => e
@@ -611,12 +612,12 @@ def accepts_server_context?(method_object)
       parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil)
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
-        progress = Progress.new(notification_target: session, progress_token: progress_token)
-        server_context = ServerContext.new(context, progress: progress, notification_target: session)
+        progress = Progress.new(notification_target: session, progress_token: progress_token, related_request_id: related_request_id)
+        server_context = ServerContext.new(context, progress: progress, notification_target: session, related_request_id: related_request_id)
         tool.call(**args, server_context: server_context).to_h
       else
         tool.call(**args).to_h