mcp 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 959e38a26541c9681c11e8bc227e84c42d20e3d98de1568c0afd45c80f3b4474
-  data.tar.gz: e2bf6b0c7926e1803f9dff1279c1f5a35d96f1cf8a1e3c6141b22a97871c8ec2
+  metadata.gz: f1915f5e50dda558f3ba32d0c946dacafda7c0ee183300cd634632505ab206bd
+  data.tar.gz: 9f702e675c56e191effefa6a7a7ac5b4d5f3c0c8bded9284484bf7260b551f3b
 SHA512:
-  metadata.gz: 5f347a7259f4e728df5edad217d6963cb3428188e46244efd9be9908e84bf4a7134600c6f453249eedc87e33f998f3f51811922659f116811251a64d78f1bbee
-  data.tar.gz: 3d8d25f65c590d07157db74d87423bbde82250b5d99cf2e3182c8adbc198f534f96809265c8615160f49f963a3b2dc2a07a85db2f6f2cc83e11b068583f405de
+  metadata.gz: 76797292c1345c02d77b63b5d840bf9a39fe719e2df6a232a32a342d9e6974e296bc4e1a08939bba539ea56f9a00ab25cf225936ecd02cd1cee31fdfd7e39d48
+  data.tar.gz: f1063ce3c1781e713f556489b0a70d58d102b42d6f220b63a138b97a0532dbfd521b7aea428ed2811d94923bff39ab6f02cad0504ad0597c53e48676cb27984f

data/README.md

@@ -47,6 +47,7 @@ It implements the Model Context Protocol specification, handling model context r
 
 - `initialize` - Initializes the protocol and returns server capabilities
 - `ping` - Simple health check
+- `logging/setLevel` - Configures the minimum log level for the server
 - `tools/list` - Lists all registered tools and their schemas
 - `tools/call` - Invokes a specific tool with provided arguments
 - `prompts/list` - Lists all registered prompts and their schemas
@@ -260,6 +261,11 @@ See the relevant sections below for the arguments they receive.
 
 The MCP protocol supports a special [`_meta` parameter](https://modelcontextprotocol.io/specification/2025-06-18/basic#general-fields) in requests that allows clients to pass request-specific metadata. The server automatically extracts this parameter and makes it available to tools and prompts as a nested field within the `server_context`.
 
+> [!NOTE]
+> `_meta` is only merged when `server_context` is a `Hash` (or `nil`, in which case a new `{ _meta: ... }` hash is synthesized).
+> If you assign a non-`Hash` value to `server_context`, `_meta` is not merged and tools will not see it
+> under `server_context[:_meta]`. Keep `server_context` as a `Hash` if your tools need access to `_meta`.
+
 **Access Pattern:**
 
 When a client includes `_meta` in the request params, it becomes available as `server_context[:_meta]`:
@@ -300,6 +306,36 @@ end
 }
 ```
 
+**Distributed Tracing (W3C Trace Context):**
+
+Per SEP-414, the keys `traceparent`, `tracestate`, and `baggage` are reserved un-prefixed `_meta` keys for propagating
+[W3C Trace Context](https://www.w3.org/TR/trace-context/) across MCP requests. The SDK guarantees these keys pass through
+incoming request `_meta` untouched, and exposes their names as constants on `MCP::TraceContext` (`TRACEPARENT_META_KEY`,
+`TRACESTATE_META_KEY`, `BAGGAGE_META_KEY`, and `META_KEYS`). The SDK does not depend on OpenTelemetry; bridge the values
+to your tracing system yourself:
+
+```ruby
+class TracedTool < MCP::Tool
+  def self.call(message:, server_context:)
+    traceparent = server_context.dig(:_meta, :traceparent)
+    # Hand traceparent/tracestate/baggage to your tracing library
+    # (e.g. the opentelemetry-ruby gems) to continue the caller's trace.
+
+    MCP::Tool::Response.new([{ type: "text", text: "ok" }])
+  end
+end
+```
+
+On the client side, every request method (`call_tool`, `read_resource`, `get_prompt`, `complete`, `ping`, and the `list_*` methods)
+accepts a `meta:` keyword to inject these keys into the outgoing request, so trace context can flow on every request:
+
+```ruby
+meta = { MCP::TraceContext::TRACEPARENT_META_KEY => "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" }
+
+client.call_tool(tool: tool, arguments: { message: "Hello" }, meta: meta)
+client.read_resource(uri: "file:///report.txt", meta: meta)
+```
+
 #### Configuration Block Data
 
 ##### Exception Reporter
@@ -423,10 +459,10 @@ The exception reporter receives two arguments:
 - `exception`: The Ruby exception object that was raised
 - `server_context`: A hash containing contextual information about where the error occurred
 
-The server_context hash includes:
+The `server_context` hash includes:
 
-- For tool calls: `{ tool_name: "name", arguments: { ... } }`
-- For general request handling: `{ request: { ... } }`
+- For request handling failures: `{ request: { ... } }` (the raw JSON-RPC request hash)
+- For notification delivery failures: `{ notification: "tools_list_changed" }` (or the relevant notification name)
 
 When an exception occurs:
 
@@ -891,6 +927,19 @@ end
 
 otherwise `resources/read` requests will be a no-op.
 
+For unknown URIs, raise `MCP::Server::ResourceNotFoundError` from the handler.
+Per SEP-2164, the server then responds with the standard JSON-RPC Invalid Params error (`-32602`)
+carrying the requested URI in the error `data` member:
+
+```ruby
+server.resources_read_handler do |params|
+  resource = lookup(params[:uri])
+  raise MCP::Server::ResourceNotFoundError.new(params[:uri], params) unless resource
+
+  [{ uri: params[:uri], mimeType: resource.mime_type, text: resource.body }]
+end
+```
+
 ### Resource Templates
 
 The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
@@ -1913,6 +1962,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).
+- 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.
+  The refresh path is bypassed because refreshing would re-issue the same scope set the server just rejected. A `403` without that challenge is surfaced unchanged.
 - 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.
@@ -2014,6 +2066,29 @@ provider = MCP::Client::OAuth::Provider.new(
 )
 ```
 
+##### Client Credentials Grant
+
+For a confidential machine-to-machine client (no user, no browser redirect), use `MCP::Client::OAuth::ClientCredentialsProvider` instead of `Provider`.
+The transport discovers the authorization server the same way, then exchanges the OAuth 2.1 `client_credentials` grant (RFC 6749 Section 4.4) at
+the token endpoint. There is no authorization request, PKCE, or `offline_access`, because the grant does not issue a refresh token.
+
+```ruby
+provider = MCP::Client::OAuth::ClientCredentialsProvider.new(
+  client_id: "my-service",
+  client_secret: ENV.fetch("MCP_CLIENT_SECRET"),
+  # token_endpoint_auth_method: "client_secret_basic" (default) or "client_secret_post"
+  # scope: "mcp:read mcp:write" (optional; used when the server does not advertise scopes)
+)
+
+transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp", oauth: provider)
+```
+
+Keyword arguments:
+
+- `client_id`, `client_secret`: Required. The grant is for confidential clients, so a credential is mandatory.
+- `token_endpoint_auth_method`: `"client_secret_basic"` (default) or `"client_secret_post"`. `"none"` is rejected with `ClientCredentialsProvider::InvalidCredentialsError`.
+- `scope`, `storage`: Optional, same meaning as on `Provider`.
+
 ##### Communication Security
 
 When `oauth:` is set, the MCP transport URL and every OAuth-facing URL (PRM, Authorization Server metadata, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,

data/lib/json_rpc_handler.rb

@@ -73,13 +73,18 @@ module JsonRpcHandler
 
     error = if !valid_version?(request[:jsonrpc])
       "JSON-RPC version must be 2.0"
-    elsif !valid_id?(request[:id], id_validation_pattern)
+    elsif !valid_id?(id, id_validation_pattern)
       "Request ID must match validation pattern, or be an integer or null"
     elsif !valid_method_name?(request[:method])
       'Method name must be a string and not start with "rpc."'
     end
 
-    return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+    # Per JSON-RPC 2.0 (Response object, `id`), the error response must carry
+    # the same id as the request when the id could be detected; null is only
+    # for requests whose id could not be determined. `error_response` nils out
+    # ids that fail validation, and the `:unknown_id` sentinel keeps a response
+    # (with a null id) being emitted when the request carried no id at all.
+    return error_response(id: id.nil? ? :unknown_id : id, id_validation_pattern: id_validation_pattern, error: {
       code: ErrorCode::INVALID_REQUEST,
       message: "Invalid Request",
       data: error,

data/lib/mcp/client/http.rb

@@ -185,6 +185,7 @@ module MCP
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
         oauth_retried = false
+        step_up_retried = false
 
         begin
           response = client.post("", request, session_headers)
@@ -217,6 +218,19 @@ module MCP
             original_error: e,
           )
         rescue Faraday::ForbiddenError => e
+          # OAuth 2.0 step-up: a 403 carrying `error="insufficient_scope"` in
+          # the Bearer challenge means the existing access token is valid
+          # but lacks scopes the server now requires for this operation.
+          # Re-run the full authorization flow with the escalated scope from
+          # the challenge and retry once. A plain 403 without the challenge is
+          # surfaced unchanged.
+          if @oauth && !step_up_retried && insufficient_scope_challenge?(e)
+            step_up_retried = true
+            run_step_up_flow!(forbidden_error: e)
+
+            retry
+          end
+
           raise RequestHandlerError.new(
             "You are forbidden to make #{method} requests",
             { method: method, params: params },
@@ -337,16 +351,63 @@ module MCP
       #
       # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#error-handling
       def run_oauth_flow!(unauthorized_error:)
-        response = unauthorized_error.response || {}
-        response_headers = response[:headers] || {}
-        www_authenticate = response_headers["www-authenticate"] || response_headers["WWW-Authenticate"]
-        params = MCP::Client::OAuth::Discovery.parse_www_authenticate(www_authenticate)
+        params = parse_www_authenticate_from_error(unauthorized_error)
+        flow = MCP::Client::OAuth::Flow.new(provider: @oauth)
+        return if attempt_refresh(flow: flow, resource_metadata_url: params["resource_metadata"])
 
+        run_full_authorization_flow!(flow: flow, params: params)
+      end
+
+      # Drives a full Authorization Code + PKCE flow without first attempting
+      # to refresh the access token. Used for the MCP scope-selection-strategy
+      # step-up path: the provider already holds a valid access token,
+      # but the server returned a 403 with
+      # `WWW-Authenticate: ... error="insufficient_scope", scope="..."`
+      # per RFC 6750 Section 3.1. Refreshing the existing token would re-issue
+      # the same scope set the server already rejected, so the SDK must run
+      # a fresh authorization request. The request asks for the union of
+      # the currently granted scope and the newly demanded scope; otherwise
+      # the caller would lose previously held scopes and trigger another step-up
+      # on the next operation that needs them.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-selection-strategy
+      def run_step_up_flow!(forbidden_error:)
+        params = parse_www_authenticate_from_error(forbidden_error)
         flow = MCP::Client::OAuth::Flow.new(provider: @oauth)
-        if attempt_refresh(flow: flow, resource_metadata_url: params["resource_metadata"])
-          return
-        end
+        params = params.merge("scope" => escalated_step_up_scope(params["scope"]))
+
+        run_full_authorization_flow!(flow: flow, params: params)
+      end
+
+      # Returns the space-separated union of the currently granted scope (read
+      # from the stored token response per RFC 6749 Section 5.1) and the scope
+      # demanded by the step-up challenge. Duplicates are collapsed; order
+      # follows first appearance so existing scopes precede the newly added
+      # ones. Returns `nil` when neither side carries a scope so
+      # `build_authorization_url` omits the `scope` parameter entirely.
+      def escalated_step_up_scope(challenge_scope)
+        tokens = @oauth.tokens
+        granted = tokens.is_a?(Hash) ? (tokens["scope"] || tokens[:scope]) : nil
+        scopes = [granted, challenge_scope].compact.flat_map { |scope| scope.to_s.split }.uniq
+
+        scopes.empty? ? nil : scopes.join(" ")
+      end
+
+      # True when the response on `forbidden_error` carries a Bearer challenge
+      # with `error="insufficient_scope"` per RFC 6750 Section 3.1 and the MCP
+      # scope-selection-strategy section. A 403 without that signal is not a
+      # step-up challenge and must not trigger re-authorization.
+      def insufficient_scope_challenge?(forbidden_error)
+        parse_www_authenticate_from_error(forbidden_error)["error"] == "insufficient_scope"
+      end
+
+      def parse_www_authenticate_from_error(error)
+        response = error.response || {}
+        response_headers = response[:headers] || {}
+        header = response_headers["www-authenticate"] || response_headers["WWW-Authenticate"]
+        MCP::Client::OAuth::Discovery.parse_www_authenticate(header)
+      end
 
+      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.

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # OAuth client configuration for the OAuth 2.1 `client_credentials` grant
+      # (machine-to-machine, no user and no browser redirect). Handed to
+      # `MCP::Client::HTTP` via the `oauth:` keyword, the same as `Provider`.
+      # The interactive Authorization Code flow lives in `Provider`;
+      # this class exists so a credentials-only client never has to supply
+      # the redirect arguments that grant has no use for, mirroring the dedicated
+      # `ClientCredentialsProvider` in the TypeScript SDK and
+      # `ClientCredentialsOAuthProvider` in the Python SDK.
+      #
+      # Required keyword arguments:
+      #
+      # - `client_id`     - String identifying the pre-registered confidential client.
+      # - `client_secret` - String shared secret. The `client_credentials` grant
+      #   is for confidential clients, so a credential is mandatory.
+      #
+      # Optional keyword arguments:
+      #
+      # - `token_endpoint_auth_method` - `"client_secret_basic"` (default) or
+      #   `"client_secret_post"`. `"none"` is rejected: an unauthenticated
+      #   `client_credentials` request is meaningless.
+      # - `scope`   - String of space-separated scopes to request when the server's
+      #   `WWW-Authenticate` and the Protected Resource Metadata do not specify one.
+      # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
+      #   `client_information`, and `save_client_information(info)`. Defaults to
+      #   an `InMemoryStorage`. The `client_id` / `client_secret` are written
+      #   into it so the token exchange reads them through the same path as
+      #   a pre-registered authorization-code client.
+      class ClientCredentialsProvider
+        include StorageBackedProvider
+
+        # Raised when the credentials required for the `client_credentials` grant are
+        # missing or the requested client authentication method cannot carry them.
+        class InvalidCredentialsError < ArgumentError; end
+
+        SUPPORTED_AUTH_METHODS = ["client_secret_basic", "client_secret_post"].freeze
+
+        attr_reader :scope, :storage
+
+        def initialize(
+          client_id:,
+          client_secret:,
+          token_endpoint_auth_method: "client_secret_basic",
+          scope: nil,
+          storage: nil
+        )
+          if blank?(client_id)
+            raise InvalidCredentialsError, "client_id is required for the client_credentials grant."
+          end
+
+          unless SUPPORTED_AUTH_METHODS.include?(token_endpoint_auth_method)
+            raise InvalidCredentialsError,
+              "token_endpoint_auth_method must be one of #{SUPPORTED_AUTH_METHODS.inspect} for the " \
+                "client_credentials grant (got #{token_endpoint_auth_method.inspect}); an unauthenticated " \
+                "client_credentials request is not allowed."
+          end
+
+          if blank?(client_secret)
+            raise InvalidCredentialsError,
+              "client_secret is required for the client_credentials grant with #{token_endpoint_auth_method}."
+          end
+
+          @scope = scope
+          @storage = storage || InMemoryStorage.new
+          @storage.save_client_information(
+            "client_id" => client_id,
+            "client_secret" => client_secret,
+            "token_endpoint_auth_method" => token_endpoint_auth_method,
+          )
+        end
+
+        # See `Provider#authorization_flow`.
+        def authorization_flow
+          :client_credentials
+        end
+
+        private
+
+        def blank?(value)
+          value.nil? || (value.is_a?(String) && value.strip.empty?)
+        end
+      end
+    end
+  end
+end

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

@@ -90,7 +90,17 @@ module MCP
           end
 
           # Returns the candidate Authorization Server metadata URLs to probe, in priority order.
-          # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery
+          #
+          # Per SEP-2351, MCP uses the default `oauth-authorization-server` well-known URI suffix
+          # registered by RFC 8414 Section 7.3 and defines no application-specific suffix of its own.
+          # The OAuth candidates below therefore use only that default suffix
+          # (plus the `openid-configuration` suffix from OpenID Connect Discovery),
+          # both in the RFC 8414 Section 3.1 path-inserted form for issuers with a path component
+          # and in the root form for issuers without one.
+          #
+          # - https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery
+          # - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2351
+          # - https://www.rfc-editor.org/rfc/rfc8414#section-3.1
           def authorization_server_metadata_urls(issuer_url)
             uri = URI.parse(issuer_url)
             path = uri.path == "/" ? "" : uri.path.to_s

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

@@ -54,6 +54,11 @@ module MCP
           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)
+
+          if provider_authorization_flow == :client_credentials
+            return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
+          end
+
           ensure_pkce_supported!(as_metadata)
 
           client_info = ensure_client_registered(as_metadata: as_metadata)
@@ -92,14 +97,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 +147,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
@@ -484,6 +520,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,9 +3,11 @@
 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
@@ -36,6 +38,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 +106,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

@@ -103,6 +103,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 +116,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 +154,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 +185,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 +216,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 +250,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 +268,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 +286,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 +298,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 +313,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 +336,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 +366,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

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

@@ -389,7 +389,11 @@ module MCP
           end
         rescue StandardError => e
           MCP.configuration.exception_reporter.call(e, { request: body_string })
-          [500, { "Content-Type" => "application/json" }, [{ error: "Internal server error" }.to_json]]
+          json_rpc_error_response(
+            status: 500,
+            code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            message: "Internal server error",
+          )
         end
 
         def handle_get(request)
@@ -513,19 +517,19 @@ module MCP
           media_type = content_type&.split(";")&.first&.strip&.downcase
           return if media_type == "application/json"
 
-          [
-            415,
-            { "Content-Type" => "application/json" },
-            [{ error: "Unsupported Media Type: Content-Type must be application/json" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 415,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Unsupported Media Type: Content-Type must be application/json",
+          )
         end
 
         def not_acceptable_response(required_types)
-          [
-            406,
-            { "Content-Type" => "application/json" },
-            [{ error: "Not Acceptable: Accept header must include #{required_types.join(" and ")}" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 406,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Not Acceptable: Accept header must include #{required_types.join(" and ")}",
+          )
         end
 
         def parse_request_body(body_string)
@@ -535,7 +539,11 @@ module MCP
         end
 
         def invalid_json_response
-          [400, { "Content-Type" => "application/json" }, [{ error: "Invalid JSON" }.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::PARSE_ERROR,
+            message: "Parse error: Invalid JSON",
+          )
         end
 
         def initialize_request?(body)
@@ -543,20 +551,20 @@ module MCP
         end
 
         def validate_protocol_version_header(request)
-          header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"]
-          return if header_value.nil?
+          header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"] || MCP::Configuration::DEFAULT_NEGOTIATED_PROTOCOL_VERSION
           return if MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(header_value)
 
           supported = MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.join(", ")
-          body = {
-            jsonrpc: "2.0",
-            id: nil,
-            error: {
-              code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
-              message: "Bad Request: Unsupported protocol version: #{header_value}. Supported versions: #{supported}",
-            },
-          }
-          [400, { "Content-Type" => "application/json" }, [body.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Bad Request: Unsupported protocol version: #{header_value}. Supported versions: #{supported}",
+          )
+        end
+
+        def json_rpc_error_response(status:, code:, message:)
+          body = { jsonrpc: "2.0", id: nil, error: { code: code, message: message } }
+          [status, { "Content-Type" => "application/json" }, [body.to_json]]
         end
 
         def notification?(body)
@@ -793,15 +801,27 @@ module MCP
         end
 
         def method_not_allowed_response
-          [405, { "Content-Type" => "application/json" }, [{ error: "Method not allowed" }.to_json]]
+          json_rpc_error_response(
+            status: 405,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Method not allowed",
+          )
         end
 
         def missing_session_id_response
-          [400, { "Content-Type" => "application/json" }, [{ error: "Missing session ID" }.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Missing session ID",
+          )
         end
 
         def session_not_found_response
-          [404, { "Content-Type" => "application/json" }, [{ error: "Session not found" }.to_json]]
+          json_rpc_error_response(
+            status: 404,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Session not found",
+          )
         end
 
         def already_initialized_response(request_id)
@@ -821,11 +841,11 @@ module MCP
         end
 
         def session_already_connected_response
-          [
-            409,
-            { "Content-Type" => "application/json" },
-            [{ error: "Conflict: Only one SSE stream is allowed per session" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 409,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Conflict: Only one SSE stream is allowed per session",
+          )
         end
 
         def setup_sse_stream(session_id)

data/lib/mcp/server.rb

@@ -58,6 +58,32 @@ module MCP
       end
     end
 
+    # Raised when a requested resource URI does not exist. Per SEP-2164,
+    # resource-not-found errors use the standard JSON-RPC Invalid Params code (-32602)
+    # with the requested URI in the error `data` member. Raise this from
+    # a `resources_read_handler` block for unknown URIs:
+    #
+    #   server.resources_read_handler do |params|
+    #     raise MCP::Server::ResourceNotFoundError.new(params[:uri], params) unless known?(params[:uri])
+    #     do_something(params[:uri])
+    #   end
+    #
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2164
+    class ResourceNotFoundError < RequestHandlerError
+      def initialize(uri, request = nil)
+        # The explicit `error_code` keeps the descriptive message in the JSON-RPC
+        # error response; `error_type: :invalid_params` alone would replace it
+        # with the generic "Invalid params" string.
+        super(
+          "Resource not found: #{uri}",
+          request,
+          error_type: :invalid_params,
+          error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+          error_data: { uri: uri },
+        )
+      end
+    end
+
     class MethodAlreadyDefinedError < StandardError
       attr_reader :method_name
 
@@ -846,7 +872,7 @@ module MCP
         uri = ref[:uri]
         found = @resource_index.key?(uri) || @resource_templates.any? { |t| t.uri_template == uri }
         unless found
-          raise RequestHandlerError.new("Resource not found: #{uri}", params, error_type: :invalid_params)
+          raise ResourceNotFoundError.new(uri, params)
         end
       else
         raise RequestHandlerError.new("Invalid ref type: #{ref[:type]}", params, error_type: :invalid_params)

data/lib/mcp/tool/input_schema.rb

@@ -12,9 +12,9 @@ module MCP
       end
 
       def missing_required_arguments(arguments)
-        return [] unless schema[:required].is_a?(Array)
+        return [] unless @schema[:required].is_a?(Array)
 
-        (schema[:required] - arguments.keys.map(&:to_s))
+        (@schema[:required] - arguments.keys.map(&:to_s))
       end
 
       def validate_arguments(arguments)

data/lib/mcp/tool/schema.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "digest"
-require "json-schema"
+require "json_schemer"
 
 module MCP
   class Tool
@@ -38,11 +38,10 @@ module MCP
 
       # 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
-      # the `json-schema` gem does not yet support 2020-12.
+      # is still performed against the JSON Schema draft-04 metaschema.
       JSON_SCHEMA_2020_12_URI = "https://json-schema.org/draft/2020-12/schema"
 
-      attr_reader :schema
+      DRAFT4_META_SCHEMA_URI = "http://json-schema.org/draft-04/schema#"
 
       def initialize(schema = {})
         @schema = JSON.parse(JSON.dump(schema), symbolize_names: true)
@@ -51,7 +50,7 @@ module MCP
       end
 
       def ==(other)
-        other.is_a?(self.class) && schema == other.schema
+        other.is_a?(self.class) && @schema == other.instance_variable_get(:@schema)
       end
 
       def to_h
@@ -62,8 +61,38 @@ module MCP
 
       private
 
+      def stringify(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify(v) }
+        when Array
+          obj.map { |v| stringify(v) }
+        when Symbol
+          obj.to_s
+        else
+          obj
+        end
+      end
+
+      # Lazily built so a cache hit in `validate_schema!` avoids the schemer construction cost.
+      # Memoized per Schema instance because schema content is fixed at construction,
+      # so the compiled schemer is reusable across many `fully_validate` calls.
+      #
+      # `format: false` preserves the legacy behavior of the previous `json-schema` based implementation,
+      # which did not enforce `format` keywords. `RegexpError` from a malformed `pattern` is re-raised as
+      # `ArgumentError` so callers see the same exception class they used to.
+      def schemer
+        @schemer ||= JSONSchemer.schema(
+          stringify(schema_for_validation),
+          meta_schema: DRAFT4_META_SCHEMA_URI,
+          format: false,
+        )
+      rescue RegexpError => e
+        raise ArgumentError, "Invalid JSON Schema: #{e.message}"
+      end
+
       def fully_validate(data)
-        JSON::Validator.fully_validate(schema_for_validation, data)
+        schemer.validate(stringify(data)).map { |validation_error| validation_error.fetch("error") }
       end
 
       def validate_schema!
@@ -75,16 +104,7 @@ module MCP
         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,
-          accept_file: ->(path) { File.realpath(path.to_s).start_with?(gem_path) },
-        )
-        metaschema_path = Pathname.new(JSON::Validator.validator_for_name("draft4").metaschema)
-        # 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, target, schema_reader: schema_reader)
+        errors = schemer.validate_schema.map { |validation_error| validation_error.fetch("error") }
         if errors.any?
           raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"
         end
@@ -92,9 +112,8 @@ module MCP
         VALIDATION_CACHE.store(key)
       end
 
-      # The `json-schema` gem's draft-04 validator cannot resolve newer or unknown `$schema`
-      # dialect URIs. Strip the top-level `$schema` before validation so a dialect URI
-      # (whether SDK-injected by `to_h` or user-supplied) does not break the validator.
+      # `json_schemer` is pinned to the draft-04 metaschema, so strip top-level `$schema` before validation:
+      # this preserves the legacy behavior of ignoring the advertised dialect URI when the SDK validates schemas.
       def schema_for_validation
         return @schema unless @schema.key?(:"$schema")
 

data/lib/mcp/trace_context.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MCP
+  # Reserved `_meta` keys for W3C Trace Context propagation, per SEP-414.
+  #
+  # The MCP spec reserves the un-prefixed `_meta` keys `traceparent`, `tracestate`, and `baggage`
+  # (an explicit exception to the reverse-DNS prefix rule for `_meta` keys) so that clients and
+  # servers can propagate distributed-tracing context across MCP requests.
+  # The SDK guarantees these keys pass through incoming request `_meta` untouched; tool, prompt,
+  # and resource handlers can read them from `server_context[:_meta]` and bridge them to a tracing
+  # system such as the `opentelemetry-ruby` gems. The SDK itself does not depend on OpenTelemetry.
+  #
+  # - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414
+  # - https://www.w3.org/TR/trace-context/
+  # - https://www.w3.org/TR/baggage/
+  module TraceContext
+    TRACEPARENT_META_KEY = "traceparent"
+    TRACESTATE_META_KEY = "tracestate"
+    BAGGAGE_META_KEY = "baggage"
+
+    META_KEYS = [TRACEPARENT_META_KEY, TRACESTATE_META_KEY, BAGGAGE_META_KEY].freeze
+  end
+end

data/lib/mcp/version.rb

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

data/lib/mcp.rb

@@ -19,6 +19,7 @@ module MCP
   autoload :Server, "mcp/server"
   autoload :ServerSession, "mcp/server_session"
   autoload :Tool, "mcp/tool"
+  autoload :TraceContext, "mcp/trace_context"
 
   class << self
     def configure

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -10,19 +10,19 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: json-schema
+  name: json_schemer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '2.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '2.4'
 description: The official Ruby SDK for Model Context Protocol servers and clients
 email:
 - mcp-support@anthropic.com
@@ -42,11 +42,13 @@ files:
 - lib/mcp/client.rb
 - lib/mcp/client/http.rb
 - lib/mcp/client/oauth.rb
+- lib/mcp/client/oauth/client_credentials_provider.rb
 - lib/mcp/client/oauth/discovery.rb
 - lib/mcp/client/oauth/flow.rb
 - lib/mcp/client/oauth/in_memory_storage.rb
 - lib/mcp/client/oauth/pkce.rb
 - lib/mcp/client/oauth/provider.rb
+- lib/mcp/client/oauth/storage_backed_provider.rb
 - lib/mcp/client/paginated_result.rb
 - lib/mcp/client/stdio.rb
 - lib/mcp/client/tool.rb
@@ -80,6 +82,7 @@ files:
 - lib/mcp/tool/output_schema.rb
 - lib/mcp/tool/response.rb
 - lib/mcp/tool/schema.rb
+- lib/mcp/trace_context.rb
 - lib/mcp/transport.rb
 - lib/mcp/version.rb
 homepage: https://ruby.sdk.modelcontextprotocol.io
@@ -87,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.19.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.20.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