mcp 1.0.0 → 1.2.0

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../result_type"
 require_relative "../../transport"
 
 # This file is autoloaded only when `StreamableHTTPTransport` is referenced,
@@ -18,10 +19,16 @@ module MCP
       class StreamableHTTPTransport < Transport
         class InvalidJsonError < StandardError; end
 
+        # `x-accel-buffering: no` tells reverse proxies (nginx and friends) not to buffer the response,
+        # which the spec asks of every SSE stream: a buffering proxy holds events back instead of
+        # delivering them as they are written, and on a long-lived `subscriptions/listen` stream that
+        # also swallows the keepalive frames a dropped peer would otherwise be detected by.
+        # The TypeScript and Python SDKs send it on their SSE responses for the same reason.
         SSE_HEADERS = {
           "content-type" => "text/event-stream",
           "cache-control" => "no-cache",
           "connection" => "keep-alive",
+          "x-accel-buffering" => "no",
         }.freeze
 
         # Secure defaults for stateful mode. Without a finite idle timeout, sessions live until an explicit client DELETE,
@@ -35,10 +42,31 @@ module MCP
         DEFAULT_SESSION_IDLE_TIMEOUT = 1800
         DEFAULT_MAX_SESSIONS = 10_000
 
+        # Cap on concurrent `subscriptions/listen` streams (SEP-2575). Each stream holds an open SSE connection
+        # for its lifetime, so without a bound an unauthenticated client can retain unbounded connections,
+        # like the session-flood case `DEFAULT_MAX_SESSIONS` guards. A listen request past the cap is rejected with HTTP 503;
+        # pass `max_listen_subscriptions: nil` to opt out.
+        DEFAULT_MAX_LISTEN_SUBSCRIPTIONS = 1_000
+
         # Distinguishes "argument omitted, apply the secure default" from an explicit `nil` (opt out of expiry).
         UNSET_IDLE_TIMEOUT = Object.new.freeze
         private_constant :UNSET_IDLE_TIMEOUT
 
+        # Default deadline in seconds for a server-to-client request (sampling, elicitation, `roots/list`, `ping`).
+        # The spec asks implementations to bound every sent request so a peer that never answers cannot exhaust
+        # the sender's resources; without one, a client that opens a session and simply never replies parks
+        # a worker thread for good.
+        #
+        # Ten minutes matches the TypeScript SDK, which raises its uniform 60-second request default to 600 seconds
+        # for the legs of its legacy `input_required` shim because they are "human-paced, so the 60s protocol default
+        # is wrong". Every request this transport can send is that kind of leg: someone answering an elicitation
+        # prompt, or the client's own model producing a sample. (The Python SDK leaves the deadline unset and bounds
+        # nothing by default.) Deployments that want a tighter bound pass a smaller value here; a single handler
+        # that legitimately waits longer passes `timeout:`.
+        #
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#timeouts
+        DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT = 600
+
         # Default upper bound on the JSON-RPC request body. `handle_post` reads the whole
         # body into memory and parses it, so without a cap a single unauthenticated POST
         # can allocate gigabytes and OOM the worker. 4 MiB comfortably
@@ -51,6 +79,20 @@ module MCP
         # the stack or amplify parse cost (complements the byte cap).
         MAX_JSON_NESTING = 64
 
+        # Cap on the notifications buffered for one modern request (SEP-2575). The sink holds them
+        # in memory until the handler returns, so a handler that emits notifications in proportion to
+        # client-supplied input would otherwise let one request grow memory without bound.
+        # Notifications past the cap are not delivered and the notify helpers report `false`,
+        # the same non-delivery degradation they have on every other undeliverable path.
+        MAX_MODERN_REQUEST_NOTIFICATIONS = 1_000
+
+        # Interval in seconds between SSE keepalive comment frames on a `subscriptions/listen` stream.
+        # Without them a silently dropped connection holds its slot until the next fan-out write fails,
+        # so on a quiet server a dead peer would occupy a `max_listen_subscriptions` slot indefinitely.
+        # The periodic write detects the dead peer and frees the slot. Matches the TypeScript SDK's
+        # 15-second default; pass `listen_keepalive_interval: nil` when an upstream proxy pings the stream.
+        DEFAULT_LISTEN_KEEPALIVE_INTERVAL = 15
+
         # Creates a Streamable HTTP transport that can be mounted as a Rack app.
         #
         # @param server [MCP::Server] the server whose requests this transport dispatches.
@@ -80,6 +122,16 @@ module MCP
         #   ownership is not enforced.
         # @param max_request_bytes [Integer] upper bound in bytes on a POST request body; larger
         #   requests are rejected with HTTP 413. Defaults to 4 MiB.
+        # @param max_listen_subscriptions [Integer, nil] cap on concurrent `subscriptions/listen`
+        #   streams; a listen request past the cap is rejected with HTTP 503, and `nil` disables
+        #   the cap.
+        # @param listen_keepalive_interval [Numeric, nil] seconds between SSE keepalive comment frames
+        #   on a `subscriptions/listen` stream; the periodic write frees the stream's slot when the peer
+        #   has gone away. Defaults to `DEFAULT_LISTEN_KEEPALIVE_INTERVAL` (15); pass `nil` to disable
+        #   when an upstream proxy already keeps the stream alive.
+        # @param server_to_client_request_timeout [Numeric] seconds a server-to-client request waits for its
+        #   response before the transport stops waiting and raises `MCP::Server::RequestTimeoutError`.
+        #   Defaults to `DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT` (600); individual calls override it with `timeout:`.
         def initialize(
           server,
           stateless: false,
@@ -90,7 +142,10 @@ module MCP
           allowed_hosts: nil,
           dns_rebinding_protection: true,
           session_request_validator: nil,
-          max_request_bytes: DEFAULT_MAX_REQUEST_BYTES
+          max_request_bytes: DEFAULT_MAX_REQUEST_BYTES,
+          max_listen_subscriptions: DEFAULT_MAX_LISTEN_SUBSCRIPTIONS,
+          listen_keepalive_interval: DEFAULT_LISTEN_KEEPALIVE_INTERVAL,
+          server_to_client_request_timeout: DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT
         )
           super(server)
           # Maps `session_id` to `{ get_sse_stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock, origin: origin_header }`.
@@ -107,6 +162,15 @@ module MCP
           @allowed_origins = Array(allowed_origins).map(&:downcase).freeze
           @pending_responses = {}
 
+          # Maps a `subscriptions/listen` request id to `{ stream: stream_object, filter: honored_subscription_filter }` (SEP-2575).
+          # In-process only; a multi-worker deployment needs an external event bus to fan notifications out across processes,
+          # which is a follow-up.
+          @listen_subscriptions = {}
+
+          # Maps a modern request's ephemeral session id to the Array collecting the notifications its handler emits;
+          # `handle_modern` registers the sink and flushes it as SSE frames ahead of the final response (SEP-2575).
+          @modern_request_sinks = {}
+
           # Resolve the idle timeout: an explicit value (including `nil` to opt out) wins; otherwise apply the secure default,
           # which does not apply to stateless mode since it retains no sessions.
           @session_idle_timeout = if session_idle_timeout.equal?(UNSET_IDLE_TIMEOUT)
@@ -136,6 +200,24 @@ module MCP
 
           @max_request_bytes = max_request_bytes
 
+          if !max_listen_subscriptions.nil? && !(max_listen_subscriptions.is_a?(Integer) && max_listen_subscriptions > 0)
+            raise ArgumentError, "max_listen_subscriptions must be a positive Integer or nil"
+          end
+
+          @max_listen_subscriptions = max_listen_subscriptions
+
+          if !listen_keepalive_interval.nil? && !(listen_keepalive_interval.is_a?(Numeric) && listen_keepalive_interval > 0)
+            raise ArgumentError, "listen_keepalive_interval must be a positive number or nil"
+          end
+
+          @listen_keepalive_interval = listen_keepalive_interval
+
+          unless server_to_client_request_timeout.is_a?(Numeric) && server_to_client_request_timeout.positive?
+            raise ArgumentError, "server_to_client_request_timeout must be a positive number"
+          end
+
+          @server_to_client_request_timeout = server_to_client_request_timeout
+
           start_reaper_thread if @session_idle_timeout
         end
 
@@ -149,15 +231,80 @@ module MCP
         # protected out of the box; non-loopback deployments widen the list via `allowed_hosts:`.
         DEFAULT_LOOPBACK_HOSTS = ["127.0.0.1", "::1", "localhost"].freeze
 
+        # JSON-RPC methods whose target name is mirrored into the `Mcp-Name` header (SEP-2575).
+        NAME_BEARING_METHODS = [Methods::TOOLS_CALL, Methods::RESOURCES_READ, Methods::PROMPTS_GET].freeze
+
+        # Maps broadcast notification methods to the `SubscriptionFilter` field that opts in to them on
+        # a `subscriptions/listen` stream (SEP-2575). `notifications/resources/updated` is matched by URI
+        # against `resourceSubscriptions` instead.
+        LISTEN_FILTER_FIELDS = {
+          Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED => :toolsListChanged,
+          Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED => :promptsListChanged,
+          Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED => :resourcesListChanged,
+        }.freeze
+
+        # JSON-RPC error codes that surface as HTTP 400 on the modern path. `-32601` maps to 404
+        # (disambiguating an unknown method from a legacy HTTP+SSE 404) and everything else, including internal errors,
+        # stays 200, matching the Python SDK's status ladder.
+        MODERN_BAD_REQUEST_CODES = [
+          ErrorCodes::HEADER_MISMATCH,
+          ErrorCodes::MISSING_REQUIRED_CLIENT_CAPABILITY,
+          ErrorCodes::UNSUPPORTED_PROTOCOL_VERSION,
+          JsonRpcHandler::ErrorCode::PARSE_ERROR,
+          JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+          JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+        ].freeze
+
         # Rack app interface. This transport can be mounted as a Rack app.
         def call(env)
           handle_request(Rack::Request.new(env))
         end
 
+        # The `subscriptions/listen` notification stream (SEP-2575) is served on the modern path,
+        # so `Server#discover` may advertise `listChanged`/`subscribe` capability flags.
+        def serves_subscriptions_listen?
+          true
+        end
+
         def handle_request(request)
           rebinding_error = validate_dns_rebinding(request)
           return rebinding_error if rebinding_error
 
+          # Header-primary era routing (SEP-2575). An `MCP-Protocol-Version` header naming a version outside
+          # every supported list routes to the sessionless modern path, so an unknown future version receives
+          # the spec-mandated `-32022` with the supported list instead of the legacy path's generic invalid-request error.
+          # Requests without the header, or with a stable-only version, take the existing paths untouched.
+          # An empty header value is malformed rather than a version claim, so it stays on the legacy path
+          # and fails legacy header validation as before.
+          #
+          # A modern header value (2026-07-28) alone cannot decide the era: sessionless modern traffic carries it,
+          # and requests of an established legacy session may stamp it as well (the handshake itself never negotiates it):
+          # an `Mcp-Session-Id` binds the request to an established legacy session (POST requests, the GET SSE stream,
+          # and DELETE termination keep working), and a session-less POST whose body is `initialize` is
+          # the legacy-distinctive handshake. Everything else under a dual-era header is sessionless modern traffic
+          # (`server/discover`, envelope-carrying requests, and envelope-missing requests that get the modern path's error shape).
+          header_version = request.env["HTTP_MCP_PROTOCOL_VERSION"]
+          if header_version && !header_version.empty? && !stable_only_version?(header_version)
+            unless MCP::Configuration.modern_protocol_version?(header_version)
+              return handle_modern(request, header_version)
+            end
+
+            if extract_session_id(request).nil?
+              return handle_modern(request, header_version) unless request.env["REQUEST_METHOD"] == "POST"
+
+              # The body is readable only once (Rack 3 inputs need not be rewindable), so the era sniff reads it here,
+              # bounded, and hands the string to whichever path serves the request.
+              body_string = read_bounded_body(request)
+              return payload_too_large_response if body_string.nil?
+
+              unless legacy_handshake_body?(body_string)
+                return handle_modern(request, header_version, body_string: body_string)
+              end
+
+              return handle_post(request, body_string: body_string)
+            end
+          end
+
           case request.env["REQUEST_METHOD"]
           when "POST"
             handle_post(request)
@@ -174,6 +321,8 @@ module MCP
           @reaper_thread&.kill
           @reaper_thread = nil
 
+          teardown_listen_subscriptions
+
           removed_sessions = @mutex.synchronize do
             @sessions.each_key.filter_map { |session_id| cleanup_session_unsafe(session_id) }
           end
@@ -185,10 +334,11 @@ module MCP
         end
 
         def send_notification(method, params = nil, session_id: nil, related_request_id: nil)
-          # Stateless mode has no streams to deliver notifications on. Report non-delivery instead of raising
-          # so the ephemeral per-request session's notify_* helpers (e.g. progress or log notifications from
-          # a tool handler) degrade gracefully rather than spamming the exception reporter on every call.
-          return false if @stateless
+          # `subscriptions/listen` streams (SEP-2575) receive matching change notifications regardless of the delivery below:
+          # a resource updated by one session's tool call changed globally, so modern subscribers hear about it too.
+          # Runs before the per-request sink and the stateless guard because the listen registry does not depend on sessions,
+          # and a sink capturing the notification for its own response stream must not hide it from other subscriptions.
+          deliver_to_listen_subscriptions(method, params)
 
           notification = {
             jsonrpc: "2.0",
@@ -196,6 +346,24 @@ module MCP
           }
           notification[:params] = params if params
 
+          # A modern request's notifications ride its own response stream (SEP-2575): `handle_modern` registers
+          # a per-request sink for its ephemeral session and flushes it as SSE frames ahead of the final response.
+          # Checked before the stateless guard, since modern requests are served in stateless deployments too.
+          # The sink is bounded; past `MAX_MODERN_REQUEST_NOTIFICATIONS` the notification is dropped as
+          # non-delivery (`false`), never handed to the legacy paths below.
+          sink = @mutex.synchronize { session_id && @modern_request_sinks[session_id] }
+          if sink
+            return false if sink.size >= MAX_MODERN_REQUEST_NOTIFICATIONS
+
+            sink << notification
+            return true
+          end
+
+          # Stateless mode has no streams to deliver notifications on. Report non-delivery instead of raising
+          # so the ephemeral per-request session's notify_* helpers (e.g. progress or log notifications from
+          # a tool handler) degrade gracefully rather than spamming the exception reporter on every call.
+          return false if @stateless
+
           if session_id
             deliver_targeted_notification(notification, session_id, related_request_id)
           else
@@ -299,14 +467,28 @@ module MCP
           end
         end
 
-        # Sends a server-to-client JSON-RPC request (e.g., `sampling/createMessage`) and
-        # blocks until the client responds.
+        # Sends a server-to-client JSON-RPC request (e.g., `sampling/createMessage`) and blocks until
+        # the client responds.
+        #
+        # Uses a `PendingResponse` for cross-thread synchronization: this method registers one,
+        # sends the request via SSE stream, then waits on it. When the client POSTs a response,
+        # `handle_response` matches it by `request_id` and resolves the pending response,
+        # unblocking this thread. A cancellation and session teardown resolve it the same way.
         #
-        # Uses a `Queue` for cross-thread synchronization. This method creates a `Queue`,
-        # sends the request via SSE stream, then blocks on `queue.pop`.
-        # When the client POSTs a response, `handle_response` matches it by `request_id`
-        # and pushes the result onto the queue, unblocking this thread.
-        def send_request(method, params = nil, session_id: nil, related_request_id: nil, parent_cancellation: nil, server_session: nil)
+        # The wait is bounded by `timeout` (defaulting to the transport's `server_to_client_request_timeout`),
+        # so a client that never answers cannot park the calling thread for good. On expiry the peer is
+        # sent `notifications/cancelled` and `MCP::Server::RequestTimeoutError` is raised.
+        def send_request(method, params = nil, session_id: nil, related_request_id: nil, parent_cancellation: nil, server_session: nil, timeout: nil)
+          # The modern lifecycle (SEP-2575) forbids server-initiated JSON-RPC requests;
+          # multi round-trip `input_required` results (SEP-2322) replace them. A modern session has never reached
+          # the rest of this method anyway, since `handle_modern` mints its session without registering it in `@sessions`,
+          # but that is incidental: without the rule stated here a modern handler that reaches for elicitation
+          # or sampling is told "Session not found: <uuid>", which points at everything except the actual reason.
+          # `StdioTransport#send_request` refuses the same way.
+          if server_session&.era == :modern
+            raise "Server-initiated requests are not available in the modern lifecycle (SEP-2575)."
+          end
+
           if @stateless
             raise "Stateless mode does not support server-to-client requests."
           end
@@ -320,7 +502,8 @@ module MCP
           end
 
           request_id = generate_request_id
-          queue = Queue.new
+          pending_response = PendingResponse.new
+          wait_timeout = timeout || @server_to_client_request_timeout
           cancel_hook = nil
 
           request = { jsonrpc: "2.0", id: request_id, method: method }
@@ -333,7 +516,7 @@ module MCP
               raise "Session not found: #{session_id}."
             end
 
-            @pending_responses[request_id] = { queue: queue, session_id: session_id }
+            @pending_responses[request_id] = { queue: pending_response, session_id: session_id }
 
             active_stream(session, related_request_id: related_request_id)
           end
@@ -369,7 +552,27 @@ module MCP
             end
           end
 
-          response = queue.pop
+          response = pending_response.pop(timeout: wait_timeout) do
+            # Expiry cancels as well as stops waiting, so a client that answers late does not act on
+            # a request the server has abandoned. Only connections speaking 2025-11-25 or earlier get here:
+            # the modern lifecycle forbids server-to-client requests outright, and its sessionless requests
+            # never register the session this method looks up. Those revisions ask the sender to "issue
+            # a cancellation notification for that request and stop waiting", letting either side send one.
+            # (The 2026-07-28 rule reserving `notifications/cancelled` for `subscriptions/listen` teardown
+            # governs the era that has no such requests to cancel.) Both reference SDKs send this same
+            # courtesy cancel on timeout.
+            server_session&.send_peer_cancellation(
+              nested_request_id: request_id,
+              related_request_id: related_request_id,
+              reason: "Timed out after #{wait_timeout} seconds",
+            )
+
+            raise RequestTimeoutError.new(
+              "#{method} request timed out after #{wait_timeout} seconds",
+              request_id: request_id,
+              timeout: wait_timeout,
+            )
+          end
 
           if response.is_a?(Hash) && response.key?(:error)
             raise StandardError, "Client returned an error for #{method} request (code: #{response[:error][:code]}): #{response[:error][:message]}"
@@ -457,7 +660,446 @@ module MCP
           stream.flush
         end
 
-        def handle_post(request)
+        # Serves one request of the stateless modern lifecycle (MCP 2026-07-28, SEP-2575):
+        # a single POST/JSON exchange with no session. The modern path never consults
+        # `@stateless`, `@sessions`, or `@enable_json_response`, and never issues or accepts
+        # an `Mcp-Session-Id`. GET (the legacy listening stream, replaced by `subscriptions/listen`)
+        # and DELETE (session termination) have no modern meaning.
+        def handle_modern(request, header_version, body_string: nil)
+          return method_not_allowed_response unless request.env["REQUEST_METHOD"] == "POST"
+
+          accept_error = validate_accept_header(request, REQUIRED_POST_ACCEPT_TYPES_SSE)
+          return accept_error if accept_error
+
+          content_type_error = validate_content_type(request)
+          return content_type_error if content_type_error
+
+          if body_string.nil?
+            body_string = read_bounded_body(request)
+            return payload_too_large_response if body_string.nil?
+          end
+
+          begin
+            body = parse_request_body(body_string)
+          rescue InvalidJsonError
+            return invalid_json_response
+          end
+
+          unless body.is_a?(Hash)
+            return invalid_request_response("Invalid Request: JSON-RPC body must be a single request object")
+          end
+
+          # The version check precedes everything else that depends on request content,
+          # so a client probing with an unknown future version always receives the `-32022` signal
+          # (with the supported list to select from) rather than an incidental error.
+          unless MCP::Configuration.modern_protocol_version?(header_version)
+            return json_rpc_error_response(
+              status: 400,
+              code: ErrorCodes::UNSUPPORTED_PROTOCOL_VERSION,
+              message: "Unsupported protocol version",
+              data: {
+                supported: MCP::Configuration::SUPPORTED_MODERN_PROTOCOL_VERSIONS,
+                requested: header_version,
+              },
+              id: body[:id],
+            )
+          end
+
+          if extract_session_id(request)
+            return json_rpc_error_response(
+              status: 400,
+              code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+              message: "Bad Request: Mcp-Session-Id is not accepted in the modern lifecycle",
+              id: body[:id],
+            )
+          end
+
+          mismatch_error = validate_modern_headers(request, body, header_version)
+          return mismatch_error if mismatch_error
+
+          # `subscriptions/listen` is a long-lived notification stream served at the transport layer;
+          # it never dispatches through `Server#handle`.
+          return handle_subscriptions_listen(body) if body[:method] == Methods::SUBSCRIPTIONS_LISTEN
+
+          session = modern_session
+          notifications = @mutex.synchronize { @modern_request_sinks[session.session_id] = [] }
+          begin
+            response = @server.handle(body, session: session)
+          ensure
+            @mutex.synchronize { @modern_request_sinks.delete(session.session_id) }
+          end
+
+          # `nil` covers notifications and cancellation-suppressed responses; ack with 202 like the legacy notification path.
+          return handle_accepted if response.nil?
+
+          # Notifications a handler emitted during the request ride the request's own response stream as SSE frames ahead of
+          # the final response (SEP-2575); a request that emitted none keeps the single JSON exchange and its HTTP status ladder.
+          # Delivery is buffered: frames flush after the handler returns, preserving order but not real-time interleaving
+          # (the TypeScript and Python SDKs stream live), and the sink grows with the handler's notification count.
+          # Live streaming can follow without changing the wire shape.
+          if notifications.empty?
+            [modern_http_status(response), { "content-type" => "application/json" }, [response.to_json]]
+          else
+            frames = notifications + [response]
+            sse_body = frames.map { |frame| "event: message\ndata: #{frame.to_json}\n\n" }.join
+            [200, SSE_HEADERS.dup, [sse_body]]
+          end
+        rescue StandardError => e
+          MCP.configuration.exception_reporter.call(e, { request: body_string })
+          json_rpc_error_response(
+            status: 500,
+            code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            message: "Internal server error",
+          )
+        end
+
+        # Enforces the SEP-2575 header/body match rules (`-32020`, HTTP 400): the `MCP-Protocol-Version` header
+        # MUST match the `_meta`-carried version, and the `Mcp-Method` / `Mcp-Name` mirror headers MUST match
+        # the body when sent. Absent mirror headers are tolerated for interoperability while other SDK serving stacks
+        # converge on enforcement.
+        def validate_modern_headers(request, body, header_version)
+          params = body[:params]
+          meta_version = params.is_a?(Hash) ? params.dig(:_meta, :"io.modelcontextprotocol/protocolVersion") : nil
+          if meta_version && meta_version != header_version
+            return header_mismatch_response(
+              "MCP-Protocol-Version header value '#{header_version}' does not match body value '#{meta_version}'",
+              body[:id],
+            )
+          end
+
+          # `Mcp-Method` is required on every modern POST and `Mcp-Name` on the name-bearing methods:
+          # the spec lists a missing required standard header among the validation failures that MUST be rejected,
+          # and the TypeScript SDK enforces presence the same way. Absence cannot be treated as "nothing to compare":
+          # the headers exist so intermediaries can route without parsing bodies, and a client that omits them
+          # defeats that contract silently.
+          method_header = request.env["HTTP_MCP_METHOD"]
+          if method_header.to_s.empty?
+            return header_mismatch_response(
+              "Mcp-Method header is required on the modern path",
+              body[:id],
+            )
+          end
+          if method_header != body[:method]
+            return header_mismatch_response(
+              "Mcp-Method header value '#{method_header}' does not match body value '#{body[:method]}'",
+              body[:id],
+            )
+          end
+
+          if NAME_BEARING_METHODS.include?(body[:method])
+            body_name = params.is_a?(Hash) ? params[:name] || params[:uri] : nil
+            name_header = request.env["HTTP_MCP_NAME"]
+            if body_name
+              if name_header.to_s.empty?
+                return header_mismatch_response(
+                  "Mcp-Name header is required for `#{body[:method]}`",
+                  body[:id],
+                )
+              end
+
+              decoded_name = decode_header_value(name_header)
+              if decoded_name != body_name
+                return header_mismatch_response(
+                  "Mcp-Name header value '#{decoded_name}' does not match body value '#{body_name}'",
+                  body[:id],
+                )
+              end
+            end
+          end
+
+          nil
+        end
+
+        # Serves `subscriptions/listen` (SEP-2575): opens a long-lived SSE stream whose first message is
+        # `notifications/subscriptions/acknowledged` with the subset of requested notification types
+        # the server agreed to honor. Notifications delivered on the stream carry `io.modelcontextprotocol/subscriptionId`
+        # (= the listen request id) in `_meta`. A graceful teardown (transport `close`) sends a `SubscriptionsListenResult`
+        # response; an abrupt disconnect sends nothing. A keepalive comment frame is written every
+        # `listen_keepalive_interval` seconds so a dropped connection frees its slot.
+        def handle_subscriptions_listen(body)
+          request_id = body[:id]
+          params = body[:params]
+
+          # A listen frame without an id could never receive stream teardown correlation.
+          unless request_id
+            return invalid_request_response("Invalid Request: subscriptions/listen requires an id")
+          end
+
+          begin
+            if RequestEnvelope.modern?(params)
+              RequestEnvelope.parse!(params, request: params)
+            else
+              return invalid_request_response("Invalid Request: modern requests require the SEP-2575 `_meta` envelope")
+            end
+          rescue Server::RequestHandlerError => e
+            return json_rpc_error_response(
+              status: 400,
+              code: e.error_code || JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+              message: e.message,
+              data: e.error_data,
+              id: request_id,
+            )
+          end
+
+          filter = params[:notifications]
+          unless filter.is_a?(Hash)
+            return json_rpc_error_response(
+              status: 400,
+              code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+              message: "Invalid params: subscriptions/listen requires a `notifications` filter object",
+              id: request_id,
+            )
+          end
+
+          # Best-effort cap check before committing to the SSE response; the registration inside
+          # `listen_sse_body` re-checks atomically for the race between two concurrent listens
+          # crossing the cap together.
+          if listen_subscriptions_full?
+            return too_many_listen_subscriptions_response(request_id)
+          end
+
+          [200, SSE_HEADERS.dup, listen_sse_body(request_id, honored_filter(filter))]
+        end
+
+        def listen_subscriptions_full?
+          return false unless @max_listen_subscriptions
+
+          @mutex.synchronize { @listen_subscriptions.size >= @max_listen_subscriptions }
+        end
+
+        def too_many_listen_subscriptions_response(request_id)
+          json_rpc_error_response(
+            status: 503,
+            code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            message: "Service unavailable: maximum concurrent subscriptions/listen streams (#{@max_listen_subscriptions}) reached",
+            id: request_id,
+          )
+        end
+
+        # The proc registers the stream and returns, leaving the response open like
+        # the legacy GET stream (`create_sse_body`).
+        def listen_sse_body(request_id, honored)
+          proc do |stream|
+            rejected = false
+            @mutex.synchronize do
+              if @listen_subscriptions.key?(request_id) ||
+                  (@max_listen_subscriptions && @listen_subscriptions.size >= @max_listen_subscriptions)
+                rejected = true
+              else
+                @listen_subscriptions[request_id] = { stream: stream, filter: honored }
+              end
+            end
+
+            if rejected
+              close_stream_safely(stream)
+            else
+              acknowledgement = {
+                jsonrpc: "2.0",
+                method: Methods::NOTIFICATIONS_SUBSCRIPTIONS_ACKNOWLEDGED,
+                params: {
+                  notifications: honored,
+                  _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id },
+                },
+              }
+
+              begin
+                send_to_stream(stream, acknowledgement)
+                start_listen_keepalive_thread(request_id)
+              rescue *STREAM_WRITE_ERRORS
+                remove_listen_subscription(request_id)
+                close_stream_safely(stream)
+              end
+            end
+          end
+        end
+
+        # Periodically writes an SSE keepalive comment frame to a listen stream so a silently dropped
+        # connection is detected and its slot freed, rather than held until the next fan-out write.
+        # Mirrors the legacy GET stream's `start_keepalive_thread`; a comment frame (not a data frame)
+        # cannot corrupt an interleaved notification's JSON.
+        def start_listen_keepalive_thread(request_id)
+          return unless @listen_keepalive_interval
+
+          Thread.new do
+            while listen_subscription_active?(request_id)
+              sleep(@listen_keepalive_interval)
+              send_listen_keepalive_ping(request_id)
+            end
+          rescue *STREAM_WRITE_ERRORS
+            # The peer went away; the ensure frees the slot. A dropped listen stream is the normal
+            # way this loop ends, so it is not reported.
+          rescue StandardError => e
+            MCP.configuration.exception_reporter.call(e, { subscription_id: request_id })
+          ensure
+            stream = @mutex.synchronize do
+              subscription = @listen_subscriptions.delete(request_id)
+              subscription && subscription[:stream]
+            end
+            close_stream_safely(stream) if stream
+          end
+        end
+
+        def listen_subscription_active?(request_id)
+          @mutex.synchronize { @listen_subscriptions.key?(request_id) }
+        end
+
+        # Resolves the stream under the lock, then writes outside it so a stalled reader cannot block
+        # every other subscription on `@mutex`. A write error propagates to end the keepalive loop.
+        def send_listen_keepalive_ping(request_id)
+          stream = @mutex.synchronize do
+            subscription = @listen_subscriptions[request_id]
+            subscription && subscription[:stream]
+          end
+          return unless stream
+
+          send_ping_to_stream(stream)
+        end
+
+        # Per SEP-2575, the server MUST NOT send notification types the client has not requested,
+        # and the acknowledgement only includes types the server actually supports
+        # (derived from its declared capabilities).
+        def honored_filter(filter)
+          capabilities = @server.capabilities
+          honored = {}
+          honored[:toolsListChanged] = true if filter[:toolsListChanged] && capability_flag?(capabilities, :tools, :listChanged)
+          honored[:promptsListChanged] = true if filter[:promptsListChanged] && capability_flag?(capabilities, :prompts, :listChanged)
+          honored[:resourcesListChanged] = true if filter[:resourcesListChanged] && capability_flag?(capabilities, :resources, :listChanged)
+
+          subscriptions = filter[:resourceSubscriptions]
+          if capability_flag?(capabilities, :resources, :subscribe) && subscriptions.is_a?(Array) && !subscriptions.empty?
+            honored[:resourceSubscriptions] = subscriptions
+          end
+
+          honored
+        end
+
+        # Reads a nested capability flag tolerating both symbol and string keys, since user-supplied capability hashes arrive
+        # in either form. The flag that promises delivery (`listChanged` / `subscribe`) decides honoring, the same derivation
+        # `Server#discover` uses for its era-aware capability stripping; the mere presence of the primitive's capability is not enough.
+        def capability_flag?(capabilities, name, flag)
+          value = capabilities[name] || capabilities[name.to_s]
+          return false unless value.is_a?(Hash)
+
+          !!(value[flag] || value[flag.to_s])
+        end
+
+        # Fans a notification out to every `subscriptions/listen` stream whose honored filter opted in to it,
+        # stamping the correlating `subscriptionId` into `_meta`. Matching against the honored filter
+        # (not the requested one) enforces the MUST NOT-send-unrequested-types rule.
+        def deliver_to_listen_subscriptions(method, params)
+          field = LISTEN_FILTER_FIELDS[method]
+          return if field.nil? && method != Methods::NOTIFICATIONS_RESOURCES_UPDATED
+
+          # The matching snapshot is taken under `@mutex`, but stream writes happen outside it:
+          # a slow or stalled subscriber must not block the transport, matching the legacy delivery paths.
+          matched = @mutex.synchronize do
+            @listen_subscriptions.filter_map do |request_id, subscription|
+              hit = if field
+                subscription[:filter][field]
+              else
+                uris = subscription[:filter][:resourceSubscriptions]
+                uri = params.is_a?(Hash) ? params[:uri] || params["uri"] : nil
+                uris.is_a?(Array) && uris.include?(uri)
+              end
+
+              [request_id, subscription[:stream]] if hit
+            end
+          end
+
+          matched.each do |request_id, stream|
+            meta = { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id }
+            notification_params = (params || {}).merge(_meta: meta)
+            notification = { jsonrpc: "2.0", method: method, params: notification_params }
+
+            begin
+              send_to_stream(stream, notification)
+            rescue *STREAM_WRITE_ERRORS => e
+              MCP.configuration.exception_reporter.call(
+                e,
+                { subscription_id: request_id, error: "Failed to send notification" },
+              )
+              remove_listen_subscription(request_id)
+              close_stream_safely(stream)
+            end
+          end
+        end
+
+        def remove_listen_subscription(request_id)
+          @mutex.synchronize { @listen_subscriptions.delete(request_id) }
+        end
+
+        # Graceful teardown (SEP-2575): each open listen stream receives its `SubscriptionsListenResult` response
+        # before the stream closes.
+        def teardown_listen_subscriptions
+          removed = @mutex.synchronize do
+            subscriptions = @listen_subscriptions.dup
+            @listen_subscriptions.clear
+            subscriptions
+          end
+
+          removed.each do |request_id, subscription|
+            begin
+              send_to_stream(subscription[:stream], {
+                jsonrpc: "2.0",
+                id: request_id,
+                result: {
+                  # `SubscriptionsListenResult` is served at the transport layer and never
+                  # passes through the dispatch path, so the REQUIRED 2026-07-28 `resultType` is
+                  # stamped at its construction site.
+                  resultType: ResultType::COMPLETE,
+                  _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id },
+                },
+              })
+            rescue *STREAM_WRITE_ERRORS
+              nil
+            end
+            close_stream_safely(subscription[:stream])
+          end
+        end
+
+        def header_mismatch_response(message, id)
+          json_rpc_error_response(
+            status: 400,
+            code: ErrorCodes::HEADER_MISMATCH,
+            message: "Header mismatch: #{message}",
+            id: id,
+          )
+        end
+
+        # Mirrors `MCP::Client::HTTP#encode_header_value`: a value wrapped as `=?base64?<base64>?=` decodes to
+        # its original UTF-8 string; anything else is taken verbatim. Duplicated here because the client transport
+        # requires faraday, which servers do not depend on.
+        def decode_header_value(value)
+          match = value.match(/\A=\?base64\?(.*)\?=\z/m)
+          return value unless match
+
+          match[1].unpack1("m0").force_encoding(Encoding::UTF_8)
+        rescue ArgumentError
+          value
+        end
+
+        # Each modern request is self-contained: handlers run against an ephemeral per-request `ServerSession` locked to
+        # the modern era. The session carries a fresh unregistered `session_id` so notification and server-initiated-request plumbing
+        # keyed by session lookup degrades gracefully (delivery returns `false`) instead of broadcasting to unrelated legacy sessions
+        # via the `session_id.nil?` branch.
+        def modern_session
+          ServerSession.new(server: @server, transport: self, session_id: SecureRandom.uuid, era: :modern)
+        end
+
+        def modern_http_status(response)
+          error_code = response.is_a?(Hash) ? response.dig(:error, :code) : nil
+          if error_code.nil?
+            200
+          elsif error_code == JsonRpcHandler::ErrorCode::METHOD_NOT_FOUND
+            404
+          elsif MODERN_BAD_REQUEST_CODES.include?(error_code)
+            400
+          else
+            200
+          end
+        end
+
+        def handle_post(request, body_string: nil)
           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
@@ -465,8 +1107,10 @@ module MCP
           content_type_error = validate_content_type(request)
           return content_type_error if content_type_error
 
-          body_string = read_bounded_body(request)
-          return payload_too_large_response if body_string.nil?
+          if body_string.nil?
+            body_string = read_bounded_body(request)
+            return payload_too_large_response if body_string.nil?
+          end
 
           session_id = extract_session_id(request)
 
@@ -483,6 +1127,28 @@ module MCP
             return invalid_request_response("Invalid Request: JSON-RPC body must be a single request object")
           end
 
+          # Header-primary routing sends sessionless modern traffic to `handle_modern` before this method runs,
+          # so a body carrying the modern `_meta` triple (SEP-2575) arrives here in two shapes only.
+          # Bound to a session under a dual-era header (2026-07-28), it is a lifecycle violation: the session
+          # already negotiated the legacy lifecycle via `initialize`, and a connection can never change eras
+          # (mirroring the stdio era lock). Otherwise the header is missing or names a stable-only version,
+          # which violates the header/body match requirement and would fall through the legacy path via
+          # the header default; reject that as a header mismatch.
+          if RequestEnvelope.modern?(body[:params])
+            header_version = request.env["HTTP_MCP_PROTOCOL_VERSION"]
+            if header_version && MCP::Configuration.modern_protocol_version?(header_version)
+              return invalid_request_response(
+                "Invalid Request: the session already negotiated the legacy lifecycle via `initialize`",
+                request_id: body[:id],
+              )
+            end
+
+            return header_mismatch_response(
+              "MCP-Protocol-Version header is missing or legacy while the body carries the modern _meta envelope",
+              body[:id],
+            )
+          end
+
           # The `MCP-Protocol-Version` header is only meaningful after negotiation, so on `initialize`
           # the JSON-RPC body `params.protocolVersion` is authoritative and the header (if any) is ignored.
           # This matches the TypeScript and Python SDKs.
@@ -748,6 +1414,28 @@ module MCP
           body.is_a?(Hash) && body[:method] == Methods::SERVER_DISCOVER
         end
 
+        # A version with no modern meaning, whose header can only accompany legacy traffic.
+        # A modern version's header (2026-07-28) can accompany either era's traffic - the handshake never negotiates it,
+        # but requests of an established legacy session may stamp it - so that value needs further disambiguation.
+        def stable_only_version?(version)
+          MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(version) &&
+            !MCP::Configuration.modern_protocol_version?(version)
+        end
+
+        # Era sniff for a sessionless POST under a dual-era header version: only an `initialize` body
+        # WITHOUT the modern `_meta` envelope is legacy-distinctive. An `initialize` carrying
+        # the envelope comes from a modern client naming a method its lifecycle removed, so it stays
+        # on the modern path and answers with -32601/404 (SEP-2575).
+        # Unparsable or non-object bodies go to the modern path, whose error responses cover them.
+        def legacy_handshake_body?(body_string)
+          body = parse_request_body(body_string)
+          return false unless initialize_request?(body)
+
+          !RequestEnvelope.modern?(body[:params])
+        rescue InvalidJsonError
+          false
+        end
+
         def validate_protocol_version_header(request)
           header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"] || MCP::Configuration::DEFAULT_NEGOTIATED_PROTOCOL_VERSION
           return if MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(header_value)
@@ -760,8 +1448,10 @@ module MCP
           )
         end
 
-        def json_rpc_error_response(status:, code:, message:)
-          body = { jsonrpc: "2.0", id: nil, error: { code: code, message: message } }
+        def json_rpc_error_response(status:, code:, message:, data: nil, id: nil)
+          error = { code: code, message: message }
+          error[:data] = data if data
+          body = { jsonrpc: "2.0", id: id, error: error }
           [status, { "content-type" => "application/json" }, [body.to_json]]
         end