mcp 0.19.0 → 0.21.0

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",
@@ -389,7 +391,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 +519,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 +541,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 +553,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)
@@ -567,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
@@ -603,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)
 
@@ -618,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
@@ -649,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
 
@@ -767,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
@@ -793,15 +809,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 +849,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

@@ -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"
 
@@ -58,6 +59,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
 
@@ -116,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
 
@@ -784,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))
@@ -846,7 +882,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.21.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.21.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.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