Support JSON response mode for StreamableHTTPTransport

## Motivation and Context

The MCP Streamable HTTP specification allows servers to return POST responses as either
`text/event-stream` (SSE) or `application/json`:

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

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

The TypeScript and Python SDKs support a configurable JSON response mode
via `enableJsonResponse` / `is_json_response_enabled`.

JSON response mode is suitable for simple tool servers that do not need server-initiated requests.
It avoids SSE framing overhead and returns a single JSON object for the POST response.

## Behavior

- POST responses use `Content-Type: application/json` and return a single JSON object.
- The POST `Accept` header requirement is relaxed to `application/json` only
  (matching the Python SDK's lenient behavior).
- Request-scoped notifications (`progress`, `log`) cannot ride along with the single-object response
  and are silently dropped.
- Session-scoped standalone notifications (`resources/updated`, `elicitation/complete`)
  and broadcast notifications (`tools/list_changed`, etc.) continue to flow to clients connected
  to the GET SSE stream.
- All server-to-client requests (`sampling/createMessage`, `roots/list`, `elicitation/create`)
  raise an error in JSON response mode.
- Combines with `stateless: true` for simple single-response servers without session tracking.

## How Has This Been Tested?

Added tests for JSON response mode:

- POST request returns `application/json` response
- Accept header validation requires only `application/json`
- Returns 406 when Accept header is missing
- Accepts wildcard `*/*` in Accept header
- Request-scoped notifications (progress, log) during tool execution are silently dropped
- Request-scoped notifications do not leak to GET SSE even when connected
- Session-scoped standalone notifications are delivered via GET SSE
- Broadcast notifications are delivered via GET SSE
- `send_request` raises for `sampling/createMessage`, `roots/list`, `elicitation/create`
- Combined with `stateless: true`: POST returns JSON without a session ID, GET returns 405

## Breaking Changes

None. JSON response mode is opt-in via `enable_json_response: true`.
The default behavior (SSE responses) is unchanged.

Author: koic

README.md

@@ -1425,6 +1425,23 @@ Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
 ```
 
+You can enable JSON response mode, where the server returns `application/json` instead of `text/event-stream`.
+Set `enable_json_response: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`:
+
+```ruby
+# JSON response mode
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, enable_json_response: true)
+```
+
+In JSON response mode, the POST response is a single JSON object, so server-to-client
+messages that need to arrive during request processing are not supported:
+request-scoped notifications (`progress`, `log`) are silently dropped, and all
+server-to-client requests (`sampling/createMessage`, `roots/list`, `elicitation/create`)
+raise an error. Session-scoped standalone notifications (`resources/updated`,
+`elicitation/complete`) and broadcast notifications (`tools/list_changed`, etc.) still
+flow to clients connected to the GET SSE stream. This mode is suitable for simple tool
+servers that do not need server-initiated requests.
+
 By default, sessions do not expire. To mitigate session hijacking risks, you can set a `session_idle_timeout` (in seconds).
 When configured, sessions that receive no HTTP requests for this duration are automatically expired and cleaned up:
 

lib/mcp/server/transports/streamable_http_transport.rb

@@ -22,13 +22,14 @@ class StreamableHTTPTransport < Transport
           "Connection" => "keep-alive",
         }.freeze
 
-        def initialize(server, stateless: false, session_idle_timeout: nil)
+        def initialize(server, stateless: false, enable_json_response: false, session_idle_timeout: nil)
           super(server)
           # Maps `session_id` to `{ get_sse_stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock }`.
           @sessions = {}
           @mutex = Mutex.new
 
           @stateless = stateless
+          @enable_json_response = enable_json_response
           @session_idle_timeout = session_idle_timeout
           @pending_responses = {}
 
@@ -43,7 +44,8 @@ def initialize(server, stateless: false, session_idle_timeout: nil)
           start_reaper_thread if @session_idle_timeout
         end
 
-        REQUIRED_POST_ACCEPT_TYPES = ["application/json", "text/event-stream"].freeze
+        REQUIRED_POST_ACCEPT_TYPES_SSE = ["application/json", "text/event-stream"].freeze
+        REQUIRED_POST_ACCEPT_TYPES_JSON = ["application/json"].freeze
         REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze
         STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
         SESSION_REAP_INTERVAL = 60
@@ -94,6 +96,12 @@ def send_notification(method, params = nil, session_id: nil, related_request_id:
 
           result = @mutex.synchronize do
             if session_id
+              # JSON response mode returns a single JSON object as the POST response,
+              # so request-scoped notifications (e.g. progress, log) cannot be delivered
+              # alongside it. Session-scoped standalone notifications
+              # (e.g. `resources/updated`, `elicitation/complete`) still flow via GET SSE.
+              next false if @enable_json_response && related_request_id
+
               # Send to specific session
               if (session = @sessions[session_id])
                 stream = active_stream(session, related_request_id: related_request_id)
@@ -172,6 +180,10 @@ def send_request(method, params = nil, session_id: nil, related_request_id: nil)
             raise "Stateless mode does not support server-to-client requests."
           end
 
+          if @enable_json_response
+            raise "JSON response mode does not support server-to-client requests."
+          end
+
           unless session_id
             raise "session_id is required for server-to-client requests."
           end
@@ -278,7 +290,8 @@ def send_ping_to_stream(stream)
         end
 
         def handle_post(request)
-          accept_error = validate_accept_header(request, REQUIRED_POST_ACCEPT_TYPES)
+          required_types = @enable_json_response ? REQUIRED_POST_ACCEPT_TYPES_JSON : REQUIRED_POST_ACCEPT_TYPES_SSE
+          accept_error = validate_accept_header(request, required_types)
           return accept_error if accept_error
 
           content_type_error = validate_content_type(request)
@@ -519,7 +532,7 @@ def handle_regular_request(body_string, session_id, related_request_id: nil)
             end
           end
 
-          if session_id && !@stateless
+          if session_id && !@stateless && !@enable_json_response
             handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: related_request_id)
           else
             response = dispatch_handle_json(body_string, server_session)