mcp 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1915f5e50dda558f3ba32d0c946dacafda7c0ee183300cd634632505ab206bd
-  data.tar.gz: 9f702e675c56e191effefa6a7a7ac5b4d5f3c0c8bded9284484bf7260b551f3b
+  metadata.gz: b7ace5af244e82b2df4f3fef449fd0942d3d9be46746d820f8207cfcee87af52
+  data.tar.gz: ce4b53defad3ed24646806c2236a8d79c68597c7225fa4fcef20fd2d85031c24
 SHA512:
-  metadata.gz: 76797292c1345c02d77b63b5d840bf9a39fe719e2df6a232a32a342d9e6974e296bc4e1a08939bba539ea56f9a00ab25cf225936ecd02cd1cee31fdfd7e39d48
-  data.tar.gz: f1063ce3c1781e713f556489b0a70d58d102b42d6f220b63a138b97a0532dbfd521b7aea428ed2811d94923bff39ab6f02cad0504ad0597c53e48676cb27984f
+  metadata.gz: 2c2ef2a03fb1b989e691aea55d350f06b9f1f357b0acfcda4e227ca359c3a12990d06fe280ced39b1e6d620181aa9c7b8d355d5985c70d090512636da7c34f3a
+  data.tar.gz: a75f884057bc318a98943fec8967c4725c63dd767552dc52591c8e08143474f8a28907e929cdbe0efb645426766b75314449b9df8c3c86aa90bb0a68247004ff

data/README.md

@@ -231,6 +231,31 @@ server = MCP::Server.new(
 )
 ```
 
+### Capability Extensions
+
+Per SEP-2133, both clients and servers can declare protocol extensions under the `extensions` member of their capabilities.
+Keys are extension identifiers using the reverse-DNS prefix convention (e.g. `"io.modelcontextprotocol/tasks"`, `"com.example/feature"`);
+values are extension-defined configuration objects, with `{}` meaning "supported with no settings".
+
+On the server, declare extensions through the `capabilities` keyword, either as a plain hash or via the `MCP::Server::Capabilities` builder:
+
+```ruby
+capabilities = MCP::Server::Capabilities.new
+capabilities.support_tools
+capabilities.support_extensions("com.example/feature" => { enabled: true })
+
+server = MCP::Server.new(name: "my_server", capabilities: capabilities)
+```
+
+The declared extensions appear in the `initialize` result's `capabilities.extensions`. Extensions the client declared during `initialize` are
+readable via `server.client_capabilities[:extensions]` (or `session.client_capabilities[:extensions]` for per-session transports).
+
+On the client, pass extensions through `connect`:
+
+```ruby
+client.connect(capabilities: { extensions: { "com.example/feature" => {} } })
+```
+
 ### Server Context and Configuration Block Data
 
 #### `server_context`
@@ -549,6 +574,10 @@ end
 The server_context parameter is the server_context passed into the server and can be used to pass per request information,
 e.g. around authentication state.
 
+Tool arguments arrive as a `Hash` with symbol keys at every nesting level, because the transports parse JSON with `symbolize_names: true`.
+Read nested objects with symbol keys (`payload[:subject]`, not `payload["subject"]`).
+See [Tool argument keys](docs/building-servers.md#tool-argument-keys) for details and a testing tip.
+
 ### Tool Annotations
 
 Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
@@ -1635,6 +1664,11 @@ Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
 ```
 
+In stateless mode, each POST is fully self-contained per SEP-2567: no `Mcp-Session-Id` is issued or required,
+handlers run against an ephemeral per-request session (so client identity never leaks across requests or onto the shared server),
+and repeated `initialize` requests are permitted. Request-scoped notifications such as progress and log messages are skipped
+(there is no stream to deliver them), while server-to-client requests (`sampling/createMessage`, `roots/list`, `elicitation/create`) raise an error.
+
 You can enable JSON response mode, where the server returns `application/json` instead of `text/event-stream`.
 Set `enable_json_response: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`:
 
@@ -1961,6 +1995,9 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
 - Send `Authorization: Bearer <access_token>` on every request when a token is available.
 - 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.
+- Fall back to the legacy 2025-03-26 discovery when the server publishes no Protected Resource Metadata, matching the TypeScript and Python SDKs: the MCP server's origin acts
+  as the authorization base URL, its metadata is fetched from `<origin>/.well-known/oauth-authorization-server` without the RFC 8414 issuer byte-match (which the legacy spec predates),
+  and when even that is absent the spec's default endpoints `/authorize`, `/token`, and `/register` at the origin are used with PKCE S256 assumed.
 - 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).
 - On a `403 Forbidden` whose `WWW-Authenticate` header carries `error="insufficient_scope"` (OAuth 2.0 step-up, RFC 6750 Section 3.1 and the MCP scope-selection-strategy),
   run a fresh authorization request for the union of the currently granted scope and the scope named in the challenge, then retry the failed request once.
@@ -2004,6 +2041,8 @@ Required keyword arguments to `Provider.new`:
 
 - `client_metadata`: Hash sent to the authorization server's Dynamic Client Registration endpoint. Must include `redirect_uris`, `grant_types`, `response_types`,
   `token_endpoint_auth_method`. `redirect_uri` (below) must appear in this list, otherwise the constructor raises `Provider::UnregisteredRedirectURIError`.
+  When `application_type` is omitted, the SDK infers `"native"` or `"web"` from `redirect_uris` per SEP-837 before registering (loopback or custom-scheme URIs are native);
+  an explicit value always wins.
 - `redirect_uri`: String. Must use HTTPS or be a loopback URL (`localhost`, `127.0.0.0/8`, `::1`); other values raise `Provider::InsecureRedirectURIError`.
 - `redirect_handler`: Callable invoked with the fully-built authorization `URI`. Typically opens the user's browser.
 - `callback_handler`: Callable that returns `[code, state]` after the user is redirected back to `redirect_uri`.

data/lib/mcp/annotations.rb

@@ -5,6 +5,8 @@ module MCP
     attr_reader :audience, :priority, :last_modified
 
     def initialize(audience: nil, priority: nil, last_modified: nil)
+      raise ArgumentError, "The value of priority must be between 0 and 1." if priority && !priority.between?(0, 1)
+
       @audience = audience
       @priority = priority
       @last_modified = last_modified

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

@@ -237,6 +237,23 @@ module MCP
             false
           end
 
+          # Infers the OIDC Dynamic Client Registration `application_type` for a client from its `redirect_uris`.
+          # Per SEP-837, MCP clients MUST specify an appropriate application type during Dynamic Client Registration
+          # so the authorization server can apply the matching redirect URI policy.
+          #
+          # Returns `"native"` when every redirect URI is a native-app URI: a custom non-http(s) scheme (RFC 8252 Section 7.1)
+          # or an http(s) URI whose host is a loopback address (`localhost`, `127.0.0.0/8`, or `::1`, RFC 8252 Section 7.3).
+          # Returns `"web"` otherwise, including when `redirect_uris` is nil, empty, or contains an unparseable URI.
+          #
+          # - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/837
+          # - https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata
+          def infer_application_type(redirect_uris)
+            uris = Array(redirect_uris)
+            return "web" if uris.empty?
+
+            uris.all? { |uri| native_redirect_uri?(uri) } ? "native" : "web"
+          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
@@ -345,6 +362,20 @@ module MCP
             nil
           end
 
+          # A redirect URI counts as native when it uses a custom non-http(s) scheme
+          # (e.g. `com.example.app:/callback`) or when it is an http(s) URI whose host is
+          # a loopback address. A URI without a scheme or one that fails to parse is not native.
+          def native_redirect_uri?(url)
+            uri = URI.parse(url.to_s)
+            scheme = uri.scheme&.downcase
+            return false if scheme.nil?
+            return loopback_host?(uri.host) if ["http", "https"].include?(scheme)
+
+            true
+          rescue URI::InvalidURIError
+            false
+          end
+
           def base_url(uri)
             port_part = uri.port && uri.port != uri.default_port ? ":#{uri.port}" : ""
             "#{uri.scheme}://#{uri.host}#{port_part}"

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

@@ -38,22 +38,18 @@ module MCP
             ensure_secure_url!(resource_metadata_url, label: "WWW-Authenticate resource_metadata URL")
           end
 
-          prm = fetch_protected_resource_metadata(
+          prm, authorization_server = locate_authorization_server(
             server_url: server_url,
             resource_metadata_url: resource_metadata_url,
           )
-          authorization_server = first_authorization_server(prm)
-          ensure_secure_url!(authorization_server, label: "PRM `authorization_servers` entry")
 
           # Per RFC 8707 + MCP authorization, the canonical MCP server URI is sent on
           # both the authorization and token requests. When PRM advertises a `resource`,
           # it MUST identify the same MCP server we are talking to; otherwise we are
           # being redirected to credentials minted for a different audience.
-          resource = canonical_resource(server_url: server_url, prm_resource: prm["resource"])
+          resource = canonical_resource(server_url: server_url, prm_resource: prm&.dig("resource"))
 
-          as_metadata = fetch_authorization_server_metadata(issuer_url: authorization_server)
-          ensure_issuer_matches!(expected: authorization_server, returned: as_metadata["issuer"])
-          ensure_secure_endpoints!(as_metadata)
+          as_metadata = authorization_server_metadata(authorization_server: authorization_server, legacy: prm.nil?)
 
           if provider_authorization_flow == :client_credentials
             return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
@@ -63,7 +59,7 @@ module MCP
 
           client_info = ensure_client_registered(as_metadata: as_metadata)
 
-          effective_scope = resolve_scope(scope: scope, prm: prm)
+          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)
@@ -158,18 +154,14 @@ module MCP
             ensure_secure_url!(resource_metadata_url, label: "WWW-Authenticate resource_metadata URL")
           end
 
-          prm = fetch_protected_resource_metadata(
+          prm, authorization_server = locate_authorization_server(
             server_url: server_url,
             resource_metadata_url: resource_metadata_url,
           )
-          authorization_server = first_authorization_server(prm)
-          ensure_secure_url!(authorization_server, label: "PRM `authorization_servers` entry")
 
-          resource = canonical_resource(server_url: server_url, prm_resource: prm["resource"])
+          resource = canonical_resource(server_url: server_url, prm_resource: prm&.dig("resource"))
 
-          as_metadata = fetch_authorization_server_metadata(issuer_url: authorization_server)
-          ensure_issuer_matches!(expected: authorization_server, returned: as_metadata["issuer"])
-          ensure_secure_endpoints!(as_metadata)
+          as_metadata = authorization_server_metadata(authorization_server: authorization_server, legacy: prm.nil?)
 
           client_info = if have_stored_client_info
             # Pre-registered / DCR-issued `client_information` always wins: if the user picked an explicit identity,
@@ -221,6 +213,87 @@ module MCP
           fetch_metadata_json(urls, label: "protected resource metadata")
         end
 
+        # Locates the authorization server for `server_url` and returns `[prm, authorization_server]`.
+        #
+        # Modern path (2025-06-18+): Protected Resource Metadata names the authorization server in
+        # `authorization_servers`.
+        #
+        # Legacy path (2025-03-26 backwards compatibility): when the server publishes no PRM, `prm` is nil
+        # and the MCP server's own origin acts as the authorization base URL, matching the TypeScript and Python SDKs.
+        # Any PRM discovery failure (404s, network errors, malformed documents) selects the legacy path, mirroring both SDKs' behavior.
+        # https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#fallbacks-for-servers-without-metadata-discovery
+        def locate_authorization_server(server_url:, resource_metadata_url:)
+          prm = begin
+            fetch_protected_resource_metadata(
+              server_url: server_url,
+              resource_metadata_url: resource_metadata_url,
+            )
+          rescue AuthorizationError
+            nil
+          end
+
+          if prm
+            authorization_server = first_authorization_server(prm)
+            ensure_secure_url!(authorization_server, label: "PRM `authorization_servers` entry")
+            [prm, authorization_server]
+          else
+            authorization_base = server_origin!(server_url)
+            ensure_secure_url!(authorization_base, label: "MCP server origin (legacy authorization base URL)")
+            [nil, authorization_base]
+          end
+        end
+
+        # Fetches and validates the authorization server's RFC 8414 metadata.
+        #
+        # On the modern path the metadata `issuer` must be byte-identical to the discovery URL (RFC 8414 Section 3.3).
+        # On the legacy 2025-03-26 path that validation is skipped: the legacy spec predates the requirement,
+        # and a pre-PRM server may host its OAuth endpoints under a path prefix whose `issuer` legitimately differs from
+        # the origin the metadata was discovered at (neither the TypeScript nor the Python SDK validates the issuer on this path).
+        # When even the metadata document is absent, the legacy spec's default endpoints are used.
+        def authorization_server_metadata(authorization_server:, legacy:)
+          metadata = if legacy
+            begin
+              fetch_authorization_server_metadata(issuer_url: authorization_server)
+            rescue AuthorizationError
+              default_legacy_metadata(authorization_server)
+            end
+          else
+            fetch_authorization_server_metadata(issuer_url: authorization_server).tap do |fetched|
+              ensure_issuer_matches!(expected: authorization_server, returned: fetched["issuer"])
+            end
+          end
+
+          ensure_secure_endpoints!(metadata)
+          metadata
+        end
+
+        # The 2025-03-26 spec's "Fallbacks for Servers without Metadata Discovery": clients MUST use these default endpoint paths
+        # relative to the authorization base URL. PKCE S256 is assumed because the legacy spec mandates PKCE and there is no metadata
+        # to advertise it (the TypeScript and Python SDKs hardcode S256 on this path too).
+        def default_legacy_metadata(authorization_base)
+          {
+            "issuer" => authorization_base,
+            "authorization_endpoint" => "#{authorization_base}/authorize",
+            "token_endpoint" => "#{authorization_base}/token",
+            "registration_endpoint" => "#{authorization_base}/register",
+            "code_challenge_methods_supported" => ["S256"],
+          }
+        end
+
+        # Returns `scheme://host[:port]` of `server_url`, the legacy 2025-03-26 authorization base URL for servers without PRM.
+        def server_origin!(server_url)
+          uri = URI.parse(server_url.to_s)
+          unless uri.is_a?(URI::HTTP) && uri.host
+            raise AuthorizationError,
+              "Cannot derive a legacy authorization base URL from MCP server URL #{server_url.inspect}."
+          end
+
+          port_part = uri.port == uri.default_port ? "" : ":#{uri.port}"
+          "#{uri.scheme}://#{uri.host}#{port_part}"
+        rescue URI::InvalidURIError => e
+          raise AuthorizationError, "MCP server URL #{server_url.inspect} is not a valid URI: #{e.message}."
+        end
+
         def fetch_authorization_server_metadata(issuer_url:)
           urls = Discovery.authorization_server_metadata_urls(issuer_url)
           fetch_metadata_json(urls, label: "authorization server metadata")
@@ -367,7 +440,7 @@ module MCP
           end
 
           response = begin
-            http_post_json(registration_endpoint, @provider.client_metadata)
+            http_post_json(registration_endpoint, registration_client_metadata)
           rescue Faraday::Error => e
             raise AuthorizationError,
               "Dynamic client registration failed: #{e.class}: #{e.message}."
@@ -393,6 +466,20 @@ module MCP
           info
         end
 
+        # Returns the client metadata to submit on Dynamic Client Registration.
+        # Per SEP-837, MCP clients MUST specify an appropriate OIDC `application_type`
+        # so the authorization server can apply the matching redirect URI policy.
+        # When the user did not set one explicitly, infer `"native"` vs `"web"` from
+        # the registered `redirect_uris`; an explicit value always wins.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/837
+        def registration_client_metadata
+          metadata = @provider.client_metadata
+          return metadata if metadata[:application_type] || metadata["application_type"]
+
+          redirect_uris = metadata[:redirect_uris] || metadata["redirect_uris"]
+          metadata.merge("application_type" => Discovery.infer_application_type(redirect_uris))
+        end
+
         # Reads `key` from a `client_information` hash that may use either string or
         # symbol keys, so users can persist the result of `JSON.parse` *or* a hand-built
         # `{ client_id:, client_secret: }` and have both work.

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

@@ -13,6 +13,9 @@ module MCP
       # - `client_metadata`  - Hash sent to the authorization server's Dynamic Client
       #   Registration endpoint. Must include at minimum `redirect_uris`,
       #   `grant_types`, `response_types`, and `token_endpoint_auth_method`.
+      #   When `application_type` is omitted, the SDK infers `"native"` or `"web"`
+      #   from `redirect_uris` per SEP-837 before registering; an explicit value
+      #   always wins.
       # - `redirect_uri`     - String: the redirect URI used for the authorization
       #   request. Must be one of `redirect_uris` in `client_metadata`.
       # - `redirect_handler` - Callable invoked with the fully-built authorization

data/lib/mcp/client.rb

@@ -77,7 +77,9 @@ module MCP
     #
     # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
     # @param protocol_version [String, nil] Protocol version to offer.
-    # @param capabilities [Hash] Capabilities advertised by the client.
+    # @param capabilities [Hash] Capabilities advertised by the client. May include
+    #   an `extensions` member per SEP-2133, keyed by reverse-DNS extension identifiers,
+    #   e.g. `{ extensions: { "com.example/feature" => {} } }`.
     # @return [Hash, nil] The server's `InitializeResult`, or `nil` when the transport
     #   does not expose an explicit handshake.
     # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization

data/lib/mcp/server/capabilities.rb

@@ -6,6 +6,7 @@ module MCP
       def initialize(capabilities_hash = nil)
         @completions = nil
         @experimental = nil
+        @extensions = nil
         @logging = nil
         @prompts = nil
         @resources = nil
@@ -14,6 +15,7 @@ module MCP
         if capabilities_hash
           support_completions if capabilities_hash.key?(:completions)
           support_experimental(capabilities_hash[:experimental]) if capabilities_hash.key?(:experimental)
+          support_extensions(capabilities_hash[:extensions]) if capabilities_hash.key?(:extensions)
           support_logging if capabilities_hash.key?(:logging)
 
           if capabilities_hash.key?(:prompts)
@@ -45,6 +47,17 @@ module MCP
         @experimental = config || {}
       end
 
+      # Declares support for capability extensions per SEP-2133. Keys are
+      # extension identifiers using the reverse-DNS prefix convention
+      # (e.g. `"io.modelcontextprotocol/tasks"`, `"com.example/feature"`);
+      # values are arbitrary extension-defined configuration objects,
+      # with an empty hash meaning "supported with no settings".
+      # Repeated calls merge, so several extensions can be declared independently.
+      # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133
+      def support_extensions(extensions = {})
+        @extensions = (@extensions || {}).merge(extensions || {})
+      end
+
       def support_logging
         @logging ||= {}
       end
@@ -85,6 +98,7 @@ module MCP
         {
           completions: @completions,
           experimental: @experimental,
+          extensions: @extensions,
           logging: @logging,
           prompts: @prompts,
           resources: @resources,

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

@@ -85,8 +85,10 @@ module MCP
         end
 
         def send_notification(method, params = nil, session_id: nil, related_request_id: nil)
-          # Stateless mode doesn't support notifications
-          raise "Stateless mode does not support notifications" if @stateless
+          # Stateless mode has no streams to deliver notifications on. Report non-delivery instead of raising
+          # so the ephemeral per-request session's notify_* helpers (e.g. progress or log notifications from
+          # a tool handler) degrade gracefully rather than spamming the exception reporter on every call.
+          return false if @stateless
 
           notification = {
             jsonrpc: "2.0",
@@ -575,7 +577,9 @@ module MCP
         # `notifications/initialized`) through the server so it can update session state.
         def dispatch_notification(body_string, session_id)
           server_session = nil
-          if session_id && !@stateless
+          if @stateless
+            server_session = ephemeral_session
+          elsif session_id
             @mutex.synchronize do
               session = @sessions[session_id]
               server_session = session[:server_session] if session
@@ -611,9 +615,10 @@ module MCP
 
         def handle_initialization(body_string, body)
           session_id = nil
-          server_session = nil
 
-          unless @stateless
+          if @stateless
+            server_session = ephemeral_session
+          else
             session_id = SecureRandom.uuid
             server_session = ServerSession.new(server: @server, transport: self, session_id: session_id)
 
@@ -626,17 +631,13 @@ module MCP
             end
           end
 
-          response = if server_session
-            server_session.handle_json(body_string)
-          else
-            @server.handle_json(body_string)
-          end
+          response = server_session.handle_json(body_string)
 
           # If `Server#init` produced an error response (e.g., malformed JSON-RPC envelope),
           # `mark_initialized!` was never called. Discard the orphaned session and omit
           # the `Mcp-Session-Id` header so the client retries from a clean state instead of
           # reusing a never-initialized ID that would later look like a duplicate `initialize`.
-          if server_session && !server_session.initialized?
+          if session_id && !server_session.initialized?
             cleanup_session(session_id)
             session_id = nil
           end
@@ -657,15 +658,15 @@ module MCP
         def handle_regular_request(body_string, session_id, related_request_id: nil)
           server_session = nil
 
-          unless @stateless
-            if session_id
-              error_response = validate_and_touch_session(session_id)
-              return error_response if error_response
+          if @stateless
+            server_session = ephemeral_session
+          elsif session_id
+            error_response = validate_and_touch_session(session_id)
+            return error_response if error_response
 
-              @mutex.synchronize do
-                session = @sessions[session_id]
-                server_session = session[:server_session] if session
-              end
+            @mutex.synchronize do
+              session = @sessions[session_id]
+              server_session = session[:server_session] if session
             end
           end
 
@@ -775,6 +776,13 @@ module MCP
           @mutex.synchronize { @sessions.key?(session_id) }
         end
 
+        # Each stateless POST is self-contained (SEP-2567): handlers run against an ephemeral per-request `ServerSession`
+        # so client info, logging level, and initialized state never leak onto the shared `Server` instance or across concurrent requests.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567
+        def ephemeral_session
+          ServerSession.new(server: @server, transport: self, session_id: nil)
+        end
+
         # Returns true iff a session exists and is not past its idle timeout. Expired sessions
         # are evicted as a side effect so a live request never observes a zombie session that
         # the reaper hasn't yet pruned. Does NOT update `last_active_at`; callers that are

data/lib/mcp/server.rb

@@ -8,6 +8,7 @@ require_relative "methods"
 require_relative "logging_message_notification"
 require_relative "progress"
 require_relative "server_context"
+require_relative "server/capabilities"
 require_relative "server/pagination"
 require_relative "server/transports"
 
@@ -142,7 +143,12 @@ module MCP
 
       validate!
 
-      @capabilities = capabilities || default_capabilities
+      # Accept either a plain Hash or an `MCP::Server::Capabilities` builder.
+      @capabilities = if capabilities.is_a?(Capabilities)
+        capabilities.to_h
+      else
+        capabilities || default_capabilities
+      end
       @client_capabilities = nil
       @logging_message_notification = nil
 
@@ -810,6 +816,10 @@ module MCP
     end
 
     def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil, cancellation: nil)
+      # Transports parse incoming JSON with `symbolize_names: true`, so `arguments` already arrives symbolized
+      # at every nesting level. This top-level transform only guards callers that hand in string-keyed top-level arguments;
+      # it does not recurse, and nested object keys remain symbols. Tools therefore receive symbol keys all the way down.
+      # See docs/building-servers.md ("Tool argument keys").
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))

data/lib/mcp/version.rb

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

metadata

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