mcp 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08c2de444c55244db435a10ce7b9f9026d24158d47cadd6f89b917f42e09b534'
-  data.tar.gz: 6126a02c9adf92df07f22b323a0337f2abae9eb23c7bf014f1b7ef1ccbbf3a72
+  metadata.gz: 87f6233cbd083a14b47183b21558ee995c06953ef5bb8d9ea568eca8e69103de
+  data.tar.gz: 11697a1b6e71297211fac5ecf411ac381a064e66274ac9c9a9640087284859ad
 SHA512:
-  metadata.gz: 7318acb46d46e9c958115f95171f21b20c186ab32608770d443440e0202d29319b9384b11099ed69f136c3ba9146be39998e1a9a47a839fe506e07cddca0ad89
-  data.tar.gz: 3008f7f6061e0a2cd514d377ade38a03be1ed88d863fb268e50c9820ece43f585b7fcc801bc6c0ffcf78fab3a80af3397c20e497722a6821c55d6128d391d4fc
+  metadata.gz: ec9899cc307eb88706aded076b0e7be9bb2bdbf2fbf52c3d8f8f7a7ebe05dbb1da802ebfc8ea9bc1d5ecc18c361a2249488815c60175650203815a084aad9833
+  data.tar.gz: c43d95b541108f64ac594567e44f3de9e103f4f52c2c122ef0f0d90dcaa52b391b419c536cf4653c784299324a71c23c9bb7da9a7c4f9f69db87c2ab1d730871

data/lib/mcp/client/http.rb

@@ -902,15 +902,25 @@ module MCP
         MCP::Client::OAuth::Discovery.parse_www_authenticate(header)
       end
 
+      # A provider without a `callback_handler` finishes the authorization in the request that receives the redirect,
+      # not here, so there is nothing to retry with yet: the pending authorization surfaces as
+      # `Flow::AuthorizationPendingError`, and requests made after `Flow#finish!` pick up the stored tokens.
       def run_full_authorization_flow!(flow:, params:)
         # Use the URL snapshotted at `initialize` time so a post-construction
         # mutation of `@url` cannot redirect PRM/AS discovery and the authorize
         # URL to an attacker-controlled host.
-        flow.run!(
+        result = flow.run!(
           server_url: @oauth_server_url,
           resource_metadata_url: params["resource_metadata"],
           scope: params["scope"],
         )
+        return unless result == :redirect
+
+        raise MCP::Client::OAuth::Flow::AuthorizationPendingError.new(
+          "Authorization is pending: the user was sent to the authorization server, and the request can be retried " \
+            "once `MCP::Client::OAuth::Flow#finish!` completes the authorization with the redirect's query.",
+          authorization_url: flow.authorization_url,
+        )
       end
 
       # Tries to swap a saved `refresh_token` for a fresh access token. Returns truthy

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

@@ -83,6 +83,27 @@ module MCP
         # and `MCP::Client::HTTP` treats on a failed refresh as a reason to run the interactive flow.
         class DestinationMismatchError < ArgumentError; end
 
+        # Raised by `MCP::Client::HTTP` when a provider without a `callback_handler` has sent the user to the authorization server:
+        # the request cannot be retried until the application finishes the authorization with `finish!` in the request that
+        # receives the redirect. `authorization_url` is the URL handed to `redirect_handler`; it is kept out of the message,
+        # which may reach logs, because it carries the `state` that `finish!` looks the pending authorization up by.
+        # Deliberately outside `AuthorizationError`, which `MCP::Client::HTTP` treats on a failed refresh as a reason to run
+        # the interactive flow: this is the interactive flow waiting on the user, not a failure.
+        class AuthorizationPendingError < StandardError
+          attr_reader :authorization_url
+
+          def initialize(message = nil, authorization_url: nil)
+            super(message)
+            @authorization_url = authorization_url
+          end
+        end
+
+        # A `state` the SDK generates is 43 characters; a callback carrying a much longer one is refused before storage is asked.
+        CALLBACK_STATE_MAX_LENGTH = 128
+
+        UNKNOWN_PENDING_AUTHORIZATION_MESSAGE =
+          "Authorization callback `state` matches no pending authorization; it is unknown, already used, or expired."
+
         # Faraday middleware registered on the connection `build_http_client` assembles before the customizer
         # is invoked, so with the usual `use` it sits ahead of the customizer's middleware and sees the URL exactly
         # as the flow requested it, which it records on the request environment for `RequestedOriginGuard`.
@@ -189,13 +210,20 @@ module MCP
           end
         end
 
+        # The authorization URL the last `run!` handed to `redirect_handler` before returning `:redirect`, or `nil`.
+        attr_reader :authorization_url
+
         def initialize(provider:, http_client_factory: nil)
           @provider = provider
           @http_client_factory = http_client_factory || -> { default_http_client }
+          @authorization_url = nil
         end
 
         # Runs the full discovery, registration, authorization, and token exchange flow.
         # On success, persists tokens via the provider and returns `:authorized`.
+        # A provider without a `callback_handler` stops after the redirect instead: the flow saves
+        # a pending authorization in the provider's storage, keyed by `state`, and returns `:redirect`, leaving the code
+        # exchange to `finish!` in the request that receives the redirect.
         def run!(server_url:, resource_metadata_url: nil, scope: nil)
           # The `resource_metadata` URL ships in `WWW-Authenticate` and is the very
           # first thing we contact in the OAuth flow, so it has to clear the same
@@ -257,6 +285,20 @@ module MCP
             resource: resource,
           )
 
+          if @provider.callback_handler.nil?
+            save_pending_authorization(
+              state: state,
+              code_verifier: pkce[:code_verifier],
+              server_url: server_url,
+              resource: resource,
+              client_id: client_info_required_value(client_info, "client_id"),
+              as_metadata: as_metadata,
+            )
+            @authorization_url = authorization_url
+            @provider.redirect_handler.call(authorization_url)
+            return :redirect
+          end
+
           @provider.redirect_handler.call(authorization_url)
           callback_result = Array(@provider.callback_handler.call)
           code, returned_state, returned_iss = callback_result
@@ -449,6 +491,87 @@ module MCP
           :refreshed
         end
 
+        # Finishes an authorization that `run!` left pending, in the request that receives the redirect to `redirect_uri`,
+        # which may run in another process. `callback_params` is that redirect's whole query as a Hash (`code`, `state`, and,
+        # when present, `iss`, `error`, and `error_description`); passing all of it, rather than picking values out, is
+        # the caller's part of the `iss` check: an `iss` the caller drops reads as absent, and the flow cannot tell the difference.
+        #
+        # The pending authorization is looked up by `state` before any request is made, and it binds the rest of the exchange:
+        # the code is redeemed at the token endpoint recorded when the authorization began, with the client registration,
+        # `resource`, and `redirect_uri` used then, and without discovery running again, so the code reaches the authorization
+        # server the user was sent to (SEP-2352). The RFC 9207 `iss` is validated against the recorded issuer before the pending
+        # authorization is consumed, so a callback from another authorization server, as in a mix-up, is refused without
+        # consuming the entry the legitimate callback needs, and before the callback's `error` is read, since in a mix-up
+        # those parameters are the other server's. The check establishes only that a present `iss` matches the recorded issuer,
+        # not who sent the callback, and a callback without `iss` passes it unless the metadata advertises
+        # `authorization_response_iss_parameter_supported`: whoever holds the `state`, passes that check, and reaches
+        # the consume first takes the entry, and the legitimate callback then finds nothing.
+        #
+        # Past that check the pending authorization is consumed with `delete_pending_authorization`, which returns the entry
+        # it removed; only a callback that gets the entry back redeems the code, so of callbacks racing on the same `state`
+        # (a retried redirect, say), at most one does.
+        #
+        # Binding the callback to the user who started the authorization stays with the application: scoping `storage`
+        # to that user means a callback delivered to another user's session finds no pending authorization.
+        #
+        # On success, persists tokens via the provider and returns `:authorized`.
+        def finish!(server_url:, callback_params:)
+          unless provider_authorization_flow == :authorization_code && @provider.callback_handler.nil?
+            raise ArgumentError,
+              "finish! completes an authorization started by a provider without a callback_handler; " \
+                "this provider finishes its authorizations in `run!`."
+          end
+
+          state = callback_param(callback_params, "state")
+          raise AuthorizationError, "Authorization callback carried no `state`." unless state
+
+          pending = @provider.pending_authorization(state) if state.bytesize <= CALLBACK_STATE_MAX_LENGTH
+          raise AuthorizationError, UNKNOWN_PENDING_AUTHORIZATION_MESSAGE unless valid_pending_authorization?(pending)
+
+          if pending_authorization_expired?(pending)
+            @provider.delete_pending_authorization(state)
+            raise AuthorizationError, "The pending authorization has expired; start a new authorization."
+          end
+
+          unless safe_canonicalize_url(server_url, label: "MCP server URL") == pending["server_url"]
+            raise AuthorizationError, "The pending authorization was started for a different MCP server."
+          end
+
+          as_metadata = pending["authorization_server_metadata"]
+          # Checked when the authorization began, and checked again because the metadata has since made a round trip
+          # through the application's storage.
+          ensure_secure_endpoints!(as_metadata, server_url: pending["server_url"])
+
+          validate_authorization_response_issuer!(
+            as_metadata: as_metadata,
+            iss: callback_param(callback_params, "iss"),
+            iss_provided: true,
+          )
+
+          # The read above and this delete are separate calls, so the storage's atomic delete is what decides
+          # which of two concurrent callbacks carrying this `state` proceeds.
+          consumed = @provider.delete_pending_authorization(state)
+          raise AuthorizationError, UNKNOWN_PENDING_AUTHORIZATION_MESSAGE unless valid_pending_authorization?(consumed)
+
+          error = callback_param(callback_params, "error")
+          raise authorization_response_error(error, callback_param(callback_params, "error_description")) if error
+
+          code = callback_param(callback_params, "code")
+          raise AuthorizationError, "Authorization callback carried no authorization code." unless code
+
+          tokens = exchange_authorization_code(
+            as_metadata: as_metadata,
+            client_info: pending_client_information(pending, as_metadata: as_metadata),
+            code: code,
+            code_verifier: pending["code_verifier"],
+            resource: pending["resource"],
+            redirect_uri: pending["redirect_uri"],
+          )
+
+          save_tokens_issued_by(tokens, as_metadata: as_metadata)
+          :authorized
+        end
+
         private
 
         def read_token(key)
@@ -1096,6 +1219,89 @@ module MCP
           result.zero?
         end
 
+        def provider_pending_authorization_max_age
+          return Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE unless @provider.respond_to?(:pending_authorization_max_age)
+
+          @provider.pending_authorization_max_age
+        end
+
+        # Records what `finish!` needs to redeem the code exactly as this authorization began: the PKCE verifier, the MCP server,
+        # the `resource` and `redirect_uri` sent, the client identity used, and the authorization server metadata already validated.
+        # The client secret is not copied: `finish!` reads the registration from storage and requires the same `client_id`.
+        # Every value is JSON-compatible, so storage can serialize the entry as-is.
+        def save_pending_authorization(state:, code_verifier:, server_url:, resource:, client_id:, as_metadata:)
+          @provider.save_pending_authorization(
+            state,
+            {
+              "code_verifier" => code_verifier,
+              "server_url" => safe_canonicalize_url(server_url, label: "MCP server URL"),
+              "resource" => resource,
+              "redirect_uri" => @provider.redirect_uri,
+              "client_id" => client_id,
+              "authorization_server_metadata" => as_metadata,
+              "created_at" => Time.now.to_i,
+            },
+          )
+        end
+
+        def valid_pending_authorization?(pending)
+          return false unless pending.is_a?(Hash)
+          return false unless ["code_verifier", "server_url", "redirect_uri", "client_id"].all? { |key| non_empty_string?(pending[key]) }
+          return false unless pending["resource"].nil? || non_empty_string?(pending["resource"])
+
+          pending["authorization_server_metadata"].is_a?(Hash) && pending["created_at"].is_a?(Integer)
+        end
+
+        def pending_authorization_expired?(pending)
+          Time.now.to_i - pending["created_at"] > provider_pending_authorization_max_age
+        end
+
+        # The registration the authorization began with. A stored registration is used only while it still carries
+        # that `client_id` and is bound to the recorded authorization server; a Client ID Metadata Document URL,
+        # which is never stored, is used again while the recorded metadata advertises support for it.
+        def pending_client_information(pending, as_metadata:)
+          client_id = pending["client_id"]
+
+          stored = @provider.client_information
+          if stored.is_a?(Hash) &&
+              client_info_required_value(stored, "client_id") == client_id &&
+              client_info_required_value(stored, "issuer") == as_metadata["issuer"]
+            return stored
+          end
+
+          if client_id == provider_client_id_metadata_document_url && as_metadata["client_id_metadata_document_supported"] == true
+            return { "client_id" => client_id }
+          end
+
+          raise AuthorizationError, "The client registration changed after the authorization began; start a new authorization."
+        end
+
+        # Reads one parameter of an authorization response. Only a non-empty String counts: a repeated parameter that
+        # a framework delivers as an Array, or an empty value, is treated as absent.
+        def callback_param(params, key)
+          return unless params.is_a?(Hash)
+
+          value = params[key] || params[key.to_sym]
+          non_empty_string?(value) ? value : nil
+        end
+
+        def non_empty_string?(value)
+          value.is_a?(String) && !value.empty?
+        end
+
+        # An RFC 6749 Section 4.1.2.1 error response, reported with the bounds a token endpoint error gets.
+        # Reached only after the `iss` check, so any `iss` beside the values matched the recorded issuer; that does not
+        # prove who sent them, and they are text the sender chose, so they are cut to a bounded length and confined to
+        # the printable ASCII the RFC permits.
+        def authorization_response_error(error, description)
+          error = bounded_diagnostic(error, limit: TOKEN_ENDPOINT_ERROR_MAX_LENGTH)
+          description = bounded_diagnostic(description, limit: TOKEN_ENDPOINT_ERROR_DESCRIPTION_MAX_LENGTH)
+          message = "The authorization server returned an error to the authorization callback."
+          message += " #{[error, description].compact.join(": ")}" if error || description
+
+          AuthorizationError.new(message, error: error, error_description: description)
+        end
+
         # Per MCP 2025-11-25 Authorization and the TS/Python SDKs, scope resolution
         # prefers the `WWW-Authenticate` challenge first, then `scopes_supported`
         # from the Protected Resource Metadata, and falls back to a provider-supplied
@@ -1233,11 +1439,11 @@ module MCP
           uri
         end
 
-        def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:)
+        def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:, redirect_uri: @provider.redirect_uri)
           form = {
             "grant_type" => "authorization_code",
             "code" => code,
-            "redirect_uri" => @provider.redirect_uri,
+            "redirect_uri" => redirect_uri,
             "code_verifier" => code_verifier,
           }
           form["resource"] = resource if resource

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

@@ -16,6 +16,17 @@ module MCP
       #   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.
       #
+      # A provider without a `callback_handler` also keeps each pending authorization here, keyed by its `state`,
+      # between the request that sends the user to the authorization server and the request that receives
+      # the redirect (`save_pending_authorization(state, pending)`, `pending_authorization(state)`,
+      # `delete_pending_authorization(state)`). A pending authorization holds the PKCE verifier, so custom storages
+      # should treat it as a secret and persist it as-is. `Flow#finish!` touches only the entry its callback's `state`
+      # names, so an authorization the user never finished stays until the storage drops it: this class drops entries
+      # older than `pending_authorization_max_age` the next time one is saved, and a custom storage should expire them,
+      # with a TTL of that age. `delete_pending_authorization` must remove the entry and return it in one atomic step
+      # (`Hash#delete` under a mutex here; `GETDEL` in Redis, `DELETE ... RETURNING` in SQL), returning `nil` when
+      # there was none: the flow redeems the code only when it gets the entry back.
+      #
       # This class keeps everything in process memory, so the credentials live
       # only for the lifetime of the Ruby process. Applications that need
       # persistence across restarts should supply a custom object responding to
@@ -24,12 +35,25 @@ module MCP
       # `Provider.new(storage: ...)`. The shape mirrors Python SDK's
       # `TokenStorage` Protocol; TypeScript's `OAuthClientProvider` rolls
       # the same responsibilities into a single object.
+      # A web application may receive the redirect in another process, so pending authorizations
+      # need shared storage.
       class InMemoryStorage
         attr_accessor :tokens, :client_information
 
-        def initialize
+        # @param pending_authorization_max_age [Integer] seconds after which a pending authorization that was
+        #   never finished is dropped from this storage, at its next save. `Provider.new` passes its own
+        #   `pending_authorization_max_age` when it builds the default storage, so the two ages agree; a storage built
+        #   by hand defaults to `Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
+        def initialize(pending_authorization_max_age: Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE)
+          unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
+            raise ArgumentError, "pending_authorization_max_age must be a positive Integer number of seconds (got #{pending_authorization_max_age.inspect})."
+          end
+
           @tokens = nil
           @client_information = nil
+          @pending_authorizations = {}
+          @pending_authorization_max_age = pending_authorization_max_age
+          @pending_authorizations_mutex = Mutex.new
         end
 
         def save_tokens(tokens)
@@ -39,6 +63,55 @@ module MCP
         def save_client_information(info)
           @client_information = info
         end
+
+        # Drops every pending authorization older than `pending_authorization_max_age` before saving the new one.
+        # The flow refuses such an entry when it is looked up, but only a callback carrying its `state` looks it up,
+        # and an authorization the user abandoned never gets one; every `401` a provider without a `callback_handler` meets
+        # starts another, so without this the entries, each holding the verifier and the authorization server metadata,
+        # would accumulate for the life of the process.
+        def save_pending_authorization(state, pending)
+          @pending_authorizations_mutex.synchronize do
+            drop_expired_pending_authorizations
+            @pending_authorizations[state] = pending
+          end
+        end
+
+        def pending_authorization(state)
+          @pending_authorizations_mutex.synchronize { @pending_authorizations[state] }
+        end
+
+        # The mutex is what makes the removal and the return one step on every Ruby implementation: `Hash#delete`
+        # alone is atomic only where a global interpreter lock serializes it, and `Flow#finish!` relies on exactly
+        # one of two callbacks racing on the same `state` getting the entry back.
+        def delete_pending_authorization(state)
+          @pending_authorizations_mutex.synchronize { @pending_authorizations.delete(state) }
+        end
+
+        # Every hash this storage holds may carry a secret (an access token, a client secret, a PKCE verifier),
+        # and `inspect` is what error reporters and consoles print an object with, so it shows only whether each is present.
+        def inspect
+          pending_count = @pending_authorizations_mutex.synchronize { @pending_authorizations.size }
+
+          "#<#{self.class.name} tokens=#{present_or_nil(@tokens)} client_information=#{present_or_nil(@client_information)} pending_authorizations=#{pending_count}>"
+        end
+
+        private
+
+        # An entry's age is read from the Integer `created_at` the flow records when it saves the entry; an entry without one,
+        # which the flow never writes, is left alone.
+        def drop_expired_pending_authorizations
+          now = Time.now.to_i
+
+          @pending_authorizations.delete_if do |_state, pending|
+            created_at = pending.is_a?(Hash) ? pending["created_at"] : nil
+
+            created_at.is_a?(Integer) && now - created_at > @pending_authorization_max_age
+          end
+        end
+
+        def present_or_nil(value)
+          value.nil? ? "nil" : "[present]"
+        end
       end
     end
   end

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

@@ -20,6 +20,8 @@ module MCP
       #   request. Must be one of `redirect_uris` in `client_metadata`.
       # - `redirect_handler` - Callable invoked with the fully-built authorization
       #   URL (a `URI`). Implementations typically open the user's browser.
+      #
+      # Optional keyword arguments:
       # - `callback_handler` - Callable invoked after `redirect_handler`. Returns
       #   `[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
@@ -28,8 +30,11 @@ module MCP
       #   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:
+      #   Omit it when the redirect arrives in a later request, as it does in a web application:
+      #   the flow then stops after `redirect_handler` with a pending authorization saved in `storage`,
+      #   and the request that receives the redirect finishes it with `Flow#finish!`.
+      # - `pending_authorization_max_age` - Seconds a pending authorization stays redeemable, counted from the moment
+      #   `run!` saves it, when `callback_handler` is omitted. Defaults to `DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
       # - `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)`,
@@ -38,6 +43,10 @@ module MCP
       #   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.
+      #   Without `callback_handler`, it must also respond to `save_pending_authorization(state, pending)`,
+      #   `pending_authorization(state)`, and `delete_pending_authorization(state)`; the last must remove the entry
+      #   and return it atomically, returning `nil` when there was none, and the storage should expire entries
+      #   older than `pending_authorization_max_age`, as `InMemoryStorage` does.
       # - `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`,
@@ -78,25 +87,45 @@ module MCP
         # applies and the value must unambiguously identify the document.
         class InvalidClientIDMetadataDocumentURLError < ArgumentError; end
 
+        # Raised when `Provider#initialize` is called without `callback_handler` and with a `storage`
+        # that cannot hold a pending authorization between the request that sends the user to the authorization server
+        # and the request that receives the redirect.
+        class PendingAuthorizationStorageError < ArgumentError; end
+
+        # Seconds a pending authorization stays redeemable, counted from the moment `run!` saves it, when the provider has
+        # no `callback_handler`; long enough for a user to sign in and consent at the authorization server. It is also
+        # the age past which `InMemoryStorage` drops an authorization that was never finished, at its next save, so that
+        # an abandoned one does not keep its PKCE verifier in memory for the life of the process; a custom storage should
+        # expire entries at the same age.
+        DEFAULT_PENDING_AUTHORIZATION_MAX_AGE = 600
+
+        PENDING_AUTHORIZATION_STORAGE_METHODS = [
+          :save_pending_authorization,
+          :pending_authorization,
+          :delete_pending_authorization,
+        ].freeze
+
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
           :storage,
           :redirect_handler,
           :callback_handler,
-          :client_id_metadata_document_url
+          :client_id_metadata_document_url,
+          :pending_authorization_max_age
 
         def initialize(
           client_metadata:,
           redirect_uri:,
           redirect_handler:,
-          callback_handler:,
+          callback_handler: nil,
           scope: nil,
           storage: nil,
           client_id_metadata_document_url: nil,
           authorization_request_validator: nil,
           token_request_params: nil,
-          http_client_customizer: nil
+          http_client_customizer: nil,
+          pending_authorization_max_age: DEFAULT_PENDING_AUTHORIZATION_MAX_AGE
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -120,16 +149,33 @@ module MCP
 
           http_client_customizer = validated_http_client_customizer(http_client_customizer)
 
+          unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
+            raise ArgumentError, "pending_authorization_max_age must be a positive Integer number of seconds (got #{pending_authorization_max_age.inspect})."
+          end
+
+          # The default storage drops abandoned pending authorizations at the same age the flow stops redeeming them.
+          storage ||= InMemoryStorage.new(pending_authorization_max_age: pending_authorization_max_age)
+
+          if callback_handler.nil?
+            missing = PENDING_AUTHORIZATION_STORAGE_METHODS.reject { |method| storage.respond_to?(method) }
+            unless missing.empty?
+              raise PendingAuthorizationStorageError,
+                "Without a callback_handler the authorization finishes in a later request, so storage must also respond to " \
+                  "#{missing.join(", ")} (#{storage.class} does not)."
+            end
+          end
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
-          @storage = storage || InMemoryStorage.new
+          @storage = storage
           @client_id_metadata_document_url = client_id_metadata_document_url
           @authorization_request_validator = authorization_request_validator
           @token_request_params = frozen_token_request_params(token_request_params)
           @http_client_customizer = http_client_customizer
+          @pending_authorization_max_age = pending_authorization_max_age
         end
 
         # Identifies the OAuth flow this provider drives.
@@ -138,6 +184,20 @@ module MCP
         def authorization_flow
           :authorization_code
         end
+
+        def save_pending_authorization(state, pending)
+          @storage.save_pending_authorization(state, pending)
+        end
+
+        def pending_authorization(state)
+          @storage.pending_authorization(state)
+        end
+
+        # Returns the entry the storage removed, or `nil`. `Flow#finish!` redeems the code only when it gets
+        # the entry back, so of two callbacks racing on the same `state`, only one can.
+        def delete_pending_authorization(state)
+          @storage.delete_pending_authorization(state)
+        end
       end
     end
   end

data/lib/mcp/icon.rb

@@ -9,9 +9,70 @@ module MCP
   # is not judged: `src` may be any non-empty `String` (the schema types it as a URI, which an empty `String`
   # is not, and the specification allows an HTTP/HTTPS URL or a `data:` URI), and a size may be any `String`
   # (the specification expects `WxH` or `"any"`).
+  #
+  # Wherever an `Icon` is accepted (`Server.new(icons:)` and the `icons` of a tool, prompt, resource, or resource template),
+  # a Hash is accepted too and converted through `Icon.from`, so it is checked the same way.
   class Icon
     SUPPORTED_THEMES = ["light", "dark"].freeze
 
+    # The keys `from` accepts in a Hash: the keyword names of `new` and the wire name `mimeType`,
+    # as Symbols or Strings.
+    HASH_KEYWORDS = {
+      "src" => :src,
+      "mimeType" => :mime_type,
+      "mime_type" => :mime_type,
+      "sizes" => :sizes,
+      "theme" => :theme,
+    }.freeze
+    private_constant :HASH_KEYWORDS
+
+    class << self
+      # Returns `value` when it is already an `Icon`, builds one from a Hash, and refuses anything else.
+      def from(value)
+        return value if value.is_a?(Icon)
+
+        unless value.is_a?(Hash)
+          raise ArgumentError, "An icon must be an MCP::Icon or a Hash (got #{value.class})."
+        end
+
+        keywords = {}
+        value.each do |key, member|
+          unless key.is_a?(Symbol) || key.is_a?(String)
+            raise ArgumentError, "An icon Hash key must be a Symbol or a String (got #{key.class})."
+          end
+
+          keyword = HASH_KEYWORDS[key.to_s]
+          unless keyword
+            raise ArgumentError, "An icon Hash may only hold src, mimeType (or mime_type), sizes, and theme (got #{key.inspect})."
+          end
+          raise ArgumentError, "An icon Hash gives #{keyword} twice." if keywords.key?(keyword)
+
+          keywords[keyword] = member
+        end
+
+        new(**keywords)
+      end
+
+      # Converts the `icons` argument of a server, tool, prompt, resource, or resource template: `nil` stays `nil`,
+      # each element of an Array goes through `from` into a frozen Array, and anything else is refused.
+      # The frozen Array keeps a later `<<` on a reader from adding an element these checks never saw.
+      def from_list(value)
+        return if value.nil?
+
+        unless value.is_a?(Array)
+          raise ArgumentError, "icons must be nil or an Array of MCP::Icon or Hash (got #{value.class})."
+        end
+
+        icons = value.each_with_index.map do |icon, index|
+          from(icon)
+        rescue ArgumentError => e
+          raise ArgumentError, "icons[#{index}]: #{e.message}"
+        end
+
+        icons.freeze
+      end
+    end
+
     attr_reader :mime_type, :sizes, :src, :theme
 
     def initialize(mime_type: nil, sizes: nil, src:, theme: nil)

data/lib/mcp/prompt.rb

@@ -72,7 +72,7 @@ module MCP
         if value == NOT_SET
           @icons_value
         else
-          @icons_value = value
+          @icons_value = Icon.from_list(value)
         end
       end
 

data/lib/mcp/resource.rb

@@ -88,7 +88,7 @@ module MCP
         if value == NOT_SET
           @icons_value
         else
-          @icons_value = value
+          @icons_value = Icon.from_list(value)
         end
       end
 
@@ -147,7 +147,7 @@ module MCP
       @name = name
       @title = title
       @description = description
-      @icons = icons
+      @icons = Icon.from_list(icons)
       @mime_type = mime_type
       @annotations = annotations
       @size = size

data/lib/mcp/resource_template.rb

@@ -89,7 +89,7 @@ module MCP
         if value == NOT_SET
           @icons_value
         else
-          @icons_value = value
+          @icons_value = Icon.from_list(value)
         end
       end
 
@@ -158,7 +158,7 @@ module MCP
       @name = name
       @title = title
       @description = description
-      @icons = icons
+      @icons = Icon.from_list(icons)
       @mime_type = mime_type
       @annotations = annotations
       @meta = meta

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 require_relative "../../result_type"
 require_relative "../../transport"
 
@@ -48,6 +49,20 @@ module MCP
         # pass `max_listen_subscriptions: nil` to opt out.
         DEFAULT_MAX_LISTEN_SUBSCRIPTIONS = 1_000
 
+        # Bound on the bytes of resource URIs one `subscriptions/listen` request may name in `resourceSubscriptions`
+        # (the sum of their byte lengths after duplicates are dropped). The URIs are held for the life of the stream,
+        # so without a bound each stream could retain a request body's worth of URIs and the retained total would be
+        # `max_listen_subscriptions` times `max_request_bytes`. 64 KiB names about a thousand ordinary URIs;
+        # pass `max_resource_subscription_bytes: nil` to opt out. The specification sets no limit, nor do the TypeScript
+        # and Python SDKs; this is the same kind of local safety limit as `max_request_bytes`.
+        DEFAULT_MAX_RESOURCE_SUBSCRIPTION_BYTES = 64 * 1024
+
+        # Bound on the number of distinct resource URIs one `subscriptions/listen` request may name. A byte bound does
+        # not tightly bound the memory a stream keeps, since each retained URI carries a fixed per-object cost however
+        # short it is, so the count is bounded as well. Like `MAX_JSON_NESTING`, it is a structural limit applied
+        # whatever `max_resource_subscription_bytes` is, including `nil`.
+        MAX_RESOURCE_SUBSCRIPTION_URIS = 1_024
+
         # 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
@@ -67,14 +82,27 @@ module MCP
         # 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
-        # fits a typical JSON-RPC request (a 4 MiB JSON string decodes to ~3 MiB of base64
-        # payload); raise `max_request_bytes:` for unusually large payloads. Matches the
-        # TypeScript SDK's 4 MB default.
+        # 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 fits
+        # a typical JSON-RPC request (a 4 MiB JSON string decodes to ~3 MiB of base64 payload); raise `max_request_bytes:`
+        # for unusually large payloads. Matches the TypeScript SDK's 4 MB default.
         DEFAULT_MAX_REQUEST_BYTES = 4 * 1024 * 1024
 
+        # Bound on the body of an `initialize` request in stateful mode. Its `clientInfo` and `capabilities` are
+        # kept for the life of the session, so without a bound of its own each session could retain a whole
+        # `max_request_bytes` body and the retained total would be `max_sessions` times that. An ordinary
+        # `initialize` is under 2 KiB; 64 KiB leaves room for large `experimental` capabilities. Pass
+        # `max_initialize_request_bytes: nil` to opt out. The TypeScript and Python SDKs keep the initialize
+        # data whole with no bound of their own; this is the same kind of local safety limit as `max_request_bytes`.
+        DEFAULT_MAX_INITIALIZE_REQUEST_BYTES = 64 * 1024
+
+        # Bound on the number of JSON values (objects, arrays, keys, and scalars) in the `params` of an `initialize`
+        # request in stateful mode. A byte bound alone does not tightly bound the memory a session keeps: a body of
+        # many small values parses into far more objects than its size suggests, so the parsed structure is bounded
+        # as well. Like `MAX_JSON_NESTING`, it is a structural limit applied whatever `max_initialize_request_bytes`
+        # is, including `nil`. An ordinary `initialize` holds a few dozen values.
+        MAX_INITIALIZE_PARAMS_VALUES = 1_024
+
         # Conservative bound on JSON nesting depth, so a deeply nested body cannot exhaust
         # the stack or amplify parse cost (complements the byte cap).
         MAX_JSON_NESTING = 64
@@ -122,9 +150,19 @@ 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_initialize_request_bytes [Integer, nil] upper bound in bytes on the body of an `initialize`
+        #   request in stateful mode, whose `clientInfo` and `capabilities` the session keeps; a larger one is
+        #   rejected with HTTP 413 before any session is created. Defaults to `DEFAULT_MAX_INITIALIZE_REQUEST_BYTES`
+        #   (64 KiB), and `nil` disables this bound, leaving `max_request_bytes` as the only cap on the body; `params`
+        #   holding more than `MAX_INITIALIZE_PARAMS_VALUES` JSON values are rejected the same way either way.
+        #   Neither applies in stateless mode, which retains nothing.
         # @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 max_resource_subscription_bytes [Integer, nil] bound on the total byte length of the distinct
+        #   resource URIs one `subscriptions/listen` request names in `resourceSubscriptions`; a request over
+        #   the bound is rejected with HTTP 400 and JSON-RPC `-32602`.
+        #   Defaults to `DEFAULT_MAX_RESOURCE_SUBSCRIPTION_BYTES` (64 KiB), and `nil` disables the bound.
         # @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
@@ -149,7 +187,9 @@ module MCP
           dns_rebinding_protection: true,
           session_request_validator: nil,
           max_request_bytes: DEFAULT_MAX_REQUEST_BYTES,
+          max_initialize_request_bytes: DEFAULT_MAX_INITIALIZE_REQUEST_BYTES,
           max_listen_subscriptions: DEFAULT_MAX_LISTEN_SUBSCRIPTIONS,
+          max_resource_subscription_bytes: DEFAULT_MAX_RESOURCE_SUBSCRIPTION_BYTES,
           listen_keepalive_interval: DEFAULT_LISTEN_KEEPALIVE_INTERVAL,
           serve_subscriptions_listen: true,
           server_to_client_request_timeout: DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT
@@ -170,8 +210,9 @@ module MCP
           @pending_responses = {}
 
           # Maps a key the transport mints for each `subscriptions/listen` stream to
-          # `{ request_id: listen_request_id, stream: stream_object, filter: honored_subscription_filter, active: boolean,
-          # write_mutex: Mutex, keepalive_wakeup: ConditionVariable }` (SEP-2575). The request id is the client's,
+          # `{ request_id: listen_request_id, stream: stream_object, filter: honored_list_changed_flags,
+          # resource_uris: Set_of_honored_resource_uris, active: boolean, write_mutex: Mutex,
+          # keepalive_wakeup: ConditionVariable }` (SEP-2575). The request id is the client's,
           # unique only among that client's own in-flight requests, so it stamps `subscriptionId` but cannot serve as the key:
           # two clients may pick the same one. Whoever removes an entry signals `keepalive_wakeup` under `@mutex`,
           # so the stream's keepalive thread ends with its slot instead of sleeping out its interval.
@@ -212,12 +253,25 @@ module MCP
 
           @max_request_bytes = max_request_bytes
 
+          if !max_initialize_request_bytes.nil? && !(max_initialize_request_bytes.is_a?(Integer) && max_initialize_request_bytes > 0)
+            raise ArgumentError, "max_initialize_request_bytes must be a positive Integer or nil"
+          end
+
+          # The bound guards what stateful sessions retain; stateless mode keeps none.
+          @max_initialize_request_bytes = stateless ? nil : max_initialize_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 !max_resource_subscription_bytes.nil? && !(max_resource_subscription_bytes.is_a?(Integer) && max_resource_subscription_bytes > 0)
+            raise ArgumentError, "max_resource_subscription_bytes must be a positive Integer or nil"
+          end
+
+          @max_resource_subscription_bytes = max_resource_subscription_bytes
+
           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
@@ -850,6 +904,14 @@ module MCP
             return invalid_request_response("Invalid Request: subscriptions/listen requires an id")
           end
 
+          # The id is echoed in every message of the stream, so one that cannot be written back as JSON
+          # (a String holding bytes that are not valid UTF-8 parses, but does not generate) is refused here,
+          # while the refusal can still answer with a null id, rather than surfacing as a failed write after
+          # the stream has been registered.
+          unless json_encodable?(request_id)
+            return invalid_request_response("Invalid Request: subscriptions/listen id must be valid UTF-8")
+          end
+
           begin
             if RequestEnvelope.modern?(params)
               RequestEnvelope.parse!(params, request: params)
@@ -876,6 +938,15 @@ module MCP
             )
           end
 
+          if (problem = resource_subscriptions_problem(filter))
+            return json_rpc_error_response(
+              status: 400,
+              code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+              message: "Invalid params: subscriptions/listen #{problem}",
+              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.
@@ -883,7 +954,43 @@ module MCP
             return too_many_listen_subscriptions_response(request_id)
           end
 
-          [200, SSE_HEADERS.dup, listen_sse_body(request_id, honored_filter(filter))]
+          honored = honored_filter(filter)
+
+          # The acknowledgement echoes the honored filter, whose resource URIs are client-supplied strings,
+          # so it is encoded before the stream is committed to: a URI that cannot be written as JSON is
+          # refused with a 400 instead of failing the first write after the stream was registered.
+          unless (acknowledgement = listen_acknowledgement_json(request_id, honored))
+            return json_rpc_error_response(
+              status: 400,
+              code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+              message: "Invalid params: subscriptions/listen `notifications` must be valid UTF-8",
+              id: request_id,
+            )
+          end
+
+          [200, SSE_HEADERS.dup, listen_sse_body(request_id, honored, acknowledgement)]
+        end
+
+        # The `notifications/subscriptions/acknowledged` frame for a listen stream as JSON, or `nil` when
+        # the request id or the honored filter holds a string JSON cannot encode.
+        def listen_acknowledgement_json(request_id, honored)
+          {
+            jsonrpc: "2.0",
+            method: Methods::NOTIFICATIONS_SUBSCRIPTIONS_ACKNOWLEDGED,
+            params: {
+              notifications: honored,
+              _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id },
+            },
+          }.to_json
+        rescue JSON::GeneratorError
+          nil
+        end
+
+        def json_encodable?(value)
+          value.to_json
+          true
+        rescue JSON::GeneratorError
+          false
         end
 
         def listen_subscriptions_full?
@@ -942,14 +1049,22 @@ module MCP
         # The entry is keyed by an identifier minted here, not by the request id: that id is unique only among
         # the requesting client's own in-flight requests, and two clients that pick the same one must each get
         # their stream, stamped with the id they sent.
-        def listen_sse_body(request_id, honored)
+        def listen_sse_body(request_id, honored, acknowledgement)
           ListenStreamBody.new do |stream|
             subscription_key = SecureRandom.uuid
             subscription = nil
+            # The entry keeps the list-changed flags of the honored filter and the URIs as a frozen Set, both built ahead of the registry lock:
+            # delivery looks each notification's URI up in constant time, so neither the matching cost nor the lock hold grows with
+            # the number of URIs a stream named. The entry does not keep the Array the acknowledgement echoes; that one lives only as long as
+            # the host keeps this response body.
+            entry_filter = honored.reject { |name, _value| name == :resourceSubscriptions }
+            resource_uris = Set.new(honored[:resourceSubscriptions] || []).freeze
+
             @mutex.synchronize do
               unless @max_listen_subscriptions && @listen_subscriptions.size >= @max_listen_subscriptions
                 subscription = {
-                  request_id: request_id, stream: stream, filter: honored, active: false, write_mutex: Mutex.new, keepalive_wakeup: ConditionVariable.new
+                  request_id: request_id, stream: stream, filter: entry_filter, resource_uris: resource_uris, active: false,
+                  write_mutex: Mutex.new, keepalive_wakeup: ConditionVariable.new,
                 }
                 @listen_subscriptions[subscription_key] = subscription
               end
@@ -958,15 +1073,6 @@ module MCP
             if subscription.nil?
               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
                 acknowledged = subscription[:write_mutex].synchronize do
                   next false if subscription[:closed]
@@ -987,11 +1093,11 @@ module MCP
                 if acknowledged
                   start_listen_keepalive_thread(subscription_key, request_id)
                 else
-                  close_stream_safely(stream)
+                  close_removed_listen_stream(subscription)
                 end
               rescue *STREAM_WRITE_ERRORS
                 remove_listen_subscription(subscription_key)
-                close_stream_safely(stream)
+                close_removed_listen_stream(subscription)
               end
             end
           end
@@ -1032,11 +1138,9 @@ module MCP
             # removed the entry already, and the report should still name the stream.
             MCP.configuration.exception_reporter.call(e, { subscription_id: request_id })
           ensure
-            stream = @mutex.synchronize do
-              subscription = @listen_subscriptions.delete(subscription_key)
-              subscription && subscription[:stream]
-            end
-            close_stream_safely(stream) if stream
+            # Through the helper, so the entry is marked closed here as it is for every other removal.
+            subscription = remove_listen_subscription(subscription_key)
+            close_removed_listen_stream(subscription) if subscription
           end
         end
 
@@ -1068,12 +1172,36 @@ module MCP
 
           subscriptions = filter[:resourceSubscriptions]
           if capability_flag?(capabilities, :resources, :subscribe) && subscriptions.is_a?(Array) && !subscriptions.empty?
-            honored[:resourceSubscriptions] = subscriptions
+            honored[:resourceSubscriptions] = subscriptions.uniq
           end
 
           honored
         end
 
+        # Checks a listen filter's `resourceSubscriptions` against the schema, which types it as an optional array of strings,
+        # so a member that is present but `null` is refused like any other non-array; against `MAX_RESOURCE_SUBSCRIPTION_URIS`;
+        # and against `max_resource_subscription_bytes`, returning the problem to report or `nil`. Duplicates are dropped before
+        # the bounds are measured, since they are dropped before storage too. The checks run whether or not the server declares
+        # the `subscribe` capability: a request that violates the schema is invalid regardless of what would be honored,
+        # and the bounds are limits on the request itself, like `max_request_bytes`, not on what the server would retain from it.
+        def resource_subscriptions_problem(filter)
+          return unless filter.key?(:resourceSubscriptions)
+
+          subscriptions = filter[:resourceSubscriptions]
+          unless subscriptions.is_a?(Array) && subscriptions.all? { |uri| uri.is_a?(String) }
+            return "`resourceSubscriptions` must be an array of strings"
+          end
+
+          distinct = subscriptions.uniq
+          if distinct.size > MAX_RESOURCE_SUBSCRIPTION_URIS
+            return "`resourceSubscriptions` exceeds #{MAX_RESOURCE_SUBSCRIPTION_URIS} URIs"
+          end
+          return unless @max_resource_subscription_bytes
+          return if distinct.sum(&:bytesize) <= @max_resource_subscription_bytes
+
+          "`resourceSubscriptions` exceeds #{@max_resource_subscription_bytes} bytes"
+        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.
@@ -1091,24 +1219,16 @@ module MCP
           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 |subscription_key, subscription|
-              # An inactive entry has not finished writing its acknowledgement yet;
-              # delivering to it would put a notification ahead of the acknowledgement.
-              next unless subscription[:active]
-
-              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
+          # Only the snapshot of active entries is taken under `@mutex`, one pass over the entries as before;
+          # the matching and the stream writes happen outside it, so neither the number of URIs the streams named
+          # nor a slow or stalled subscriber can hold the transport's lock, matching the legacy delivery paths.
+          # An inactive entry has not finished writing its acknowledgement yet;
+          # delivering to it would put a notification ahead of the acknowledgement.
+          candidates = @mutex.synchronize { @listen_subscriptions.select { |_key, subscription| subscription[:active] } }
 
-              [subscription_key, subscription] if hit
-            end
+          uri = params.is_a?(Hash) ? params[:uri] || params["uri"] : nil
+          matched = candidates.select do |_key, subscription|
+            field ? subscription[:filter][field] : subscription[:resource_uris].include?(uri)
           end
 
           matched.each do |subscription_key, subscription|
@@ -1132,7 +1252,7 @@ module MCP
                 { subscription_id: subscription[:request_id], error: "Failed to send notification" },
               )
               remove_listen_subscription(subscription_key)
-              close_stream_safely(subscription[:stream])
+              close_removed_listen_stream(subscription)
             end
           end
         end
@@ -1140,12 +1260,27 @@ module MCP
         def remove_listen_subscription(subscription_key)
           @mutex.synchronize do
             subscription = @listen_subscriptions.delete(subscription_key)
-            subscription[:keepalive_wakeup].signal if subscription
+            if subscription
+              # Marked closed as teardown does, so a delivery or keepalive that took the entry before the removal skips it under
+              # the write mutex instead of writing to a stream being closed. The flag is set without taking the write mutex,
+              # which must never be taken inside `@mutex`: a write that checks the flag from here on skips, and one already
+              # past its check lands before the stream closes, since `close_removed_listen_stream` waits for the write mutex.
+              subscription[:closed] = true
+              subscription[:keepalive_wakeup].signal
+            end
 
             subscription
           end
         end
 
+        # Closes a subscription's stream while excluding concurrent writes. The write mutex, taken here outside
+        # `@mutex`, makes the close wait for a write already past its `closed` check, so that write completes or fails
+        # before the stream is closed, and a write that takes the mutex afterwards sees `closed` and skips. Teardown
+        # gets the same ordering by setting `closed` under the write mutex itself.
+        def close_removed_listen_stream(subscription)
+          subscription[:write_mutex].synchronize { close_stream_safely(subscription[:stream]) }
+        end
+
         # Graceful teardown (SEP-2575): each open listen stream receives its `SubscriptionsListenResult` response
         # before the stream closes.
         def teardown_listen_subscriptions
@@ -1296,6 +1431,16 @@ module MCP
           end
 
           if initialize_request?(body)
+            # Checked before a session exists: the body's `clientInfo` and `capabilities` are what the session would keep,
+            # so an oversized `initialize` is refused outright instead of being stored and capped later.
+            if @max_initialize_request_bytes && body_string.bytesize > @max_initialize_request_bytes
+              return initialize_too_large_response(body[:id], "body exceeds #{@max_initialize_request_bytes} bytes")
+            end
+
+            if !@stateless && json_values_exceed?(body[:params], MAX_INITIALIZE_PARAMS_VALUES)
+              return initialize_too_large_response(body[:id], "params exceed #{MAX_INITIALIZE_PARAMS_VALUES} JSON values")
+            end
+
             if !@stateless && session_id
               # An `initialize` request carrying an `Mcp-Session-Id` header is either a duplicate
               # initialization attempt against a live session, or a retry against an unknown/expired
@@ -1524,6 +1669,45 @@ module MCP
           )
         end
 
+        def initialize_too_large_response(request_id, reason)
+          json_rpc_error_response(
+            status: 413,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Payload too large: initialize request #{reason}",
+            id: request_id,
+          )
+        end
+
+        # Counts the JSON values in `value` (every object, array, object key, and scalar) and reports whether
+        # they exceed `limit`. The walk is iterative. Every value still queued is at least one more value,
+        # so `count + pending.size` never overstates the total, and a container is refused before its members are
+        # queued if they would take that sum past the limit; the walk therefore stops as soon as the limit is
+        # certain to be passed and never queues more than `limit` values, whatever the shape of the input.
+        def json_values_exceed?(value, limit)
+          count = 0
+          pending = [value]
+
+          until pending.empty?
+            current = pending.pop
+            count += 1
+
+            case current
+            when Hash
+              count += current.size
+              return true if count + pending.size + current.size > limit
+
+              pending.concat(current.values)
+            when Array
+              return true if count + pending.size + current.size > limit
+
+              pending.concat(current)
+            end
+            return true if count + pending.size > limit
+          end
+
+          false
+        end
+
         def parse_request_body(body_string)
           # `max_nesting` bounds parse depth; a too-deep body raises `JSON::NestingError`,
           # a subclass of `JSON::ParserError`, so it is caught below as a parse error.

data/lib/mcp/server.rb

@@ -181,8 +181,13 @@ module MCP
       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, :request_state_security
+    attr_accessor :description, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resource_templates, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
+    attr_reader :icons, :resources, :page_size, :client_capabilities, :ttl_ms, :cache_scope, :request_state_security
+
+    # Replaces the icons advertised in `serverInfo`; a Hash is converted through `Icon.from`.
+    def icons=(value)
+      @icons = Icon.from_list(value)
+    end
 
     def initialize(
       description: nil,
@@ -207,7 +212,7 @@ module MCP
       transport: nil
     )
       @description = description
-      @icons = icons
+      @icons = Icon.from_list(icons)
       @name = name
       @title = title
       @version = version

data/lib/mcp/tool.rb

@@ -86,7 +86,7 @@ module MCP
         if value == NOT_SET
           @icons_value
         else
-          @icons_value = value
+          @icons_value = Icon.from_list(value)
         end
       end
 

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "1.6.1"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -108,7 +108,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.6.1
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.7.0
   homepage_uri: https://ruby.sdk.modelcontextprotocol.io
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues