mcp 0.25.0 → 1.4.0

data/lib/mcp/server.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 require_relative "../json_rpc_handler"
 require_relative "cancellation"
 require_relative "cancelled_error"
@@ -7,9 +9,13 @@ require_relative "instrumentation"
 require_relative "methods"
 require_relative "logging_message_notification"
 require_relative "progress"
+require_relative "protocol_deprecations"
 require_relative "server_context"
 require_relative "server/capabilities"
+require_relative "server/input_required_result"
 require_relative "server/pagination"
+require_relative "server/pending_response"
+require_relative "server/request_state_security"
 require_relative "server/transports"
 
 module MCP
@@ -59,6 +65,43 @@ module MCP
       end
     end
 
+    # Raised when a request carries a protocol version the server does not support under the stateless lifecycle of
+    # MCP 2026-07-28 (SEP-2575). Maps to JSON-RPC error `-32022` with `data: { supported: [...], requested: "..." }`
+    # so the client can select a mutually supported version and retry.
+    #
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+    class UnsupportedProtocolVersionError < RequestHandlerError
+      # No keyword parameters here: with one present, Ruby 2.7 would split a trailing symbol-keyed `request` Hash
+      # into keywords and fail with "unknown keywords".
+      def initialize(requested, request = nil)
+        super(
+          "Unsupported protocol version",
+          request,
+          error_type: :unsupported_protocol_version,
+          error_code: ErrorCodes::UNSUPPORTED_PROTOCOL_VERSION,
+          error_data: { supported: Configuration::SUPPORTED_MODERN_PROTOCOL_VERSIONS, requested: requested || "unknown" },
+        )
+      end
+    end
+
+    # Raised when processing a request requires a client capability the request did not declare in `_meta`
+    # (`io.modelcontextprotocol/clientCapabilities`). Per SEP-2575, servers MUST NOT rely on capabilities
+    # the client has not declared. Maps to JSON-RPC error `-32021` with `data: { requiredCapabilities: {...} }`
+    # listing the missing capabilities.
+    #
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+    class MissingRequiredClientCapabilityError < RequestHandlerError
+      def initialize(required_capabilities, request = nil)
+        super(
+          "Missing required client capability",
+          request,
+          error_type: :missing_required_client_capability,
+          error_code: ErrorCodes::MISSING_REQUIRED_CLIENT_CAPABILITY,
+          error_data: { requiredCapabilities: required_capabilities },
+        )
+      end
+    end
+
     # Raised when a requested resource URI does not exist. Per SEP-2164,
     # resource-not-found errors use the standard JSON-RPC Invalid Params code (-32602)
     # with the requested URI in the error `data` member. Raise this from
@@ -85,6 +128,27 @@ module MCP
       end
     end
 
+    # Raised when a server-to-client request (sampling, elicitation, `roots/list`, `ping`) goes unanswered past its timeout.
+    # The spec asks implementations to bound every sent request so a peer that never answers cannot exhaust the sender's resources,
+    # and to cancel the request on expiry; the transport sends `notifications/cancelled` before raising this.
+    # These requests exist only on connections speaking 2025-11-25 or earlier, since the modern lifecycle forbids them.
+    #
+    # Left uncaught in a handler, this answers the client's originating request with `-32001` rather than a generic
+    # internal error, so the peer that failed to answer can tell a timeout apart from a server fault. The code is not
+    # spec-allocated: it sits in the implementation-defined server range and is the value the Python SDK reports for
+    # this condition, so a client that already recognizes it there reads the same meaning here.
+    #
+    # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#timeouts
+    class RequestTimeoutError < RequestHandlerError
+      attr_reader :request_id, :timeout
+
+      def initialize(message, request_id:, timeout:)
+        super(message, nil, error_type: :request_timeout, error_code: -32001)
+        @request_id = request_id
+        @timeout = timeout
+      end
+    end
+
     class MethodAlreadyDefinedError < StandardError
       attr_reader :method_name
 
@@ -105,8 +169,20 @@ module MCP
     # Allowed values for the SEP-2549 `cacheScope` cache hint.
     CACHE_SCOPES = ["public", "private"].freeze
 
+    # Methods whose results are cacheable per SEP-2549.
+    # On the modern wire (2026-07-28) the `ttlMs`/`cacheScope` hints are REQUIRED on these results,
+    # so unset hints get the spec defaults there; on stable protocol versions emission stays opt-in
+    # via `apply_cache_metadata`.
+    CACHEABLE_RESULT_METHODS = [
+      Methods::TOOLS_LIST,
+      Methods::PROMPTS_LIST,
+      Methods::RESOURCES_LIST,
+      Methods::RESOURCES_TEMPLATES_LIST,
+      Methods::RESOURCES_READ,
+    ].freeze
+
     attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resource_templates, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
-    attr_reader :resources, :page_size, :client_capabilities, :ttl_ms, :cache_scope
+    attr_reader :resources, :page_size, :client_capabilities, :ttl_ms, :cache_scope, :request_state_security
 
     def initialize(
       description: nil,
@@ -126,6 +202,8 @@ module MCP
       page_size: nil,
       ttl_ms: nil,
       cache_scope: nil,
+      request_state_security: nil,
+      input_required_legacy_shim: true,
       transport: nil
     )
       @description = description
@@ -141,12 +219,21 @@ module MCP
       @resources = resources
       @resource_templates = resource_templates
       @resource_index = index_resources_by_uri(resources)
+      @resources_list_handler = nil
       @server_context = server_context
       self.page_size = page_size
       self.ttl_ms = ttl_ms
       self.cache_scope = cache_scope
+      @request_state_security = request_state_security
+
+      # Dual-era authoring (SEP-2322): on the legacy wire, an `input_required` result is fulfilled
+      # through real server-to-client requests and the handler re-runs, so handlers written
+      # in the 2026 style serve both eras. `false` restores the strict rejection of `input_required`
+      # on legacy requests. Matches the TypeScript SDK's default-on legacy shim.
+      @input_required_legacy_shim = input_required_legacy_shim
       @configuration = MCP.configuration.merge(configuration)
       @client = nil
+      @client_protocol_version = nil
 
       validate!
 
@@ -340,6 +427,22 @@ module MCP
       @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
     end
 
+    # Sets a custom handler for `resources/list` requests, letting the visible list depend on request context such as
+    # the authenticated principal or granted scope. The block returns the resource collection to serve;
+    # the framework paginates it and stamps SEP-2549 cache hints exactly as it does for the constructor-provided resources,
+    # so the block returns only the array, not the paginated result.
+    # A block that declares a `server_context:` keyword receives an `MCP::ServerContext`. When no handler is set,
+    # the constructor-provided `resources` array is served unchanged.
+    #
+    # The block is invoked once per page, so it must return a stable ordering across the pages of one logical query;
+    # the cursor is a positional offset into the returned collection.
+    #
+    # @yield [params, server_context:] The request params, and an `MCP::ServerContext` when declared.
+    # @yieldreturn [Array<MCP::Resource>] The resources to paginate.
+    def resources_list_handler(&block)
+      @resources_list_handler = block
+    end
+
     # Sets a custom handler for `resources/read` requests.
     # The block receives the parsed request params and should return resource
     # contents. The return value is set as the `contents` field of the response.
@@ -360,19 +463,25 @@ module MCP
     end
 
     # Sets a custom handler for `resources/subscribe` requests.
-    # The block receives the parsed request params. The return value is
-    # ignored; the response is always an empty result `{}` per the MCP specification.
+    # The block receives the parsed request params. The response is an empty result, except that
+    # a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
+    # so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
+    # under `_meta`.
     #
     # @yield [params] The request params containing `:uri`.
+    # @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
     def resources_subscribe_handler(&block)
       @handlers[Methods::RESOURCES_SUBSCRIBE] = block
     end
 
     # Sets a custom handler for `resources/unsubscribe` requests.
-    # The block receives the parsed request params. The return value is
-    # ignored; the response is always an empty result `{}` per the MCP specification.
+    # The block receives the parsed request params. The response is an empty result, except that
+    # a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
+    # so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
+    # under `_meta`.
     #
     # @yield [params] The request params containing `:uri`.
+    # @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
     def resources_unsubscribe_handler(&block)
       @handlers[Methods::RESOURCES_UNSUBSCRIBE] = block
     end
@@ -510,12 +619,47 @@ module MCP
         return
       end
 
-      Methods.ensure_capability!(method, capabilities)
+      # SEP-2575 removes these RPCs from the modern lifecycle, so they answer with Method not found
+      # there regardless of the server's declared capabilities: in this era the method does not exist
+      # at all, which is why the check precedes `ensure_capability!`.
+      if Methods::MODERN_REMOVED_METHODS.include?(method) && modern_request?(request, session)
+        raise RequestHandlerError.new(
+          "Method not found: #{method} is not part of the modern lifecycle (SEP-2575)",
+          request,
+          error_type: :method_not_found,
+          error_code: JsonRpcHandler::ErrorCode::METHOD_NOT_FOUND,
+        )
+      end
+
+      begin
+        Methods.ensure_capability!(method, capabilities)
+      rescue Methods::MissingRequiredCapabilityError => e
+        # Re-raise through RequestHandlerError, the one channel whose message is
+        # deliberately surfaced to clients: `JsonRpcHandler`'s blind `rescue StandardError`
+        # no longer echoes exception messages into the error `data` member (CWE-209).
+        raise RequestHandlerError.new(e.message, request, error_type: :internal_error, original_error: e)
+      end
 
       # `initialize` MUST NOT be cancelled (MCP spec 2025-11-25, cancellation item 2),
       # so do not track it in the in-flight registry.
-      cancellation = if related_request_id && method != Methods::INITIALIZE
-        session&.register_in_flight(related_request_id)
+      cancellation = nil
+      if related_request_id && method != Methods::INITIALIZE && session
+        cancellation = session.register_in_flight(related_request_id)
+
+        # The spec puts the uniqueness obligation on the sender - "The request ID MUST NOT have been previously used by
+        # the requestor within the same session" - and says nothing about what a receiver does with a duplicate.
+        # Answering one is the only option that stays correct: the id routes request-scoped messages back to
+        # the request that caused them, and the transport's rule is that those messages "SHOULD relate to
+        # the originating client request", which a second live request under the same id makes impossible to honor
+        # for either of them. Refused the same way a duplicate `initialize` is, and for the same reason:
+        # so that a repeated id cannot silently displace state negotiated by the first one.
+        if cancellation.nil?
+          raise RequestHandlerError.new(
+            "Invalid Request: request id #{related_request_id.inspect} is already in flight",
+            request,
+            error_type: :invalid_request,
+          )
+        end
       end
 
       ->(params) {
@@ -525,25 +669,42 @@ module MCP
           server_context: { request: request },
           exception_already_reported: ->(e) { reported_exception.equal?(e) },
         ) do
+          envelope = lift_request_envelope(params, method: method, session: session)
+
+          # The envelope's `logLevel` member replaces `logging/setLevel` in the modern lifecycle:
+          # it authorizes `notifications/message` for this request only (SEP-2575). Without it,
+          # `ServerSession#notify_log_message` stays silent on modern-era sessions. An unrecognized level
+          # reads as absent, so delivery stays off (the safe direction), matching the Python SDK.
+          if envelope&.log_level && session.respond_to?(:configure_logging)
+            request_logging = LoggingMessageNotification.new(level: envelope.log_level)
+            session.configure_logging(request_logging) if request_logging.valid_level?
+          end
+
+          params = unseal_request_state(params, method: method) if @request_state_security
+
           result = case method
           when Methods::INITIALIZE
             init(params, session: session)
           when Methods::RESOURCES_READ
-            build_read_resource_result(read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation))
+            contents = read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+
+            # An SEP-2322 `input_required` result must not be wrapped as `contents` or stamped with SEP-2549 cache hints.
+            contents.is_a?(InputRequiredResult) ? contents : build_read_resource_result(contents)
           when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
             validate_resource_subscription_params!(params)
-            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation)
-            {}
+            handler_result = dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+
+            subscription_result(handler_result)
           when Methods::TOOLS_CALL
-            call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+            call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
           when Methods::PROMPTS_GET
-            get_prompt(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+            get_prompt(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
           when Methods::COMPLETION_COMPLETE
-            complete(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+            complete(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
           when Methods::LOGGING_SET_LEVEL
             configure_logging_level(params, session: session)
           else
-            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
           end
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
@@ -553,6 +714,43 @@ module MCP
             next JsonRpcHandler::NO_RESPONSE
           end
 
+          # Runs after the cancellation check so a cancelled request stays suppressed
+          # instead of turning into a gate error response.
+          if result.is_a?(InputRequiredResult)
+            result = if envelope.nil? && @input_required_legacy_shim && session
+              run_legacy_input_required_shim(
+                result,
+                method: method,
+                params: params,
+                session: session,
+                related_request_id: related_request_id,
+                cancellation: cancellation,
+              )
+            else
+              serialize_input_required_result(result, envelope: envelope, request: params, method: method)
+            end
+          end
+
+          # SEP-2322 makes `resultType` REQUIRED on every result a 2026-07-28 server returns;
+          # a missing value is only tolerated FROM earlier protocol versions. Results that already carry
+          # a discriminator keep it; everything else on the modern wire is the standard shape,
+          # `"complete"`. Legacy results stay unstamped: pre-2026 clients do not know the field.
+          if envelope && result.is_a?(Hash) && !result.key?(:resultType)
+            result = result.merge(resultType: ResultType::COMPLETE)
+          end
+
+          # SEP-2549 makes the `ttlMs`/`cacheScope` hints REQUIRED on cacheable results at 2026-07-28,
+          # so unconfigured servers get `ttlMs: 0` (do not cache) and `cacheScope: "private"`:
+          # the spec names no default scope, and `"private"` is the side that cannot leak
+          # a user-dependent result through a shared cache, matching the TypeScript SDK's default
+          # and `server/discover`. Values already in the result win.
+          # Only complete results are cacheable: an SEP-2322 `input_required` round trip must not be stamped
+          # (the stamp above guarantees `resultType` is present on every modern Hash result by this point).
+          if envelope && result.is_a?(Hash) && CACHEABLE_RESULT_METHODS.include?(method) &&
+              result[:resultType] == ResultType::COMPLETE && !(result.key?(:ttlMs) && result.key?(:cacheScope))
+            result = { ttlMs: @ttl_ms || 0, cacheScope: @cache_scope || "private" }.merge(result)
+          end
+
           result
         rescue CancelledError => e
           add_instrumentation_data(cancelled: true, cancellation_reason: e.reason)
@@ -569,11 +767,267 @@ module MCP
           reported_exception = wrapped
           raise wrapped
         ensure
-          session&.unregister_in_flight(related_request_id) if related_request_id
+          # `cancellation` is non-nil exactly when this request claimed the id above, so this also keeps `initialize`
+          # (which never registers) from evicting an in-flight registration under a reused id when the duplicate-`initialize`
+          # refusal raises out of the handler.
+          session&.unregister_in_flight(related_request_id, cancellation: cancellation) if related_request_id && cancellation
         end
       }
     end
 
+    # Whether this request belongs to the modern lifecycle, used to refuse the RPCs SEP-2575 removed from it.
+    # A locked `ServerSession#era` is authoritative; until it locks, the request's own `_meta` envelope is
+    # the signal. Both are needed because `StdioTransport` locks the era only after a response succeeds,
+    # which would otherwise let the first request of a connection reach a method the modern lifecycle does not have.
+    # The Python SDK gates the same way, on the envelope of each request rather than on connection state that
+    # is only settled afterwards.
+    #
+    # A legacy-locked session is deliberately excluded: `lift_request_envelope` answers a modern envelope there
+    # with the lifecycle violation, which names the cause better than Method not found.
+    def modern_request?(request, session)
+      era = session.respond_to?(:era) ? session.era : nil
+      return true if era == :modern
+      return false unless era.nil?
+
+      RequestEnvelope.modern?(request.is_a?(Hash) ? request[:params] : nil)
+    end
+
+    # Lifts the SEP-2575 per-request `_meta` envelope for modern requests. Only a request whose `_meta` carries
+    # the full required triple is classified as modern; a partial triple keeps flowing through the legacy path untouched.
+    # Notifications carry no envelope (their `_meta` is a `NotificationMetaObject`), and `server/discover` is
+    # pre-version discovery, so both are exempt. Era-locked sessions additionally enforce the dual-era rules:
+    # on a modern session, `initialize` is rejected with `-32022` (the modern lifecycle has no handshake)
+    # and the triple becomes required for every other request; on a legacy session, a modern envelope is rejected as
+    # an invalid request because a connection can never change eras.
+    def lift_request_envelope(params, method:, session:)
+      return if Methods.notification?(method)
+
+      era = session.respond_to?(:era) ? session.era : nil
+
+      # Outside the modern era, `server/discover` stays envelope-exempt so legacy connections can probe capabilities
+      # before any negotiation. Under the modern era every request carries the envelope, discovery included:
+      # the conformance suite's 2026-07-28 requirements reject an envelope-less `server/discover` with `-32602` (SEP-2575).
+      return if method == Methods::SERVER_DISCOVER && era != :modern
+
+      if RequestEnvelope.modern?(params)
+        if era == :legacy
+          raise RequestHandlerError.new(
+            "Invalid Request: the session already negotiated the legacy lifecycle via `initialize`",
+            params,
+            error_type: :invalid_request,
+          )
+        end
+
+        RequestEnvelope.parse!(params, request: params)
+      elsif era == :modern
+        # A claim-less request on a modern session is a malformed envelope, not a malformed request:
+        # the spec maps missing required envelope fields to Invalid params (`-32602`),
+        # and the reference SDKs answer it naming the missing keys.
+        raise RequestHandlerError.new(
+          "Invalid params: missing or invalid `#{RequestEnvelope::REQUIRED_META_KEYS.join("`, `")}` in `_meta`",
+          params,
+          error_type: :invalid_params,
+          error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+        )
+      end
+    end
+
+    # Central gate and serializer for SEP-2322 `input_required` results, run once in the dispatch lambda for
+    # whichever handler produced one. The result type exists only in the 2026-07-28 stateless lifecycle,
+    # so a legacy request (no envelope) must not receive it: pre-2026 clients treat an unknown `resultType` as
+    # a final result. The capability gate enforces the SEP-2575 rule that servers MUST NOT rely on
+    # (or embed requests for) capabilities the client did not declare, and reports every missing capability at
+    # once so the client sees the full set.
+    def serialize_input_required_result(result, envelope:, request:, method:)
+      if envelope.nil?
+        raise RequestHandlerError.new(
+          "input_required results require the 2026-07-28 stateless lifecycle (SEP-2322)",
+          request,
+          error_type: :internal_error,
+        )
+      end
+
+      missing = result.missing_client_capabilities(envelope.client_capabilities)
+      raise MissingRequiredClientCapabilityError.new(missing, request) unless missing.empty?
+
+      add_instrumentation_data(input_required: true)
+      serialized = result.to_h
+
+      if @request_state_security && serialized[:requestState]
+        serialized = serialized.merge(requestState: @request_state_security.seal(
+          serialized[:requestState],
+          method: method,
+          target: mrtr_target(request),
+          arguments_digest: mrtr_arguments_digest(request),
+        ))
+      end
+
+      serialized
+    end
+
+    # Methods whose results may be `input_required` and whose retried requests carry
+    # `inputResponses`/`requestState` (SEP-2322).
+    MRTR_METHODS = [Methods::TOOLS_CALL, Methods::PROMPTS_GET, Methods::RESOURCES_READ].freeze
+
+    # Fulfilment rounds the legacy shim runs before giving up, matching the TypeScript SDK's legacy shim default (`maxRounds: 8`).
+    LEGACY_INPUT_REQUIRED_MAX_ROUNDS = 8
+
+    # Dual-era authoring shim (SEP-2322): a handler on the legacy wire returned an `input_required` result,
+    # which pre-2026 clients cannot understand, so the server fulfills it in place of the client's driver.
+    # Every entry of `inputRequests` is sent as the equivalent real server-to-client request (associated with
+    # the originating request per SEP-2260), the answers are collected under the same keys, and the handler
+    # re-runs with `inputResponses`/`requestState` merged into the original params - the same deterministic replay
+    # contract the modern client driver follows. The `requestState` round-trips in-process as the raw value
+    # the handler wrote; `RequestStateSecurity` sealing is wire hardening and does not apply.
+    def run_legacy_input_required_shim(result, method:, params:, session:, related_request_id:, cancellation:)
+      rounds = 0
+
+      loop do
+        missing = result.missing_client_capabilities(session.client_capabilities)
+        unless missing.empty?
+          # The explicit `error_code` keeps the descriptive message in the JSON-RPC error response
+          # (the `ResourceNotFoundError` pattern). `-32021` is a 2026-07-28 code, so the legacy wire
+          # gets a plain internal error.
+          raise RequestHandlerError.new(
+            "input_required requires client capabilities the client did not declare: #{missing.to_json}",
+            params,
+            error_type: :internal_error,
+            error_code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+          )
+        end
+
+        responses = (result.input_requests || {}).each_with_object({}) do |(key, entry), collected|
+          collected[key] = session.fulfill_input_request(
+            entry[:method],
+            legacy_leg_params(entry),
+            related_request_id: related_request_id,
+          )
+        end
+
+        retry_params = params.reject { |key, _| [:inputResponses, :requestState].include?(key.to_sym) }
+        retry_params[:inputResponses] = responses unless responses.empty?
+        retry_params[:requestState] = result.request_state if result.request_state
+
+        result = redispatch_mrtr_method(
+          method,
+          retry_params,
+          session: session,
+          related_request_id: related_request_id,
+          cancellation: cancellation,
+        )
+        return result unless result.is_a?(InputRequiredResult)
+
+        rounds += 1
+        next if rounds < LEGACY_INPUT_REQUIRED_MAX_ROUNDS
+
+        raise RequestHandlerError.new(
+          "Handler still returned `input_required` after #{LEGACY_INPUT_REQUIRED_MAX_ROUNDS} legacy shim rounds (SEP-2322)",
+          params,
+          error_type: :internal_error,
+          error_code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+        )
+      end
+    end
+
+    # The params an embedded entry sends on its legacy leg. Entries are forwarded verbatim with
+    # one exception: the 2025-11-25 wire requires `elicitationId` on URL-mode elicitation requests,
+    # a field the 2026-07-28 in-band shape dropped (correlation rides `requestState` there),
+    # so a missing one is synthesized for the leg, matching the TypeScript SDK's shim.
+    def legacy_leg_params(entry)
+      params = entry[:params]
+      return params unless entry[:method] == Methods::ELICITATION_CREATE
+      return params if params.nil? || (params[:mode] || params["mode"]) != "url"
+      return params if params.key?(:elicitationId) || params.key?("elicitationId")
+
+      params.merge(elicitationId: SecureRandom.uuid)
+    end
+
+    # Re-runs the handler of one of the three MRTR-capable methods for
+    # the legacy shim. Legacy wire, so no envelope is threaded.
+    def redispatch_mrtr_method(method, params, session:, related_request_id:, cancellation:)
+      case method
+      when Methods::TOOLS_CALL
+        call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+      when Methods::PROMPTS_GET
+        get_prompt(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+      when Methods::RESOURCES_READ
+        contents = read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+        contents.is_a?(InputRequiredResult) ? contents : build_read_resource_result(contents)
+      else
+        raise RequestHandlerError.new(
+          "input_required results are only supported for #{MRTR_METHODS.join(", ")}",
+          params,
+          error_type: :internal_error,
+        )
+      end
+    end
+
+    # Replaces a sealed client-echoed `requestState` with its verified plaintext before dispatch,
+    # so handlers always read the state they wrote. A tampered, expired, or cross-request token is
+    # rejected as invalid params, matching the Python SDK's "Invalid or expired requestState" behavior.
+    def unseal_request_state(params, method:)
+      return params unless MRTR_METHODS.include?(method)
+      return params unless params.is_a?(Hash)
+
+      sealed = params[:requestState] || params["requestState"]
+      return params unless sealed
+
+      plaintext = @request_state_security.unseal(
+        sealed,
+        method: method,
+        target: mrtr_target(params),
+        arguments_digest: mrtr_arguments_digest(params),
+      )
+      key = params.key?("requestState") ? "requestState" : :requestState
+      params.merge(key => plaintext)
+    rescue RequestStateSecurity::InvalidStateError => e
+      raise RequestHandlerError.new(
+        "Invalid or expired requestState",
+        params,
+        error_type: :invalid_params,
+        error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+        original_error: e,
+      )
+    end
+
+    def mrtr_target(params)
+      return "" unless params.is_a?(Hash)
+
+      params[:name] || params["name"] || params[:uri] || params["uri"] || ""
+    end
+
+    # Digest of the originating arguments, binding a sealed state to retries of
+    # the same call with the same inputs. Keys are stringified and sorted recursively
+    # so symbol/string parses of identical JSON digest identically.
+    def mrtr_arguments_digest(params)
+      arguments = params.is_a?(Hash) ? params[:arguments] || params["arguments"] : nil
+      OpenSSL::Digest::SHA256.hexdigest(canonical_json(arguments || {}))
+    end
+
+    def canonical_json(value)
+      case value
+      when Hash
+        pairs = value.map { |key, nested| [key.to_s, nested] }.sort_by(&:first)
+        "{#{pairs.map { |key, nested| "#{key.to_json}:#{canonical_json(nested)}" }.join(",")}}"
+      when Array
+        "[#{value.map { |element| canonical_json(element) }.join(",")}]"
+      else
+        value.to_json
+      end
+    end
+
+    # Extracts the SEP-2322 retry fields a client sends when re-issuing a request:
+    # `inputResponses` (answers keyed like the earlier `inputRequests`) and the echoed opaque `requestState`.
+    # They are params-top-level siblings of `name`/`arguments`/ `uri`, not `_meta` entries.
+    def mrtr_retry_fields(params)
+      return { input_responses: nil, request_state: nil } unless params.is_a?(Hash)
+
+      {
+        input_responses: params[:inputResponses] || params["inputResponses"],
+        request_state: params[:requestState] || params["requestState"],
+      }
+    end
+
     def handle_cancelled_notification(params, session: nil)
       return unless session
       return unless params.is_a?(Hash)
@@ -623,10 +1077,19 @@ module MCP
       end
       protocol_version = params[:protocolVersion]
 
-      negotiated_version = if Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
+      # Per the SEP-2575 era model, `initialize` negotiates legacy protocol versions only: a modern version is
+      # defined by carrying its own version on every request in `_meta`, with no handshake,
+      # so asking `initialize` for one (or for a version this server does not know) is answered with
+      # a counter-offer instead of an echo, matching the TypeScript and Python SDKs. Modern versions
+      # stay reachable through `server/discover` and the per-request envelope. The counter-offer is
+      # a configured `protocol_version` pin when one is set (`Configuration` only accepts handshake versions there),
+      # and the latest handshake version otherwise.
+      negotiated_version = if Configuration.handshake_protocol_version?(protocol_version)
         protocol_version
-      else
+      elsif configuration.protocol_version?
         configuration.protocol_version
+      else
+        Configuration::LATEST_HANDSHAKE_PROTOCOL_VERSION
       end
 
       info = server_info.reject do |property|
@@ -640,7 +1103,11 @@ module MCP
         response_instructions = nil
       end
 
-      session&.mark_initialized!
+      if session
+        session.mark_initialized!(protocol_version: negotiated_version)
+      else
+        @client_protocol_version = negotiated_version
+      end
 
       {
         protocolVersion: negotiated_version,
@@ -656,6 +1123,18 @@ module MCP
       end
     end
 
+    # The `resources/subscribe` and `resources/unsubscribe` result is an empty object except for the optional `_meta`
+    # every result may carry: the TypeScript SDK validates it against `EmptyResultSchema.strict()`,
+    # which rejects any other member, so only `_meta` is passed through from the handler. A handler that returns
+    # anything else keeps the empty `{}` result it had before, so returning a subscription identifier or
+    # other advisory data means nesting it under `_meta`.
+    def subscription_result(handler_result)
+      return {} unless handler_result.is_a?(Hash)
+
+      meta = handler_result[:_meta] || handler_result["_meta"]
+      meta.is_a?(Hash) ? { _meta: meta } : {}
+    end
+
     def validate_initialize_params!(params)
       unless params.is_a?(Hash)
         raise RequestHandlerError.new("Invalid params", params, error_type: :invalid_params)
@@ -675,20 +1154,47 @@ module MCP
       end
     end
 
-    # Handles `server/discover` (MCP 2026-07-28 draft, SEP-2575): sessionless capability discovery.
+    # Handles `server/discover` (MCP 2026-07-28, SEP-2575): sessionless capability discovery.
     # Unlike `init`, this is state-free and idempotent: it stores no client info, does not mark
     # the session initialized, and responds regardless of capability declarations or initialization state,
-    # so clients can probe a server before (or instead of) `initialize`. `serverInfo` is returned unfiltered
-    # because discovery happens before version negotiation. The draft's `ttlMs`/`cacheScope` cache hints
-    # are not included here yet.
+    # so clients can probe a server before (or instead of) `initialize`.
+    #
+    # `supportedVersions` advertises modern versions only, matching the TypeScript and Python SDKs:
+    # legacy versions are negotiated via `initialize`, not selected from discovery. The `ttlMs`/`cacheScope`
+    # cache hints are REQUIRED on `DiscoverResult` (unlike the opt-in SEP-2549 hints on list/read results),
+    # so the spec defaults (`0` = immediately stale, `"private"` = per-authorization-context caching only)
+    # fill in when the server was not configured with `ttl_ms`/`cache_scope`. The server identity rides
+    # in the result `_meta` as the optional `io.modelcontextprotocol/serverInfo` stamp per the finalized
+    # spec (PR #3002), unfiltered because discovery happens before version negotiation.
     # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
     def discover(_request)
       {
-        supportedVersions: Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS,
-        capabilities: capabilities,
-        serverInfo: server_info,
+        supportedVersions: Configuration::SUPPORTED_MODERN_PROTOCOL_VERSIONS,
+        capabilities: discover_capabilities,
         instructions: instructions,
-      }.compact
+        _meta: { RequestEnvelope::SERVER_INFO_META_KEY => server_info },
+      }.compact.merge(
+        ttlMs: ttl_ms || 0,
+        cacheScope: cache_scope || "private",
+        # `server/discover` is exempt from the `_meta` envelope, so the central modern-result stamping does not see it;
+        # `DiscoverResult` is still a 2026-07-28 result and carries the REQUIRED `resultType` directly.
+        resultType: ResultType::COMPLETE,
+      )
+    end
+
+    # Capabilities as advertised by `server/discover`. In the modern lifecycle, `listChanged` and `subscribe` flags
+    # promise delivery over `subscriptions/listen` streams, so they are stripped when the transport does not serve that RPC
+    # (e.g. stdio), matching the Python SDK's era-aware capability derivation.
+    def discover_capabilities
+      return capabilities if @transport.respond_to?(:serves_subscriptions_listen?) && @transport.serves_subscriptions_listen?
+
+      capabilities.each_with_object({}) do |(name, value), stripped|
+        stripped[name] = if value.is_a?(Hash)
+          value.reject { |flag, _| ["listChanged", "subscribe"].include?(flag.to_s) }
+        else
+          value
+        end
+      end
     end
 
     def configure_logging_level(request, session: nil)
@@ -713,7 +1219,7 @@ module MCP
       apply_cache_metadata({ tools: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
-    def call_tool(request, session: nil, related_request_id: nil, cancellation: nil)
+    def call_tool(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -745,18 +1251,38 @@ module MCP
 
       progress_token = request.dig(:_meta, :progressToken)
 
-      result = call_tool_with_args(
-        tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id, cancellation: cancellation
+      response = call_tool_with_args(
+        tool,
+        arguments,
+        server_context_with_meta(request),
+        progress_token: progress_token,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+        envelope: envelope,
+        retry_fields: mrtr_retry_fields(request),
       )
+      # An SEP-2322 `input_required` result is not a tool result: output schema
+      # validation would run against a `nil` `structuredContent` and the structured
+      # content fallback does not apply. The dispatch lambda serializes it.
+      return response if response.is_a?(InputRequiredResult)
+
+      result = response.to_h
       validate_tool_call_result!(tool, result)
-      serialize_structured_content_fallback(result)
+      serialize_structured_content_fallback(
+        result,
+        content_provided: response.respond_to?(:content_provided?) && response.content_provided?,
+      )
     rescue RequestHandlerError, CancelledError
       # CancelledError is intentionally not wrapped so `handle_request` can turn it into
       # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
       raise
     rescue => e
+      # `e.message` is deliberately not included: it can carry internals (class, method
+      # and host names) that must not reach untrusted clients (CWE-209). The original
+      # exception still reaches `configuration.exception_reporter` via `original_error`.
       raise RequestHandlerError.new(
-        "Internal error calling tool #{tool_name}: #{e.message}",
+        "Internal error calling tool #{tool_name}",
         request,
         error_type: :internal_error,
         original_error: e,
@@ -769,12 +1295,21 @@ module MCP
       apply_cache_metadata({ prompts: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
-    def get_prompt(request, session: nil, related_request_id: nil, cancellation: nil)
+    def get_prompt(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
       prompt_name = request[:name]
       prompt = @prompts[prompt_name]
       unless prompt
         add_instrumentation_data(error: :prompt_not_found)
-        raise RequestHandlerError.new("Prompt not found #{prompt_name}", request, error_type: :prompt_not_found)
+        # The explicit `error_code` maps an unknown prompt to Invalid Params (-32602) rather than
+        # the default Internal Error (-32603), matching the `tools/call`, `resources/read`, and
+        # `completion/complete` siblings for the same not-found condition, while `error_type:
+        # :prompt_not_found` keeps the descriptive message and instrumentation label.
+        raise RequestHandlerError.new(
+          "Prompt not found #{prompt_name}",
+          request,
+          error_type: :prompt_not_found,
+          error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+        )
       end
 
       add_instrumentation_data(prompt_name: prompt_name)
@@ -787,17 +1322,34 @@ module MCP
         session: session,
         related_request_id: related_request_id,
         cancellation: cancellation,
+        envelope: envelope,
       )
 
       call_prompt_template_with_args(prompt, prompt_args, server_context)
     end
 
-    def list_resources(request)
-      page = paginate(@resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+    def list_resources(request, server_context: nil)
+      resources = if @resources_list_handler
+        invoke_resources_list_handler(request, server_context)
+      else
+        @resources
+      end
+
+      page = paginate(resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
 
       apply_cache_metadata({ resources: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
+    # Calls the `resources_list_handler` block, forwarding `server_context:` only when the block opts in
+    # by declaring the keyword (the same rule `dispatch_optional_context_handler` applies).
+    def invoke_resources_list_handler(request, server_context)
+      if handler_declares_server_context?(@resources_list_handler)
+        @resources_list_handler.call(request, server_context: server_context)
+      else
+        @resources_list_handler.call(request)
+      end
+    end
+
     # Default `resources/read` handler: routes to class-based resources and resource templates.
     # Fully replaced when `resources_read_handler` is set. When no class-based resource or template is registered,
     # unknown URIs keep the historical no-op `[]` response instead of raising.
@@ -871,18 +1423,19 @@ module MCP
     end
 
     # Adds the SEP-2549 cache hints (`ttlMs`, `cacheScope`) to a result. Emission is opt-in: nothing is added
-    # unless the server was configured with `ttl_ms`/`cache_scope` or the result already carries one of the fields, in
-    # which case the missing one is filled with the spec defaults (`ttlMs: 0` = do not cache, `cacheScope: "public"`).
+    # unless the server was configured with `ttl_ms`/`cache_scope` or the result already carries one of the fields,
+    # in which case the missing one is filled with `ttlMs: 0` (do not cache) or `cacheScope: "private"`,
+    # the side that cannot leak a user-dependent result through a shared cache (the TypeScript SDK's default).
     # Values already in the result win, enabling per-result overrides.
     # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549
     def apply_cache_metadata(result)
       explicit = result.key?(:ttlMs) || result.key?(:cacheScope)
       return result if @ttl_ms.nil? && @cache_scope.nil? && !explicit
 
-      { ttlMs: @ttl_ms || 0, cacheScope: @cache_scope || "public" }.merge(result)
+      { ttlMs: @ttl_ms || 0, cacheScope: @cache_scope || "private" }.merge(result)
     end
 
-    def complete(params, session: nil, related_request_id: nil, cancellation: nil)
+    def complete(params, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
       validate_completion_params!(params)
 
       result = dispatch_optional_context_handler(
@@ -891,6 +1444,7 @@ module MCP
         session: session,
         related_request_id: related_request_id,
         cancellation: cancellation,
+        envelope: envelope,
       )
 
       normalize_completion_result(result)
@@ -899,13 +1453,14 @@ module MCP
     # Invokes `resources/read` via the registered handler. If the handler block opts in to `server_context:`,
     # pass an `MCP::ServerContext` so the handler can observe cancellation via `server_context.cancelled?` or
     # `server_context.raise_if_cancelled!`.
-    def read_resource_contents(request, session: nil, related_request_id: nil, cancellation: nil)
+    def read_resource_contents(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
       dispatch_optional_context_handler(
         @handlers[Methods::RESOURCES_READ],
         request,
         session: session,
         related_request_id: related_request_id,
         cancellation: cancellation,
+        envelope: envelope,
       )
     end
 
@@ -913,7 +1468,7 @@ module MCP
     # `completion_handler`, `resources_subscribe_handler`, `resources_unsubscribe_handler`, or `define_custom_method`.
     # Existing handlers that only accept `params` are called unchanged; handlers that declare a `server_context:`
     # keyword receive an `MCP::ServerContext` wrapping the raw server context with cancellation plumbing.
-    def dispatch_optional_context_handler(handler, params, session: nil, related_request_id: nil, cancellation: nil)
+    def dispatch_optional_context_handler(handler, params, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
       return handler.call(params) unless handler_declares_server_context?(handler)
 
       server_context = build_server_context(
@@ -921,6 +1476,7 @@ module MCP
         session: session,
         related_request_id: related_request_id,
         cancellation: cancellation,
+        envelope: envelope,
       )
       handler.call(params, server_context: server_context)
     end
@@ -945,16 +1501,20 @@ module MCP
 
     # Builds an `MCP::ServerContext` used to give a handler access to session-scoped helpers
     # (progress, cancellation, nested server-to-client requests).
-    def build_server_context(request:, session:, related_request_id:, cancellation:)
+    def build_server_context(request:, session:, related_request_id:, cancellation:, envelope: nil)
       meta_source = request.is_a?(Hash) ? request : {}
       progress_token = meta_source.dig(:_meta, :progressToken)
       progress = Progress.new(notification_target: session, progress_token: progress_token, related_request_id: related_request_id)
+      retry_fields = mrtr_retry_fields(meta_source)
       ServerContext.new(
         server_context_with_meta(meta_source),
         progress: progress,
         notification_target: session,
         related_request_id: related_request_id,
         cancellation: cancellation,
+        envelope: envelope,
+        input_responses: retry_fields[:input_responses],
+        request_state: retry_fields[:request_state],
       )
     end
 
@@ -986,14 +1546,18 @@ module MCP
 
     # Per SEP-2106, `structuredContent` may be any JSON value, not only an object.
     # Clients on older protocol versions may only read `content`,
-    # so when a tool returns non-object structured content without providing
-    # any content blocks, mirror the value into `content` as serialized JSON text.
-    def serialize_structured_content_fallback(result)
+    # so when a tool returns non-object structured content without explicitly
+    # providing `content`, mirror the value into serialized JSON text.
+    def serialize_structured_content_fallback(result, content_provided: false)
       structured = result[:structuredContent]
       return result if structured.nil? || structured.is_a?(Hash)
+      return result if content_provided
       return result unless result[:content].nil? || result[:content].empty?
 
-      result.merge(content: [{ type: "text", text: JSON.generate(structured) }])
+      serialized = JSON.generate(structured)
+      return result if JSON.parse(serialized).is_a?(Hash)
+
+      result.merge(content: [{ type: "text", text: serialized }])
     end
 
     # Whether a tool/prompt handler opts in to receiving an `MCP::ServerContext`.
@@ -1010,11 +1574,11 @@ module MCP
       end
     end
 
-    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil, cancellation: nil)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, retry_fields: nil)
       # Transports parse incoming JSON with `symbolize_names: true`, so `arguments` already arrives symbolized
       # at every nesting level. This top-level transform only guards callers that hand in string-keyed top-level arguments;
       # it does not recurse, and nested object keys remain symbols. Tools therefore receive symbol keys all the way down.
-      # See docs/building-servers.md ("Tool argument keys").
+      # See docs/server/tools.md ("Tool argument keys").
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
@@ -1025,19 +1589,24 @@ module MCP
           notification_target: session,
           related_request_id: related_request_id,
           cancellation: cancellation,
+          envelope: envelope,
+          input_responses: retry_fields&.fetch(:input_responses, nil),
+          request_state: retry_fields&.fetch(:request_state, nil),
         )
-        tool.call(**args, server_context: server_context).to_h
+        tool.call(**args, server_context: server_context)
       else
-        tool.call(**args).to_h
+        tool.call(**args)
       end
     end
 
     def call_prompt_template_with_args(prompt, args, server_context)
-      if accepts_server_context?(prompt.method(:template))
-        prompt.template(args, server_context: server_context).to_h
+      raw_result = if accepts_server_context?(prompt.method(:template))
+        prompt.template(args, server_context: server_context)
       else
-        prompt.template(args).to_h
+        prompt.template(args)
       end
+
+      raw_result.is_a?(InputRequiredResult) ? raw_result : raw_result.to_h
     end
 
     def server_context_with_meta(request)