mcp 0.23.0 → 0.24.0

data/lib/mcp/client/oauth/flow.rb

@@ -74,13 +74,20 @@ module MCP
           )
 
           @provider.redirect_handler.call(authorization_url)
-          code, returned_state = Array(@provider.callback_handler.call)
+          callback_result = Array(@provider.callback_handler.call)
+          code, returned_state, returned_iss = callback_result
           raise AuthorizationError, "Authorization callback did not return an authorization code." unless code
 
           unless states_match?(returned_state, state)
             raise AuthorizationError, "OAuth state mismatch (CSRF protection)."
           end
 
+          validate_authorization_response_issuer!(
+            as_metadata: as_metadata,
+            iss: returned_iss,
+            iss_provided: callback_result.length >= 3,
+          )
+
           tokens = exchange_authorization_code(
             as_metadata: as_metadata,
             client_info: client_info,
@@ -101,6 +108,7 @@ module MCP
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
         def run_client_credentials!(as_metadata:, prm:, resource:, scope:)
           client_info = client_credentials_client_info
+          ensure_client_credentials_issuer!(client_info, as_metadata: as_metadata)
 
           form = { "grant_type" => "client_credentials" }
           effective_scope = resolve_scope(scope: scope, prm: prm)
@@ -127,6 +135,25 @@ module MCP
           info
         end
 
+        # Per SEP-2352, static machine-to-machine credentials are bound to their authorization
+        # server the same way registered ones are: when the stored `client_information` records
+        # an `issuer` that differs from the current authorization server, surface an error
+        # instead of silently sending another server's credentials (the spec's "SHOULD surface
+        # an error"; the TypeScript SDK raises `AuthorizationServerMismatchError` here).
+        # Re-registration is not an option for the `client_credentials` grant - the credentials
+        # are pre-registered, not DCR results - so the operator must update the stored credentials.
+        # Credentials without a recorded issuer keep working unchanged.
+        def ensure_client_credentials_issuer!(client_info, as_metadata:)
+          stored_issuer = client_info_required_value(client_info, "issuer")
+          return if stored_issuer.nil?
+          return if stored_issuer == as_metadata["issuer"]
+
+          raise AuthorizationError,
+            "Stored client credentials are bound to a different authorization server " \
+              "(stored issuer #{stored_issuer.inspect}, current #{as_metadata["issuer"].inspect}); " \
+              "refusing to send them to the current authorization server (SEP-2352)."
+        end
+
         # Exchanges the saved `refresh_token` for a fresh access token (RFC 6749 Section 6).
         # Re-discovers PRM and AS metadata so we always pick up a moved token endpoint, and re-runs the audience / issuer / security
         # checks before talking to it.
@@ -166,6 +193,7 @@ module MCP
           client_info = if have_stored_client_info
             # Pre-registered / DCR-issued `client_information` always wins: if the user picked an explicit identity,
             # do not silently swap it for the CIMD URL even when the AS also advertises CIMD support.
+            ensure_refreshable_client_information!(stored_client_info, as_metadata: as_metadata)
             stored_client_info
           elsif as_metadata["client_id_metadata_document_supported"] == true
             { "client_id" => @provider.client_id_metadata_document_url }
@@ -412,8 +440,8 @@ module MCP
         end
 
         def ensure_client_registered(as_metadata:)
-          existing = @provider.client_information
-          return existing if existing.is_a?(Hash) && client_info_required_value(existing, "client_id")
+          existing = stored_client_information_for(issuer: as_metadata["issuer"])
+          return existing if existing
 
           # Per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`,
           # if the authorization server advertises Client ID Metadata Document support and the provider has
@@ -462,7 +490,12 @@ module MCP
               "Dynamic client registration response is missing `client_id`."
           end
 
-          @provider.save_client_information(info)
+          # Per SEP-2352, persisted client credentials are keyed by the issuer identifier of
+          # the authorization server that minted them, so a later flow can detect an AS change and
+          # re-register instead of replaying another server's credentials. `issuer` is not an RFC 7591 response field;
+          # the SDK adds it to the opaque persisted hash.
+          @provider.save_client_information(info.merge("issuer" => as_metadata["issuer"]))
+
           info
         end
 
@@ -480,6 +513,60 @@ module MCP
           metadata.merge("application_type" => Discovery.infer_application_type(redirect_uris))
         end
 
+        # Returns the stored `client_information` when it may be used against the authorization server
+        # identified by `issuer`, applying SEP-2352's authorization server binding rules:
+        #
+        # - Credentials persisted with an `"issuer"` binding MUST NOT be reused against
+        #   a different authorization server. When the AS changed, the stale registration and its tokens
+        #   are discarded (tokens minted by the old AS are dead at the new one) and nil is returned so
+        #   the flow re-registers.
+        # - Stored credentials without an `"issuer"` binding (data persisted by an older SDK version,
+        #   or user-supplied pre-registered credentials) are bound to the current issuer on first use.
+        # - A CIMD `client_id` (an HTTPS URL) is portable across authorization servers, so it is reused
+        #   and re-bound instead of discarded.
+        #
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2352
+        def stored_client_information_for(issuer:)
+          existing = @provider.client_information
+          return unless existing.is_a?(Hash) && client_info_required_value(existing, "client_id")
+
+          stored_issuer = client_info_required_value(existing, "issuer")
+          return existing if stored_issuer == issuer
+          return rebind_client_information(existing, issuer: issuer) if stored_issuer.nil?
+
+          client_id = client_info_required_value(existing, "client_id")
+          return rebind_client_information(existing, issuer: issuer) if Discovery.client_id_metadata_document_url?(client_id)
+
+          @provider.save_client_information(nil)
+          @provider.clear_tokens!
+          nil
+        end
+
+        def rebind_client_information(info, issuer:)
+          rebound = info.merge("issuer" => issuer)
+          @provider.save_client_information(rebound)
+          rebound
+        end
+
+        # Per SEP-2352, stored client credentials are bound to the authorization server that issued them;
+        # refuse to replay another AS's credentials at this token endpoint. `HTTP#attempt_refresh` rescues
+        # the error and falls back to the full flow, which discards the stale registration and re-registers.
+        # Credentials without an `"issuer"` binding predate this check and are allowed through;
+        # CIMD `client_id`s are portable.
+        def ensure_refreshable_client_information!(client_info, as_metadata:)
+          stored_issuer = client_info_required_value(client_info, "issuer")
+          return if stored_issuer.nil?
+          return if stored_issuer == as_metadata["issuer"]
+
+          client_id = client_info_required_value(client_info, "client_id")
+          return if Discovery.client_id_metadata_document_url?(client_id)
+
+          raise AuthorizationError,
+            "Cannot refresh: stored client credentials were issued by a different authorization server " \
+              "(stored issuer #{stored_issuer.inspect}, current #{as_metadata["issuer"].inspect}); " \
+              "re-registration is required (SEP-2352)."
+        end
+
         # Reads `key` from a `client_information` hash that may use either string or
         # symbol keys, so users can persist the result of `JSON.parse` *or* a hand-built
         # `{ client_id:, client_secret: }` and have both work.
@@ -534,6 +621,43 @@ module MCP
           raise AuthorizationError, "#{label} #{url.inspect} is not a valid URI: #{e.message}."
         end
 
+        # Validates the RFC 9207 `iss` authorization response parameter against the issuer of the authorization server
+        # the flow is talking to, per SEP-2468 (mix-up attack mitigation in multi-IdP setups):
+        #
+        # - When the callback supplied a non-empty `iss`, it MUST equal the AS metadata `issuer` exactly (simple string comparison,
+        #   no normalization, per RFC 9207 Section 2.4); on mismatch the flow aborts before the authorization code is ever sent to
+        #   a token endpoint.
+        # - When the callback returned a 3-element `[code, state, iss]` whose `iss` is nil (asserting it inspected the authorization response
+        #   and found no `iss`) and the AS metadata advertises `authorization_response_iss_parameter_supported: true`, the missing parameter
+        #   is treated as an attack per RFC 9207 Section 2.4 and the flow aborts.
+        # - A legacy 2-element `[code, state]` callback skips the check: the caller never looked for `iss`, so its absence carries no signal.
+        #
+        # `as_metadata["issuer"]` has already been byte-compared against the discovery URL by `ensure_issuer_matches!`,
+        #  so it is the RFC 9207 anchor value. `iss` is not a secret; a plain `==` suffices.
+        #
+        # - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2468
+        # - https://www.rfc-editor.org/rfc/rfc9207
+        def validate_authorization_response_issuer!(as_metadata:, iss:, iss_provided:)
+          expected = as_metadata["issuer"]
+
+          if iss && !iss.to_s.empty?
+            return if iss.to_s == expected.to_s
+
+            raise AuthorizationError,
+              "Authorization response `iss` does not match the authorization server issuer " \
+                "(expected #{expected.inspect}, got #{iss.inspect}) (RFC 9207); " \
+                "refusing to exchange the authorization code."
+          end
+
+          return unless iss_provided
+          return unless as_metadata["authorization_response_iss_parameter_supported"] == true
+
+          raise AuthorizationError,
+            "Authorization server advertises `authorization_response_iss_parameter_supported` but " \
+              "the authorization response carried no `iss` parameter (RFC 9207 Section 2.4); " \
+              "refusing to exchange the authorization code."
+        end
+
         # Constant-time comparison for the OAuth `state` parameter to prevent timing-based discovery
         # of the expected value.
         # `OpenSSL.fixed_length_secure_compare` would be ideal, but it is not available on Ruby 2.7
@@ -681,7 +805,26 @@ module MCP
           client_secret = client_info_required_value(client_info, "client_secret")
           token_endpoint_auth_method = client_info_value(client_info, "token_endpoint_auth_method")
 
-          form = form.merge("client_id" => client_id)
+          form = if token_endpoint_auth_method == "private_key_jwt"
+            # RFC 7523 Section 2.2 JWT client assertion for the `private_key_jwt` method of
+            # the `io.modelcontextprotocol/oauth-client-credentials` extension (SEP-1046).
+            # The client identity travels in the assertion's `iss`/`sub` claims, so `client_id` is
+            # omitted from the body per RFC 7521 Section 4.2 (the `client_assertion` conveys the client identity).
+            # The audience is the issuer identifier that `ensure_issuer_matches!` already byte-validated.
+            unless @provider.respond_to?(:client_assertion)
+              raise AuthorizationError,
+                "token_endpoint_auth_method is private_key_jwt but the provider does not " \
+                  "implement `client_assertion(audience:)`."
+            end
+
+            form.merge(
+              "client_assertion_type" => JWTClientAssertion::ASSERTION_TYPE,
+              "client_assertion" => @provider.client_assertion(audience: as_metadata["issuer"]),
+            )
+          else
+            form.merge("client_id" => client_id)
+          end
+
           headers = {}
           if client_secret
             case token_endpoint_auth_method

data/lib/mcp/client/oauth/in_memory_storage.rb

@@ -12,7 +12,9 @@ module MCP
       # - `client_information`: the hash returned by Dynamic Client Registration
       #   or supplied as pre-registered credentials
       #   (`client_id`, optional `client_secret`, optional
-      #   `token_endpoint_auth_method`).
+      #   `token_endpoint_auth_method`). The SDK additionally stamps an `"issuer"` member
+      #   binding the credentials to the authorization server that issued them (SEP-2352);
+      #   custom storages should treat the hash as opaque and persist it as-is.
       #
       # This class keeps everything in process memory, so the credentials live
       # only for the lifetime of the Ruby process. Applications that need

data/lib/mcp/client/oauth/jwt_client_assertion.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "securerandom"
+
+module MCP
+  class Client
+    module OAuth
+      # Builds RFC 7523 Section 2.2 JWT client assertions for the `private_key_jwt`
+      # client authentication method used by the `client_credentials` grant
+      # (MCP extension `io.modelcontextprotocol/oauth-client-credentials`, SEP-1046).
+      #
+      # The JWS is assembled with openssl so the SDK stays free of a JWT gem dependency
+      # (the TypeScript and Python SDKs use jose and PyJWT for the same assertion).
+      # Claims follow SEP-1046 and RFC 7523: `iss` and `sub` carry the client_id,
+      # `aud` carries the authorization server's issuer identifier, plus `exp`, `iat`,
+      # and a unique `jti`.
+      #
+      # - https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1046
+      # - https://www.rfc-editor.org/rfc/rfc7523#section-2.2
+      module JWTClientAssertion
+        # Raised when `signing_algorithm` is not supported.
+        class UnsupportedAlgorithmError < ArgumentError; end
+
+        # Raised when the private key cannot be parsed or does not match
+        # the requested signing algorithm (e.g. an RSA key with ES256).
+        class InvalidKeyError < ArgumentError; end
+
+        # RFC 7523 Section 2.2 `client_assertion_type` value.
+        ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+        # Assertion lifetime in seconds; matches the TypeScript SDK's `jwtLifetimeSeconds`
+        # and the Python SDK's `lifetime_seconds` default.
+        DEFAULT_LIFETIME = 300
+
+        # ES256 produces a raw `r || s` JWS signature of two 32-byte integers.
+        ES256_COMPONENT_BYTES = 32
+        private_constant :ES256_COMPONENT_BYTES
+
+        SUPPORTED_ALGORITHMS = ["ES256", "RS256"].freeze
+
+        class << self
+          # Returns a signed compact-serialization JWT (`header.payload.signature`).
+          #
+          # @param client_id [String] The pre-registered OAuth client identifier.
+          # @param audience [String] The authorization server's issuer identifier.
+          # @param private_key [String, OpenSSL::PKey::PKey] PEM string (PKCS#8 or
+          #   traditional encoding) or an already-parsed key.
+          # @param signing_algorithm [String] `"ES256"` (prime256v1 EC key) or
+          #   `"RS256"` (RSA key).
+          # @param lifetime [Integer] Seconds until the `exp` claim expires.
+          def generate(client_id:, audience:, private_key:, signing_algorithm:, lifetime: DEFAULT_LIFETIME)
+            unless SUPPORTED_ALGORITHMS.include?(signing_algorithm)
+              raise UnsupportedAlgorithmError,
+                "signing_algorithm must be one of #{SUPPORTED_ALGORITHMS.inspect} (got #{signing_algorithm.inspect})."
+            end
+
+            key = parse_key(private_key)
+            validate_key!(key, signing_algorithm)
+
+            now = Time.now.to_i
+            header = { alg: signing_algorithm, typ: "JWT" }
+            claims = {
+              iss: client_id,
+              sub: client_id,
+              aud: audience,
+              exp: now + lifetime,
+              iat: now,
+              jti: SecureRandom.uuid,
+            }
+
+            signing_input = "#{base64url(JSON.generate(header))}.#{base64url(JSON.generate(claims))}"
+            "#{signing_input}.#{base64url(sign(key, signing_algorithm, signing_input))}"
+          end
+
+          private
+
+          def parse_key(private_key)
+            return private_key if private_key.is_a?(OpenSSL::PKey::PKey)
+
+            OpenSSL::PKey.read(private_key.to_s)
+          rescue OpenSSL::PKey::PKeyError => e
+            raise InvalidKeyError, "private_key could not be parsed as a PEM-encoded key: #{e.message}."
+          end
+
+          def validate_key!(key, signing_algorithm)
+            case signing_algorithm
+            when "ES256"
+              unless key.is_a?(OpenSSL::PKey::EC) && key.group.curve_name == "prime256v1"
+                raise InvalidKeyError, "ES256 requires an EC private key on the prime256v1 (P-256) curve."
+              end
+            when "RS256"
+              unless key.is_a?(OpenSSL::PKey::RSA)
+                raise InvalidKeyError, "RS256 requires an RSA private key."
+              end
+            end
+
+            return if key.private?
+
+            raise InvalidKeyError, "private_key must contain the private component to sign assertions."
+          end
+
+          def sign(key, signing_algorithm, signing_input)
+            der = key.sign(OpenSSL::Digest.new("SHA256"), signing_input)
+            return der unless signing_algorithm == "ES256"
+
+            ecdsa_der_to_raw(der)
+          end
+
+          # `OpenSSL::PKey::EC#sign` returns an ASN.1 DER `SEQUENCE { r, s }`,
+          # while JWS ES256 (RFC 7518 Section 3.4) requires the raw 64-byte
+          # `r || s` concatenation with each integer left-padded to 32 bytes.
+          def ecdsa_der_to_raw(der)
+            OpenSSL::ASN1.decode(der).value.map do |integer|
+              integer.value.to_s(16).rjust(ES256_COMPONENT_BYTES * 2, "0")
+            end.join.then { |hex| [hex].pack("H*") }
+          end
+
+          def base64url(data)
+            Base64.urlsafe_encode64(data, padding: false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mcp/client/oauth/provider.rb

@@ -21,15 +21,23 @@ module MCP
       # - `redirect_handler` - Callable invoked with the fully-built authorization
       #   URL (a `URI`). Implementations typically open the user's browser.
       # - `callback_handler` - Callable invoked after `redirect_handler`. Returns
-      #   `[code, state]` where `code` is the authorization code and `state` is
-      #   the `state` parameter received on the redirect URI.
+      #   `[code, state]` or `[code, state, iss]`, where `code` is the authorization code,
+      #   `state` is the `state` parameter received on the redirect URI, and `iss` is
+      #   the RFC 9207 `iss` parameter (or nil when the authorization response carried none).
+      #   Returning the 3-element form opts into SEP-2468 issuer validation: a present `iss`
+      #   must match the authorization server's issuer, and a nil `iss` is
+      #   rejected when the AS advertises `authorization_response_iss_parameter_supported`.
+      #   The 2-element form skips the check for backward compatibility.
       #
       # Optional keyword arguments:
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` does not specify one.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
-      #   an `InMemoryStorage`.
+      #   an `InMemoryStorage`. Persisted `client_information` is stamped with
+      #   an `"issuer"` member binding it to the authorization server that
+      #   issued it (SEP-2352); when the authorization server changes, the SDK discards
+      #   the stale registration and tokens and re-registers.
       # - `client_id_metadata_document_url` - URL where the client publishes its Client ID Metadata Document
       #   (`draft-ietf-oauth-client-id-metadata-document-00` and the MCP authorization specification).
       #   When the authorization server advertises `client_id_metadata_document_supported: true`,

data/lib/mcp/client/oauth.rb

@@ -5,6 +5,7 @@ require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"
 require_relative "oauth/pkce"
 require_relative "oauth/storage_backed_provider"
+require_relative "oauth/jwt_client_assertion"
 require_relative "oauth/provider"
 require_relative "oauth/client_credentials_provider"
 

data/lib/mcp/client/paginated_result.rb

@@ -4,10 +4,12 @@ module MCP
   class Client
     # Result objects returned by `list_tools`, `list_prompts`, `list_resources`, and `list_resource_templates`.
     # Each carries the page items, an optional opaque `next_cursor` string for continuing pagination,
-    # and an optional `meta` hash mirroring the MCP `_meta` response field.
-    ListToolsResult = Struct.new(:tools, :next_cursor, :meta, keyword_init: true)
-    ListPromptsResult = Struct.new(:prompts, :next_cursor, :meta, keyword_init: true)
-    ListResourcesResult = Struct.new(:resources, :next_cursor, :meta, keyword_init: true)
-    ListResourceTemplatesResult = Struct.new(:resource_templates, :next_cursor, :meta, keyword_init: true)
+    # an optional `meta` hash mirroring the MCP `_meta` response field, and the optional SEP-2549
+    # cache hints `ttl_ms` (freshness lifetime in milliseconds; 0 means do not cache) and
+    # `cache_scope` (`"public"` or `"private"`) mirroring the `ttlMs`/`cacheScope` response fields.
+    ListToolsResult = Struct.new(:tools, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
+    ListPromptsResult = Struct.new(:prompts, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
+    ListResourcesResult = Struct.new(:resources, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
+    ListResourceTemplatesResult = Struct.new(:resource_templates, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
   end
 end

data/lib/mcp/client/stdio.rb

@@ -259,7 +259,9 @@ module MCP
 
           parsed = JSON.parse(line.strip)
 
-          next unless parsed.key?("id")
+          # A JSON-RPC message is an object; skip a non-object frame (array or scalar)
+          # the same way as a frame without an id.
+          next unless parsed.is_a?(Hash) && parsed.key?("id")
 
           return parsed if parsed["id"] == request_id
         end

data/lib/mcp/client.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "client/elicitation"
 require_relative "client/oauth"
 require_relative "client/stdio"
 require_relative "client/http"
 require_relative "client/paginated_result"
 require_relative "client/tool"
+require_relative "result_type"
 
 module MCP
   class Client
@@ -29,11 +31,44 @@ module MCP
       end
     end
 
+    # Raised inside a server-to-client request handler (registered via `on_server_request`, e.g. `on_sampling`)
+    # to answer the request with a specific JSON-RPC error code instead of the default internal error.
+    # Mirrors the TypeScript SDK's `McpError` and the Python SDK's `ErrorData` return: for example,
+    # the sampling spec answers a rejected request with code `-1`.
+    # https://modelcontextprotocol.io/specification/2025-11-25/client/sampling
+    class ServerRequestError < StandardError
+      attr_reader :code
+
+      def initialize(message, code:)
+        super(message)
+        @code = code
+      end
+    end
+
     # Raised when a server response fails client-side validation, e.g., a success response
     # whose `result` field is missing or has the wrong type. This is distinct from a
     # server-returned JSON-RPC error, which is raised as `ServerError`.
     class ValidationError < StandardError; end
 
+    # Raised when a server answers with a SEP-2322 Multi Round-Trip `input_required` result instead of
+    # a final result. The result is not an error on the wire: it asks the client to fulfill the server's
+    # `inputRequests` (a map of id => `{ "method" => ..., "params" => ... }` request objects with
+    # `sampling/createMessage`, `roots/list`, or `elicitation/create` shapes) and re-issue
+    # the original request with `inputResponses` plus the echoed opaque `requestState`.
+    # This SDK does not yet drive that resume loop automatically; callers can inspect `input_requests`
+    # and respond manually.
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322
+    class InputRequiredError < StandardError
+      attr_reader :input_requests, :request_state, :result
+
+      def initialize(message, input_requests:, request_state: nil, result: nil)
+        super(message)
+        @input_requests = input_requests
+        @request_state = request_state
+        @result = result
+      end
+    end
+
     # Raised when the server responds 404 to a request containing a session ID,
     # indicating the session has expired. Inherits from `RequestHandlerError` for
     # backward compatibility with callers that rescue the generic error. Per spec,
@@ -134,7 +169,13 @@ module MCP
         )
       end
 
-      ListToolsResult.new(tools: tools, next_cursor: result["nextCursor"], meta: result["_meta"])
+      ListToolsResult.new(
+        tools: tools,
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
+      )
     end
 
     # Returns every tool available on the server. Iterates through all pages automatically
@@ -175,6 +216,8 @@ module MCP
         resources: result["resources"] || [],
         next_cursor: result["nextCursor"],
         meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
       )
     end
 
@@ -208,6 +251,8 @@ module MCP
         resource_templates: result["resourceTemplates"] || [],
         next_cursor: result["nextCursor"],
         meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
       )
     end
 
@@ -241,6 +286,8 @@ module MCP
         prompts: result["prompts"] || [],
         next_cursor: result["nextCursor"],
         meta: result["_meta"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
       )
     end
 
@@ -352,6 +399,30 @@ module MCP
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
 
+    # Registers a handler for `elicitation/create` requests the server sends while one of
+    # this client's requests is in flight. The handler receives the request `params`
+    # (message and `requestedSchema`, string keys) and must return an `ElicitResult`-shaped Hash:
+    # `{ action: "accept" | "decline" | "cancel", content: { ... } }`.
+    #
+    # Requires a transport that supports server-to-client requests (e.g. `MCP::Client::HTTP`);
+    # pass `capabilities: { elicitation: {} }` to `connect` so the server knows it may send them.
+    #
+    # @example Accept with schema defaults applied (SEP-1034)
+    #   client.on_elicitation do |params|
+    #     {
+    #       action: "accept",
+    #       content: MCP::Client::Elicitation.apply_defaults(params["requestedSchema"]),
+    #     }
+    #   end
+    # https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
+    def on_elicitation(&handler)
+      unless transport.respond_to?(:on_server_request)
+        raise ArgumentError, "The transport does not support server-to-client requests"
+      end
+
+      transport.on_server_request(Methods::ELICITATION_CREATE, &handler)
+    end
+
     # Sends a `ping` request to the server to verify the connection is alive.
     # Per the MCP spec, the server responds with an empty result.
     #
@@ -422,9 +493,26 @@ module MCP
         raise ServerError.new(error["message"], code: error["code"], data: error["data"])
       end
 
+      raise_on_input_required(response)
+
       response
     end
 
+    # Recognizes a SEP-2322 `input_required` result and raises rather than returning it as if it were a final result.
+    # Servers on stable protocol versions never emit `resultType`, so this is a no-op for them.
+    def raise_on_input_required(response)
+      result = response.is_a?(Hash) ? response["result"] : nil
+      return unless result.is_a?(Hash) && result["resultType"] == ResultType::INPUT_REQUIRED
+
+      raise InputRequiredError.new(
+        "Server returned `input_required`; this SDK does not yet resume multi-round-trip requests (SEP-2322). " \
+          "Inspect `input_requests` to respond manually.",
+        input_requests: result["inputRequests"] || {},
+        request_state: result["requestState"],
+        result: result,
+      )
+    end
+
     # Generates a fresh JSON-RPC request id for an outgoing request.
     # Ids are an internal concern: the public API never accepts or exposes them, and cancellation is driven through
     # an `MCP::Cancellation` token instead.

data/lib/mcp/error_codes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MCP
+  # MCP-specific JSON-RPC error codes, complementing the generic codes in `JsonRpcHandler::ErrorCode`.
+  #
+  # Both constants below are introduced by the stateless lifecycle of the MCP 2026-07-28 draft (SEP-2575):
+  # `UNSUPPORTED_PROTOCOL_VERSION` rejects a request whose `_meta`-carried protocol version the server does not
+  # support (`error.data: { supported: [...], requested: "..." }`), and `MISSING_REQUIRED_CLIENT_CAPABILITY`
+  # rejects a request that requires a client capability the request did not declare
+  # (`error.data: { requiredCapabilities: {...} }`). The SDK exports the vocabulary; it does not raise
+  # these codes itself yet.
+  #
+  # The values come from the spec's MCP-specific error code block, which is allocated sequentially from
+  # `-32020` toward `-32099`. `-32020` (`HEADER_MISMATCH`, SEP-2243) precedes the two codes defined here.
+  #
+  # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+  module ErrorCodes
+    MISSING_REQUIRED_CLIENT_CAPABILITY = -32021
+    UNSUPPORTED_PROTOCOL_VERSION = -32022
+  end
+end

data/lib/mcp/methods.rb

@@ -5,6 +5,8 @@ module MCP
     INITIALIZE = "initialize"
     PING = "ping"
     LOGGING_SET_LEVEL = "logging/setLevel"
+    # Sessionless capability discovery (MCP 2026-07-28 draft, SEP-2575).
+    SERVER_DISCOVER = "server/discover"
 
     PROMPTS_GET = "prompts/get"
     PROMPTS_LIST = "prompts/list"
@@ -81,7 +83,7 @@ module MCP
           require_capability!(method, capabilities, :sampling)
         when ELICITATION_CREATE
           require_capability!(method, capabilities, :elicitation)
-        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_ROOTS_LIST_CHANGED,
+        when INITIALIZE, PING, SERVER_DISCOVER, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_ROOTS_LIST_CHANGED,
              NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
           # No specific capability required.
         end