mcp 0.19.0 → 0.21.0

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

@@ -38,27 +38,28 @@ 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 = 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)
+          end
 
-          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)
           ensure_pkce_supported!(as_metadata)
 
           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)
@@ -92,14 +93,46 @@ module MCP
           :authorized
         end
 
-        # Exchanges the saved `refresh_token` for a fresh access token (RFC 6749
-        # Section 6). Re-discovers PRM and AS metadata so we always pick up a moved
-        # token endpoint, and re-runs the audience / issuer / security checks
-        # before talking to it.
+        # Runs the OAuth 2.1 `client_credentials` grant (machine-to-machine, no user interaction) and persists
+        # the resulting token. Shares the same discovery and security checks as `run!`; the only difference is
+        # the grant exchanged at the token endpoint. There is no PKCE, redirect, or authorization request,
+        # and no `offline_access` augmentation because the grant does not issue a refresh token (OAuth 2.1 Section 4.3.3).
+        # The pre-registered `client_id` / `client_secret` come from the provider's stored `client_information`.
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
+        def run_client_credentials!(as_metadata:, prm:, resource:, scope:)
+          client_info = client_credentials_client_info
+
+          form = { "grant_type" => "client_credentials" }
+          effective_scope = resolve_scope(scope: scope, prm: prm)
+          form["scope"] = effective_scope if effective_scope
+          form["resource"] = resource if resource
+
+          tokens = post_to_token_endpoint(as_metadata: as_metadata, client_info: client_info, form: form)
+          @provider.save_tokens(tokens)
+          :authorized
+        end
+
+        # Reads the pre-registered credentials for the `client_credentials` grant directly from the provider's stored
+        # `client_information`, rather than going through `ensure_client_registered` (which targets the authorization-code
+        # flow and reaches for `Provider`-only methods like `client_metadata` and `client_id_metadata_document_url`).
+        # The grant is for confidential clients, so a missing `client_id` is a clean configuration error, not a fallback
+        # to dynamic registration.
+        def client_credentials_client_info
+          info = @provider.client_information
+          unless info.is_a?(Hash) && client_info_required_value(info, "client_id")
+            raise AuthorizationError,
+              "Cannot run the client_credentials grant: the provider has no stored `client_id`."
+          end
+
+          info
+        end
+
+        # Exchanges the saved `refresh_token` for a fresh access token (RFC 6749 Section 6).
+        # Re-discovers PRM and AS metadata so we always pick up a moved token endpoint, and re-runs the audience / issuer / security
+        # checks before talking to it.
         #
-        # Returns `:refreshed` on success. Raises `AuthorizationError` when
-        # the provider has no refresh token, no client information, or when
-        # the token endpoint refuses the refresh request.
+        # Returns `:refreshed` on success. Raises `AuthorizationError` when the provider has no refresh token, no client information,
+        # or when the token endpoint refuses the refresh request.
         # https://www.rfc-editor.org/rfc/rfc6749#section-6
         def refresh!(server_url:, resource_metadata_url: nil)
           refresh_token = read_token("refresh_token")
@@ -110,8 +143,7 @@ module MCP
 
           # 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.
+          # 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
@@ -122,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,
@@ -185,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")
@@ -331,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}."
@@ -357,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.
@@ -484,6 +607,18 @@ module MCP
           Array(grant_types).include?("refresh_token")
         end
 
+        # The OAuth flow the provider drives. Dispatching on the provider's
+        # declared flow keeps `Flow` from second-guessing intent by parsing
+        # `client_metadata[:grant_types]` (which is protocol metadata for the
+        # authorization server, not an SDK control signal). A provider that
+        # predates this method is treated as the interactive authorization-code
+        # flow it was the only option for.
+        def provider_authorization_flow
+          return :authorization_code unless @provider.respond_to?(:authorization_flow)
+
+          @provider.authorization_flow
+        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

@@ -3,14 +3,19 @@
 module MCP
   class Client
     module OAuth
-      # Pluggable OAuth client configuration handed to `MCP::Client::HTTP` via
-      # the `oauth:` keyword. Inspired by the OAuthClientProvider in the TypeScript SDK
-      # and httpx.Auth-based provider in the Python SDK.
+      # Pluggable OAuth client configuration for the OAuth 2.1 Authorization Code + PKCE flow,
+      # handed to `MCP::Client::HTTP` via the `oauth:` keyword.
+      # Inspired by the OAuthClientProvider in the TypeScript SDK and the httpx.Auth-based provider
+      # in the Python SDK. For the non-interactive machine-to-machine `client_credentials` grant,
+      # use `ClientCredentialsProvider` instead.
       #
       # Required keyword arguments:
       # - `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
@@ -36,6 +41,8 @@ module MCP
       #   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
+        include StorageBackedProvider
+
         # Raised when `Provider#initialize` is called with a `redirect_uri` that
         # is neither HTTPS nor a loopback `http://` URL, per the MCP
         # authorization spec's Communication Security requirement.
@@ -102,28 +109,11 @@ module MCP
           @client_id_metadata_document_url = client_id_metadata_document_url
         end
 
-        def access_token
-          tokens&.dig("access_token") || tokens&.dig(:access_token)
-        end
-
-        def tokens
-          @storage.tokens
-        end
-
-        def save_tokens(tokens)
-          @storage.save_tokens(tokens)
-        end
-
-        def client_information
-          @storage.client_information
-        end
-
-        def save_client_information(info)
-          @storage.save_client_information(info)
-        end
-
-        def clear_tokens!
-          @storage.save_tokens(nil)
+        # Identifies the OAuth flow this provider drives.
+        # `Flow` dispatches on this rather than inspecting `client_metadata[:grant_types]`,
+        # which is protocol metadata for the authorization server, not an SDK control signal.
+        def authorization_flow
+          :authorization_code
         end
       end
     end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # Shared token/credential persistence for the OAuth provider classes
+      # (`Provider` for the authorization-code flow and `ClientCredentialsProvider`
+      # for the client_credentials flow). The two grants differ in how they authenticate,
+      # but both read and write the same two pieces of state through a `storage` object:
+      # the token response and the client information. This module supplies that delegation
+      # so the `Flow` orchestrator can treat any provider uniformly.
+      #
+      # Including classes must set `@storage` to an object responding to `tokens`,
+      # `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`
+      # (see `InMemoryStorage`).
+      module StorageBackedProvider
+        def access_token
+          tokens&.dig("access_token") || tokens&.dig(:access_token)
+        end
+
+        def tokens
+          @storage.tokens
+        end
+
+        def save_tokens(tokens)
+          @storage.save_tokens(tokens)
+        end
+
+        def client_information
+          @storage.client_information
+        end
+
+        def save_client_information(info)
+          @storage.save_client_information(info)
+        end
+
+        def clear_tokens!
+          @storage.save_tokens(nil)
+        end
+      end
+    end
+  end
+end

data/lib/mcp/client/oauth.rb

@@ -4,13 +4,15 @@ require_relative "oauth/discovery"
 require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"
 require_relative "oauth/pkce"
+require_relative "oauth/storage_backed_provider"
 require_relative "oauth/provider"
+require_relative "oauth/client_credentials_provider"
 
 module MCP
   class Client
     # OAuth client support for the MCP Authorization spec (PRM discovery,
     # Authorization Server metadata discovery, Dynamic Client Registration,
-    # OAuth 2.1 Authorization Code + PKCE).
+    # OAuth 2.1 Authorization Code + PKCE, and the client_credentials grant).
     # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
     module OAuth
     end

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
@@ -103,6 +105,8 @@ module MCP
     # Returns a single page of tools from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListToolsResult] Result with `tools` (Array<MCP::Client::Tool>)
     #   and `next_cursor` (String or nil).
     #
@@ -114,9 +118,9 @@ module MCP
     #     cursor = page.next_cursor
     #     break unless cursor
     #   end
-    def list_tools(cursor: nil)
+    def list_tools(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "tools/list", params: params)
+      response = request(method: "tools/list", params: params, meta: meta)
       result = response["result"] || {}
 
       tools = (result["tools"] || []).map do |tool|
@@ -152,11 +156,13 @@ module MCP
     # Returns a single page of resources from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListResourcesResult] Result with `resources` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_resources(cursor: nil)
+    def list_resources(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/list", params: params)
+      response = request(method: "resources/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListResourcesResult.new(
@@ -181,11 +187,13 @@ module MCP
     # Returns a single page of resource templates from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListResourceTemplatesResult] Result with `resource_templates`
     #   (Array<Hash>) and `next_cursor` (String or nil).
-    def list_resource_templates(cursor: nil)
+    def list_resource_templates(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/templates/list", params: params)
+      response = request(method: "resources/templates/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListResourceTemplatesResult.new(
@@ -210,11 +218,13 @@ module MCP
     # Returns a single page of prompts from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListPromptsResult] Result with `prompts` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_prompts(cursor: nil)
+    def list_prompts(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "prompts/list", params: params)
+      response = request(method: "prompts/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListPromptsResult.new(
@@ -242,6 +252,10 @@ module MCP
     # @param tool [MCP::Client::Tool] The tool to be called.
     # @param arguments [Object, nil] The arguments to pass to the tool.
     # @param progress_token [String, Integer, nil] A token to request progress notifications from the server during tool execution.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. the W3C Trace Context keys reserved by SEP-414
+    #   (`MCP::TraceContext::TRACEPARENT_META_KEY`, `tracestate`, `baggage`).
+    #   `progress_token` takes precedence over a `progressToken` entry in `meta`.
     # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example Call by name
@@ -256,14 +270,17 @@ module MCP
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
-    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil)
+    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil)
       tool_name = name || tool&.name
       raise ArgumentError, "Either `name:` or `tool:` must be provided." unless tool_name
 
       params = { name: tool_name, arguments: arguments }
+      meta_entries = meta ? meta.dup : {}
       if progress_token
-        params[:_meta] = { progressToken: progress_token }
+        meta_entries.delete("progressToken")
+        meta_entries[:progressToken] = progress_token
       end
+      params[:_meta] = meta_entries unless meta_entries.empty?
 
       request(method: "tools/call", params: params)
     end
@@ -271,9 +288,11 @@ module MCP
     # Reads a resource from the server by URI and returns the contents.
     #
     # @param uri [String] The URI of the resource to read.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Array<Hash>] An array of resource contents (text or blob).
-    def read_resource(uri:)
-      response = request(method: "resources/read", params: { uri: uri })
+    def read_resource(uri:, meta: nil)
+      response = request(method: "resources/read", params: { uri: uri }, meta: meta)
 
       response.dig("result", "contents") || []
     end
@@ -281,9 +300,11 @@ module MCP
     # Gets a prompt from the server by name and returns its details.
     #
     # @param name [String] The name of the prompt to get.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Hash] A hash containing the prompt details.
-    def get_prompt(name:)
-      response = request(method: "prompts/get", params: { name: name })
+    def get_prompt(name:, meta: nil)
+      response = request(method: "prompts/get", params: { name: name }, meta: meta)
 
       response.fetch("result", {})
     end
@@ -294,12 +315,14 @@ module MCP
     #   or `{ type: "ref/resource", uri: "file:///{path}" }`.
     # @param argument [Hash] The argument being completed, e.g. `{ name: "language", value: "py" }`.
     # @param context [Hash, nil] Optional context with previously resolved arguments.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Hash] The completion result with `"values"`, `"hasMore"`, and optionally `"total"`.
-    def complete(ref:, argument:, context: nil)
+    def complete(ref:, argument:, context: nil, meta: nil)
       params = { ref: ref, argument: argument }
       params[:context] = context if context
 
-      response = request(method: "completion/complete", params: params)
+      response = request(method: "completion/complete", params: params, meta: meta)
 
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
@@ -315,8 +338,8 @@ module MCP
     #   client.ping # => {}
     #
     # @see https://modelcontextprotocol.io/specification/latest/basic/utilities/ping
-    def ping
-      result = request(method: Methods::PING)["result"]
+    def ping(meta: nil)
+      result = request(method: Methods::PING, meta: meta)["result"]
       raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
 
       result
@@ -345,7 +368,13 @@ module MCP
       pages
     end
 
-    def request(method:, params: nil)
+    # Merges caller-supplied `meta` entries into the request params as `_meta`,
+    # without mutating the caller's hashes. Per SEP-414, `_meta` carries
+    # request-specific metadata such as W3C trace context (`traceparent`,
+    # `tracestate`, `baggage`); see {MCP::TraceContext}.
+    def request(method:, params: nil, meta: nil)
+      params = (params || {}).merge(_meta: meta) if meta && !meta.empty?
+
       request_body = {
         jsonrpc: JsonRpcHandler::Version::V2_0,
         id: request_id,

data/lib/mcp/configuration.rb

@@ -6,6 +6,7 @@ module MCP
     SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
       LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
     ]
+    DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26"
 
     attr_writer :exception_reporter, :around_request
 

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, :size, :meta
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :annotations, :size, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, size: nil, meta: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, size: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @annotations = annotations
       @size = size
       @meta = meta
     end
@@ -26,6 +27,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        annotations: annotations&.to_h,
         size: size,
         _meta: meta,
       }.compact

data/lib/mcp/resource_template.rb

@@ -2,15 +2,16 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :meta
+    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :annotations, :meta
 
-    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, meta: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @annotations = annotations
       @meta = meta
     end
 
@@ -22,6 +23,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        annotations: annotations&.to_h,
         _meta: meta,
       }.compact
     end