mcp 0.17.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 325fab0f82b31b6a2614ef626ebecb12a7bf22c199ddf189dcd70b4fcf9acb58
-  data.tar.gz: 7cb2b010e0808efce62e9d80f487c7cb6bff9604e13f6b2b68590ffa4e0fc784
+  metadata.gz: 959e38a26541c9681c11e8bc227e84c42d20e3d98de1568c0afd45c80f3b4474
+  data.tar.gz: e2bf6b0c7926e1803f9dff1279c1f5a35d96f1cf8a1e3c6141b22a97871c8ec2
 SHA512:
-  metadata.gz: 6c675a999c460dd7a285203e949587ecf1faf43a0f80f67f6f00bbb06abaa31846382cf013a0590a22c237b341860bc9a880d2d6d5de2971c8f70cde8d9d78ee
-  data.tar.gz: 84f4ca2c9a3a745976059655e2ea6f89ff5bae6637b32ab151894f12b3aea96ce5f11d9e50b3c908769f97e9bc923fd68f0e0b83060104964710d6ca70f06cb0
+  metadata.gz: 5f347a7259f4e728df5edad217d6963cb3428188e46244efd9be9908e84bf4a7134600c6f453249eedc87e33f998f3f51811922659f116811251a64d78f1bbee
+  data.tar.gz: 3d8d25f65c590d07157db74d87423bbde82250b5d99cf2e3182c8adbc198f534f96809265c8615160f49f963a3b2dc2a07a85db2f6f2cc83e11b068583f405de

data/README.md

@@ -1253,6 +1253,25 @@ A `ping` request has no parameters, and the receiver MUST respond promptly with
 Servers respond to incoming `ping` requests automatically - no setup is required.
 Any `MCP::Server` instance replies with an empty result.
 
+Servers can also send `ping` requests to the client via `ServerSession#ping`.
+Inside a tool handler that receives `server_context:`, call `ping` on it:
+
+```ruby
+class HealthCheckTool < MCP::Tool
+  description "Verifies the client is still responsive"
+
+  def self.call(server_context:)
+    server_context.ping # => {} on success
+
+    MCP::Tool::Response.new([{ type: "text", text: "client is alive" }])
+  end
+end
+```
+
+`#ping` raises `MCP::Server::ValidationError` when the client returns a `result`
+that is not a Hash. Transport-level errors (e.g., the client returning a JSON-RPC error)
+propagate as exceptions raised by the transport layer.
+
 #### Client-Side
 
 `MCP::Client` exposes `ping` to send a ping to the server:
@@ -1736,7 +1755,7 @@ This class supports:
 
 - Liveness check via the `ping` method (`MCP::Client#ping`)
 - Tool listing via the `tools/list` method (`MCP::Client#tools`)
-- Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)
+- Tool invocation via the `tools/call` method (`MCP::Client#call_tool`)
 - Resource listing via the `resources/list` method (`MCP::Client#resources`)
 - Resource template listing via the `resources/templates/list` method (`MCP::Client#resource_templates`)
 - Resource reading via the `resources/read` method (`MCP::Client#read_resource`)
@@ -1894,6 +1913,9 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
 - On a `401 Unauthorized`, parse the `WWW-Authenticate` header, discover the authorization server (Protected Resource Metadata + RFC 8414 Authorization Server Metadata),
   perform Dynamic Client Registration if needed, run the OAuth 2.1 Authorization Code flow with PKCE (S256), and retry the failed request with the acquired token.
 - On subsequent 401s with a saved `refresh_token`, exchange it at the token endpoint before falling back to the full interactive flow (RFC 6749 Section 6).
+- Request the `offline_access` scope when `client_metadata[:grant_types]` includes `refresh_token` and the authorization server advertises `offline_access` in its metadata
+  `scopes_supported` (SEP-2207). This is what lets the server issue the `refresh_token` used above. As an SDK-level safeguard, when the authorization server does not advertise
+  `offline_access` the scope is also stripped from any other source (challenge, PRM, or provider-supplied scope) so a server that does not support it never receives it.
 
 ```ruby
 require "mcp"
@@ -1939,6 +1961,17 @@ Optional keyword arguments:
 - `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
 - `storage`: Object responding to `tokens`, `save_tokens(t)`, `client_information`, `save_client_information(info)`. Defaults to `MCP::Client::OAuth::InMemoryStorage`,
   which keeps credentials in process memory only.
+- `client_id_metadata_document_url`: URL where you publish a Client ID Metadata Document
+  (`draft-ietf-oauth-client-id-metadata-document` and the MCP authorization specification).
+  When the authorization server advertises `client_id_metadata_document_supported: true`,
+  the SDK uses this URL as the OAuth `client_id` and skips Dynamic Client Registration.
+  Spec-required: the URL MUST be `https://` with a non-root path and MUST NOT include a fragment,
+  userinfo, or `.`/`..` segments. The SDK additionally rejects query strings (the draft only marks
+  them SHOULD NOT include, but the SDK refuses to send any) for `client_id` stability.
+  Any of these failures raise `Provider::InvalidClientIDMetadataDocumentURLError`. The CIMD document
+  served at the URL is a separate JSON artifact from the `client_metadata` keyword above:
+  the DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include
+  `client_id` set to the document URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
 
 To persist credentials across restarts, supply your own storage:
 

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

@@ -183,6 +183,50 @@ module MCP
             false
           end
 
+          # Returns true when `url` satisfies the structural requirements for
+          # a Client ID Metadata Document URL per the MCP 2025-11-25
+          # authorization specification and `draft-ietf-oauth-client-id-metadata-document-00`.
+          #
+          # Spec-required:
+          #
+          # - scheme MUST be `https` (the loopback-`http` carve-out used for discovery does not apply:
+          #   the document URL is sent verbatim to the authorization server as the OAuth `client_id`
+          #   and travels off-loopback)
+          # - host MUST be present
+          # - path MUST be non-empty and MUST NOT be the root (`/`); the document is a discrete resource,
+          #   not the origin
+          # - URL MUST NOT carry a fragment or userinfo: a fragment is not sent to the server, and userinfo
+          #   would leak credentials into every `client_id` log line
+          # - path MUST be already free of `.` / `..` dot segments after percent-decoding, so two URLs with
+          #   the same effective path do not produce different `client_id` strings
+          #
+          # SDK policy (stricter than the draft):
+          #
+          # - URL MUST NOT carry a query string. The draft marks query components only SHOULD NOT include,
+          #   but different encodings of the same query (`?a=1&b=2` vs `?b=2&a=1`) would yield distinct
+          #   `client_id` values for the same logical document.
+          def client_id_metadata_document_url?(url)
+            return false if url.nil? || url.to_s.empty?
+
+            uri = URI.parse(url.to_s)
+            return false unless uri.scheme&.downcase == "https"
+            return false if uri.host.nil? || uri.host.empty?
+            return false unless uri.fragment.nil?
+            return false unless uri.query.nil?
+            return false if uri.respond_to?(:user) && (uri.user || uri.password)
+
+            path = uri.path.to_s
+            return false if path.empty? || path == "/"
+
+            decoded = path.gsub(/%2[eE]/, ".")
+            segments = decoded.split("/", -1)
+            return false if segments.any? { |segment| segment == "." || segment == ".." }
+
+            true
+          rescue URI::InvalidURIError
+            false
+          end
+
           # Like `canonicalize_url` but also strips query string, fragment, and
           # userinfo. This variant is used for identity comparison against
           # the request URL Faraday actually sends, which differs from the value

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

@@ -59,6 +59,7 @@ module MCP
           client_info = ensure_client_registered(as_metadata: as_metadata)
 
           effective_scope = resolve_scope(scope: scope, prm: prm)
+          effective_scope = normalize_offline_access_scope(effective_scope, as_metadata: as_metadata)
           pkce = PKCE.generate
           state = SecureRandom.urlsafe_base64(32)
 
@@ -104,8 +105,16 @@ module MCP
           refresh_token = read_token("refresh_token")
           raise AuthorizationError, "Cannot refresh: no refresh_token in provider storage." unless refresh_token
 
-          client_info = @provider.client_information
-          unless client_info.is_a?(Hash) && client_info_required_value(client_info, "client_id")
+          stored_client_info = @provider.client_information
+          have_stored_client_info = stored_client_info.is_a?(Hash) && client_info_required_value(stored_client_info, "client_id")
+
+          # A CIMD-configured provider stores no `client_information` on purpose
+          # (the CIMD URL is re-resolved against the live AS metadata on every flow).
+          # Allow refresh to proceed in that case so the `refresh_token` obtained via
+          # the CIMD flow remains usable.
+          have_cimd_url = !@provider.client_id_metadata_document_url.nil?
+
+          unless have_stored_client_info || have_cimd_url
             raise AuthorizationError, "Cannot refresh: no client_information in provider storage."
           end
 
@@ -126,6 +135,18 @@ module MCP
           ensure_issuer_matches!(expected: authorization_server, returned: as_metadata["issuer"])
           ensure_secure_endpoints!(as_metadata)
 
+          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.
+            stored_client_info
+          elsif as_metadata["client_id_metadata_document_supported"] == true
+            { "client_id" => @provider.client_id_metadata_document_url }
+          else
+            raise AuthorizationError,
+              "Cannot refresh: provider has a CIMD URL but the authorization server no longer advertises " \
+                "`client_id_metadata_document_supported: true`."
+          end
+
           new_tokens = exchange_refresh_token(
             as_metadata: as_metadata,
             client_info: client_info,
@@ -285,6 +306,24 @@ module MCP
           existing = @provider.client_information
           return existing if existing.is_a?(Hash) && client_info_required_value(existing, "client_id")
 
+          # 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
+          # a CIMD URL configured, use the URL as the OAuth `client_id` and skip Dynamic Client Registration.
+          #
+          # The `== true` comparison is intentional: only a JSON `boolean` `true` opts the flow in.
+          # A string `"false"`, an empty Hash, or any other truthy value MUST NOT be treated as CIMD support,
+          # otherwise a misconfigured AS could trick the client into using the CIMD `client_id` against
+          # a server that has not actually adopted it.
+          #
+          # The CIMD `client_id` is NOT persisted to storage. The AS may later stop advertising CIMD support
+          # (or the operator may rotate the CIMD URL), and a stale `client_information` entry would otherwise
+          # keep sending the old CIMD URL forever. Re-evaluating on every flow re-reads the current AS metadata
+          # and the current `provider.client_id_metadata_document_url`.
+          cimd_url = @provider.client_id_metadata_document_url
+          if cimd_url && as_metadata["client_id_metadata_document_supported"] == true
+            return { "client_id" => cimd_url }
+          end
+
           registration_endpoint = as_metadata["registration_endpoint"]
           unless registration_endpoint
             raise AuthorizationError,
@@ -403,6 +442,48 @@ module MCP
           nil
         end
 
+        # Applies the SDK's `offline_access` policy to the resolved scope. The policy has two halves:
+        #
+        # - Spec (SEP-2207): a client that wants a refresh token (signalled here by listing
+        #   `refresh_token` in its registered `grant_types`) MAY request `offline_access`
+        #   when the authorization server advertises it in metadata `scopes_supported`.
+        #   When the server advertises it and the client opted in, add it if absent.
+        #
+        # - SDK policy (defensive hardening): when the server does NOT advertise `offline_access`,
+        #   strip it from the resolved scope no matter where it came from (the `WWW-Authenticate` challenge,
+        #   PRM `scopes_supported`, or the provider-supplied scope). SEP-2207 only says clients SHOULD NOT
+        #   request unsupported scopes, but a misbehaving RS that includes `offline_access` in its challenge,
+        #   or a misconfigured PRM that lists it under `scopes_supported`, would otherwise propagate into
+        #   the authorization request even though the AS will not honour it. Stripping here keeps the SDK's
+        #   own request consistent with the AS's advertisement.
+        #
+        # Returns `nil` when the result is empty so `build_authorization_url` omits the `scope` parameter entirely.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207
+        def normalize_offline_access_scope(scope, as_metadata:)
+          scopes = scope.to_s.split
+
+          if server_supports_offline_access?(as_metadata)
+            scopes << "offline_access" if wants_refresh_token? && !scopes.include?("offline_access")
+          else
+            scopes.delete("offline_access")
+          end
+
+          scopes.empty? ? nil : scopes.join(" ")
+        end
+
+        def server_supports_offline_access?(as_metadata)
+          supported = as_metadata["scopes_supported"]
+
+          supported.is_a?(Array) && supported.include?("offline_access")
+        end
+
+        def wants_refresh_token?
+          metadata = @provider.client_metadata
+          grant_types = metadata[:grant_types] || metadata["grant_types"]
+
+          Array(grant_types).include?("refresh_token")
+        end
+
         def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint

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

@@ -25,6 +25,16 @@ module MCP
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`.
+      # - `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`,
+      #   the SDK uses this URL as the OAuth `client_id` and skips Dynamic Client Registration.
+      #   Spec-required: `https://` scheme, a non-root path, and no fragment, userinfo, or `.`/`..` segments.
+      #   The SDK additionally refuses to send query strings (the draft marks them only SHOULD NOT include,
+      #   but different encodings of the same query would yield different `client_id` strings for the same document).
+      #   The document served at the URL is a separate JSON artifact from the `client_metadata` keyword:
+      #   DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include `client_id` set
+      #   to the URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
       class Provider
         # Raised when `Provider#initialize` is called with a `redirect_uri` that
         # is neither HTTPS nor a loopback `http://` URL, per the MCP
@@ -38,12 +48,21 @@ module MCP
         # runtime; failing at construction surfaces the bug earlier.
         class UnregisteredRedirectURIError < ArgumentError; end
 
+        # Raised when `client_id_metadata_document_url` is provided but does not meet
+        # the structural requirements for a Client ID Metadata Document URL:
+        # HTTPS, non-root path, and no fragment, query, userinfo, or `.`/`..` segments.
+        # The CIMD URL is sent to the authorization server as the OAuth `client_id`,
+        # so the same Communication Security guarantee that protects the redirect URI
+        # applies and the value must unambiguously identify the document.
+        class InvalidClientIDMetadataDocumentURLError < ArgumentError; end
+
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
           :storage,
           :redirect_handler,
-          :callback_handler
+          :callback_handler,
+          :client_id_metadata_document_url
 
         def initialize(
           client_metadata:,
@@ -51,7 +70,8 @@ module MCP
           redirect_handler:,
           callback_handler:,
           scope: nil,
-          storage: nil
+          storage: nil,
+          client_id_metadata_document_url: nil
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -66,12 +86,20 @@ module MCP
                 "(got #{registered.inspect}); otherwise the authorization server will reject the authorization request."
           end
 
+          if client_id_metadata_document_url && !Discovery.client_id_metadata_document_url?(client_id_metadata_document_url)
+            raise InvalidClientIDMetadataDocumentURLError,
+              "client_id_metadata_document_url #{client_id_metadata_document_url.inspect} must be an https URL " \
+                "with a non-root path and no fragment, query, userinfo, or `.`/`..` segments, " \
+                "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
+          end
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
           @storage = storage || InMemoryStorage.new
+          @client_id_metadata_document_url = client_id_metadata_document_url
         end
 
         def access_token

data/lib/mcp/client/stdio.rb

@@ -134,7 +134,10 @@ module MCP
 
       def send_request(request:)
         start unless @started
-        connect unless @initialized
+        unless @initialized
+          warn("Calling `MCP::Client::Stdio#send_request` without calling `MCP::Client#connect` is deprecated. Use `MCP::Client#connect` before sending requests instead.", uplevel: 1)
+          connect
+        end
 
         write_message(request)
         read_response(request)

data/lib/mcp/client.rb

@@ -146,21 +146,7 @@ module MCP
     #   end
     def tools
       # TODO: consider renaming to `list_all_tools`.
-      all_tools = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_tools(cursor: cursor)
-        all_tools.concat(page.tools)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_tools
+      fetch_all_pages { |cursor| list_tools(cursor: cursor) }.flat_map(&:tools)
     end
 
     # Returns a single page of resources from the server.
@@ -189,21 +175,7 @@ module MCP
     # @return [Array<Hash>] An array of available resources.
     def resources
       # TODO: consider renaming to `list_all_resources`.
-      all_resources = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resources(cursor: cursor)
-        all_resources.concat(page.resources)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_resources
+      fetch_all_pages { |cursor| list_resources(cursor: cursor) }.flat_map(&:resources)
     end
 
     # Returns a single page of resource templates from the server.
@@ -232,21 +204,7 @@ module MCP
     # @return [Array<Hash>] An array of available resource templates.
     def resource_templates
       # TODO: consider renaming to `list_all_resource_templates`.
-      all_templates = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resource_templates(cursor: cursor)
-        all_templates.concat(page.resource_templates)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_templates
+      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor) }.flat_map(&:resource_templates)
     end
 
     # Returns a single page of prompts from the server.
@@ -275,21 +233,7 @@ module MCP
     # @return [Array<Hash>] An array of available prompts.
     def prompts
       # TODO: consider renaming to `list_all_prompts`.
-      all_prompts = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_prompts(cursor: cursor)
-        all_prompts.concat(page.prompts)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_prompts
+      fetch_all_pages { |cursor| list_prompts(cursor: cursor) }.flat_map(&:prompts)
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -380,6 +324,27 @@ module MCP
 
     private
 
+    # Walks every page of a list endpoint, following `next_cursor`, and returns
+    # the page results. The `seen` set guards against a server that repeats or
+    # cycles cursors, so the loop always terminates.
+    def fetch_all_pages
+      pages = []
+      seen = Set.new
+      cursor = nil
+
+      loop do
+        page = yield(cursor)
+        pages << page
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      pages
+    end
+
     def request(method:, params: nil)
       request_body = {
         jsonrpc: JsonRpcHandler::Version::V2_0,

data/lib/mcp/resource.rb

@@ -5,15 +5,16 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :size, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, size: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @size = size
       @meta = meta
     end
 
@@ -25,6 +26,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        size: size,
         _meta: meta,
       }.compact
     end

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

@@ -426,7 +426,7 @@ module MCP
             return success_response
           end
 
-          return missing_session_id_response unless (session_id = request.env["HTTP_MCP_SESSION_ID"])
+          return missing_session_id_response unless (session_id = extract_session_id(request))
           return session_not_found_response unless session_exists?(session_id)
 
           protocol_version_error = validate_protocol_version_header(request)
@@ -504,7 +504,7 @@ module MCP
 
         def parse_accept_header(header)
           header.split(",").map do |part|
-            part.split(";").first.strip
+            part.split(";").first.strip.downcase
           end
         end
 

data/lib/mcp/server.rb

@@ -67,6 +67,11 @@ module MCP
       end
     end
 
+    # Raised when a client response fails server-side validation, e.g., a success response
+    # whose `result` field is missing or has the wrong type. This is distinct from a
+    # client-returned JSON-RPC error.
+    class ValidationError < StandardError; end
+
     include Instrumentation
     include Pagination
 

data/lib/mcp/server_context.rb

@@ -59,6 +59,28 @@ module MCP
       end
     end
 
+    # Sends a `ping` request to the originating client to verify it is still responsive.
+    # Per the MCP spec, the client MUST respond promptly with an empty result.
+    #
+    # @return [Hash] An empty hash on success.
+    # @raise [Server::ValidationError] If the response `result` is not a Hash.
+    # @raise [NoMethodError] If the session does not support sending pings.
+    #
+    # @example
+    #   def self.call(server_context:)
+    #     server_context.ping # => {}
+    #     # ...
+    #   end
+    #
+    # @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
+    def ping
+      if @notification_target.respond_to?(:ping)
+        @notification_target.ping(related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'ping' for #{self}"
+      end
+    end
+
     # Delegates to the session so the request is scoped to the originating client.
     # Falls back to `@context` (via `method_missing`) when `@notification_target`
     # does not support sampling.

data/lib/mcp/server_session.rb

@@ -106,6 +106,14 @@ module MCP
       send_to_transport_request(Methods::ROOTS_LIST, nil, related_request_id: related_request_id)
     end
 
+    # Sends a `ping` request scoped to this session.
+    def ping(related_request_id: nil)
+      result = send_to_transport_request(Methods::PING, nil, related_request_id: related_request_id)
+      raise Server::ValidationError, "Response validation failed: invalid `result`" unless result.is_a?(Hash)
+
+      result
+    end
+
     # Sends a `sampling/createMessage` request scoped to this session.
     def create_sampling_message(related_request_id: nil, **kwargs)
       params = @server.build_sampling_params(client_capabilities, **kwargs)

data/lib/mcp/tool/schema.rb

@@ -1,10 +1,41 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json-schema"
 
 module MCP
   class Tool
     class Schema
+      # Metaschema validation depends only on schema content, so a given schema
+      # never needs to be validated more than once. Caching the result lets repeated
+      # (e.g. dynamically rebuilt) schemas skip the costly traversal.
+      class ValidationCache
+        DEFAULT_MAX_SIZE = 1000
+
+        def initialize(max_size: DEFAULT_MAX_SIZE)
+          @max_size = max_size
+          @entries = {}
+          @mutex = Mutex.new
+        end
+
+        def validated?(key)
+          @mutex.synchronize { @entries.key?(key) }
+        end
+
+        def store(key)
+          @mutex.synchronize do
+            @entries.delete(key)
+            @entries[key] = true
+            @entries.shift while @entries.size > @max_size
+          end
+        end
+
+        def clear
+          @mutex.synchronize { @entries.clear }
+        end
+      end
+      VALIDATION_CACHE = ValidationCache.new
+
       # JSON Schema 2020-12 is the default dialect for MCP schema definitions
       # per MCP 2025-11-25 (SEP-1613). Note: emission only — runtime validation
       # is still performed against the JSON Schema draft-04 metaschema because
@@ -36,6 +67,14 @@ module MCP
       end
 
       def validate_schema!
+        target = schema_for_validation
+
+        # `max_nesting: false` because normalization uses `JSON.dump` (no nesting limit),
+        # so the default `JSON.generate` limit would raise on a deeply nested schema that
+        # the initializer already accepted.
+        key = Digest::SHA256.hexdigest(JSON.generate(target, max_nesting: false))
+        return if VALIDATION_CACHE.validated?(key)
+
         gem_path = File.realpath(Gem.loaded_specs["json-schema"].full_gem_path)
         schema_reader = JSON::Schema::Reader.new(
           accept_uri: false,
@@ -45,10 +84,12 @@ module MCP
         # Converts metaschema to a file URI for cross-platform compatibility
         metaschema_uri = JSON::Util::URI.file_uri(metaschema_path.expand_path.cleanpath.to_s.tr("\\", "/"))
         metaschema = metaschema_uri.to_s
-        errors = JSON::Validator.fully_validate(metaschema, schema_for_validation, schema_reader: schema_reader)
+        errors = JSON::Validator.fully_validate(metaschema, target, schema_reader: schema_reader)
         if errors.any?
           raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"
         end
+
+        VALIDATION_CACHE.store(key)
       end
 
       # The `json-schema` gem's draft-04 validator cannot resolve newer or unknown `$schema`

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -87,7 +87,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.17.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.19.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