mcp 1.7.0 → 1.8.1

data/lib/mcp/server.rb

@@ -13,6 +13,7 @@ require_relative "protocol_deprecations"
 require_relative "server_context"
 require_relative "server/capabilities"
 require_relative "server/input_required_result"
+require_relative "server/oauth"
 require_relative "server/pagination"
 require_relative "server/pending_response"
 require_relative "server/request_state_security"
@@ -270,6 +271,9 @@ module MCP
         Methods::COMPLETION_COMPLETE => ->(_) { DEFAULT_COMPLETION_RESULT },
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
       }
+      # The protocol's own request methods, as opposed to the notifications above and to custom methods
+      # registered later: these need a request id to be run.
+      @protocol_request_methods = @handlers.keys.reject { |name| Methods.notification?(name) }.freeze
       @transport = transport
     end
 
@@ -279,10 +283,13 @@ module MCP
     # @param session [ServerSession, nil] Per-connection session. Passed by
     #   `ServerSession#handle` for session-scoped notification delivery.
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
+    # @param auth_info [Server::OAuth::AccessToken, nil] The verified access token
+    #   for the current request, passed by the transport layer and exposed to
+    #   handlers as `server_context.auth_info`.
     # @return [Hash, nil] The JSON-RPC response, or `nil` for notifications.
-    def handle(request, session: nil)
-      JsonRpcHandler.handle(request) do |method, request_id|
-        handle_request(request, method, session: session, related_request_id: request_id)
+    def handle(request, session: nil, auth_info: nil)
+      JsonRpcHandler.handle(request, id_validation_pattern: nil) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id, auth_info: auth_info)
       end
     end
 
@@ -292,10 +299,12 @@ module MCP
     # @param session [ServerSession, nil] Per-connection session. Passed by
     #   `ServerSession#handle_json` for session-scoped notification delivery.
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
+    # @param auth_info [Server::OAuth::AccessToken, nil] The verified access token
+    #   for the current request, as in `handle`.
     # @return [String, nil] The JSON-RPC response as JSON, or `nil` for notifications.
-    def handle_json(request, session: nil)
-      JsonRpcHandler.handle_json(request) do |method, request_id|
-        handle_request(request, method, session: session, related_request_id: request_id)
+    def handle_json(request, session: nil, auth_info: nil)
+      JsonRpcHandler.handle_json(request, id_validation_pattern: nil) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id, auth_info: auth_info)
       end
     end
 
@@ -600,7 +609,7 @@ module MCP
       end
     end
 
-    def handle_request(request, method, session: nil, related_request_id: nil)
+    def handle_request(request, method, session: nil, related_request_id: nil, auth_info: nil)
       # A well-formed notification carries no JSON-RPC id and receives no response.
       # If a client erroneously sends a notification-only method with an id, the message
       # is framed as a request; since notification methods have no request handler,
@@ -608,6 +617,12 @@ module MCP
       # the TypeScript and Python SDKs rather than emitting a spurious `result: null`.
       return if Methods.notification?(method) && !related_request_id.nil?
 
+      # The mirror case: a request method of the protocol sent without an id is framed as a notification,
+      # whose result the sender can never receive, so it is not run either; the TypeScript and Python servers
+      # drop such a message the same way, as a notification they have no handler for. A custom method keeps
+      # running without an id, since `define_custom_method` serves notifications too.
+      return if related_request_id.nil? && @protocol_request_methods.include?(method)
+
       # `notifications/cancelled` is dispatched directly: it is a notification (no JSON-RPC id)
       # and intentionally bypasses the `@handlers` lookup, capability check, in-flight registry,
       # and rescue blocks below.
@@ -639,10 +654,18 @@ module MCP
       begin
         Methods.ensure_capability!(method, capabilities)
       rescue Methods::MissingRequiredCapabilityError => e
-        # Re-raise through RequestHandlerError, the one channel whose message is
-        # deliberately surfaced to clients: `JsonRpcHandler`'s blind `rescue StandardError`
-        # no longer echoes exception messages into the error `data` member (CWE-209).
-        raise RequestHandlerError.new(e.message, request, error_type: :internal_error, original_error: e)
+        # A method of a capability the server does not declare is one the server does not implement, so it is answered as Method not found,
+        # which the TypeScript and Python servers return for a handler they never registered, and which the Streamable HTTP transport maps to
+        # 404 on the modern lifecycle. Re-raised through RequestHandlerError, the one channel whose message is deliberately surfaced to clients:
+        # `JsonRpcHandler`'s blind `rescue StandardError` no longer echoes exception messages into the error `data` member (CWE-209).
+        raise RequestHandlerError.new(
+          "Method not found",
+          request,
+          error_type: :method_not_found,
+          error_code: JsonRpcHandler::ErrorCode::METHOD_NOT_FOUND,
+          error_data: e.message,
+          original_error: e,
+        )
       end
 
       # `initialize` MUST NOT be cancelled (MCP spec 2025-11-25, cancellation item 2),
@@ -691,25 +714,25 @@ module MCP
           when Methods::INITIALIZE
             init(params, session: session)
           when Methods::RESOURCES_READ
-            contents = read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+            contents = read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope, auth_info: auth_info)
 
             # An SEP-2322 `input_required` result must not be wrapped as `contents` or stamped with SEP-2549 cache hints.
             contents.is_a?(InputRequiredResult) ? contents : build_read_resource_result(contents)
           when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
             validate_resource_subscription_params!(params)
-            handler_result = dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+            handler_result = dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope, auth_info: auth_info)
 
             subscription_result(handler_result)
           when Methods::TOOLS_CALL
-            call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+            call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope, auth_info: auth_info)
           when Methods::PROMPTS_GET
-            get_prompt(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+            get_prompt(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope, auth_info: auth_info)
           when Methods::COMPLETION_COMPLETE
-            complete(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+            complete(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope, auth_info: auth_info)
           when Methods::LOGGING_SET_LEVEL
             configure_logging_level(params, session: session)
           else
-            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
+            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope, auth_info: auth_info)
           end
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
@@ -760,6 +783,15 @@ module MCP
         rescue CancelledError => e
           add_instrumentation_data(cancelled: true, cancellation_reason: e.reason)
           next JsonRpcHandler::NO_RESPONSE
+        rescue OAuth::InsufficientScopeError => e
+          # A handler's `require_scopes!` failure is a client authorization error, not a server fault:
+          # surface it as an invalid-request JSON-RPC error whose message names the missing scopes.
+          # HTTP-level 403 challenges remain the transport `required_scopes` gate's job.
+          report_exception(e, { request: request })
+          add_instrumentation_data(error: :insufficient_scope)
+          converted = RequestHandlerError.new(e.message, request, error_type: :invalid_request, original_error: e)
+          reported_exception = converted
+          raise converted
         rescue RequestHandlerError => e
           report_exception(e.original_error || e, { request: request })
           add_instrumentation_data(error: e.error_type)
@@ -1116,7 +1148,7 @@ module MCP
 
       {
         protocolVersion: negotiated_version,
-        capabilities: capabilities,
+        capabilities: handshake_capabilities,
         serverInfo: info,
         instructions: response_instructions,
       }.compact
@@ -1193,6 +1225,19 @@ module MCP
     def discover_capabilities
       return capabilities if @transport.respond_to?(:serves_subscriptions_listen?) && @transport.serves_subscriptions_listen?
 
+      without_notification_flags(capabilities)
+    end
+
+    # Capabilities as advertised by `initialize`. A transport that delivers no notifications to its sessions
+    # (stateless Streamable HTTP) cannot keep the promise the `listChanged` and `subscribe` flags make, so they are
+    # left out, as `server/discover` leaves them out when `subscriptions/listen` is not served.
+    def handshake_capabilities
+      return capabilities unless @transport.respond_to?(:delivers_notifications?) && !@transport.delivers_notifications?
+
+      without_notification_flags(capabilities)
+    end
+
+    def without_notification_flags(capabilities)
       capabilities.each_with_object({}) do |(name, value), stripped|
         stripped[name] = if value.is_a?(Hash)
           value.reject { |flag, _| ["listChanged", "subscribe"].include?(flag.to_s) }
@@ -1224,7 +1269,7 @@ module MCP
       apply_cache_metadata({ tools: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
-    def call_tool(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
+    def call_tool(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -1259,12 +1304,13 @@ module MCP
       response = call_tool_with_args(
         tool,
         arguments,
-        server_context_with_meta(request),
+        server_context_with_meta(request, auth_info: auth_info),
         progress_token: progress_token,
         session: session,
         related_request_id: related_request_id,
         cancellation: cancellation,
         envelope: envelope,
+        auth_info: auth_info,
         retry_fields: mrtr_retry_fields(request),
       )
       # An SEP-2322 `input_required` result is not a tool result: output schema
@@ -1278,9 +1324,11 @@ module MCP
         result,
         content_provided: response.respond_to?(:content_provided?) && response.content_provided?,
       )
-    rescue RequestHandlerError, CancelledError
+    rescue RequestHandlerError, CancelledError, OAuth::InsufficientScopeError
       # CancelledError is intentionally not wrapped so `handle_request` can turn it into
-      # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
+      # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec, and
+      # `OAuth::InsufficientScopeError` so `require_scopes!` failures keep their
+      # scope-naming message instead of the generic internal-error shape.
       raise
     rescue => e
       # `e.message` is deliberately not included: it can carry internals (class, method
@@ -1300,7 +1348,7 @@ module MCP
       apply_cache_metadata({ prompts: page[:items], nextCursor: page[:next_cursor] }.compact)
     end
 
-    def get_prompt(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
+    def get_prompt(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
       prompt_name = request[:name]
       prompt = @prompts[prompt_name]
       unless prompt
@@ -1328,6 +1376,7 @@ module MCP
         related_request_id: related_request_id,
         cancellation: cancellation,
         envelope: envelope,
+        auth_info: auth_info,
       )
 
       call_prompt_template_with_args(prompt, prompt_args, server_context)
@@ -1440,7 +1489,7 @@ module MCP
       { ttlMs: @ttl_ms || 0, cacheScope: @cache_scope || "private" }.merge(result)
     end
 
-    def complete(params, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
+    def complete(params, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
       validate_completion_params!(params)
 
       result = dispatch_optional_context_handler(
@@ -1450,6 +1499,7 @@ module MCP
         related_request_id: related_request_id,
         cancellation: cancellation,
         envelope: envelope,
+        auth_info: auth_info,
       )
 
       normalize_completion_result(result)
@@ -1458,7 +1508,7 @@ module MCP
     # Invokes `resources/read` via the registered handler. If the handler block opts in to `server_context:`,
     # pass an `MCP::ServerContext` so the handler can observe cancellation via `server_context.cancelled?` or
     # `server_context.raise_if_cancelled!`.
-    def read_resource_contents(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
+    def read_resource_contents(request, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
       dispatch_optional_context_handler(
         @handlers[Methods::RESOURCES_READ],
         request,
@@ -1466,6 +1516,7 @@ module MCP
         related_request_id: related_request_id,
         cancellation: cancellation,
         envelope: envelope,
+        auth_info: auth_info,
       )
     end
 
@@ -1473,7 +1524,7 @@ module MCP
     # `completion_handler`, `resources_subscribe_handler`, `resources_unsubscribe_handler`, or `define_custom_method`.
     # Existing handlers that only accept `params` are called unchanged; handlers that declare a `server_context:`
     # keyword receive an `MCP::ServerContext` wrapping the raw server context with cancellation plumbing.
-    def dispatch_optional_context_handler(handler, params, session: nil, related_request_id: nil, cancellation: nil, envelope: nil)
+    def dispatch_optional_context_handler(handler, params, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
       return handler.call(params) unless handler_declares_server_context?(handler)
 
       server_context = build_server_context(
@@ -1482,6 +1533,7 @@ module MCP
         related_request_id: related_request_id,
         cancellation: cancellation,
         envelope: envelope,
+        auth_info: auth_info,
       )
       handler.call(params, server_context: server_context)
     end
@@ -1506,13 +1558,13 @@ module MCP
 
     # Builds an `MCP::ServerContext` used to give a handler access to session-scoped helpers
     # (progress, cancellation, nested server-to-client requests).
-    def build_server_context(request:, session:, related_request_id:, cancellation:, envelope: nil)
+    def build_server_context(request:, session:, related_request_id:, cancellation:, envelope: nil, auth_info: nil)
       meta_source = request.is_a?(Hash) ? request : {}
       progress_token = meta_source.dig(:_meta, :progressToken)
       progress = Progress.new(notification_target: session, progress_token: progress_token, related_request_id: related_request_id)
       retry_fields = mrtr_retry_fields(meta_source)
       ServerContext.new(
-        server_context_with_meta(meta_source),
+        server_context_with_meta(meta_source, auth_info: auth_info),
         progress: progress,
         notification_target: session,
         related_request_id: related_request_id,
@@ -1520,6 +1572,7 @@ module MCP
         envelope: envelope,
         input_responses: retry_fields[:input_responses],
         request_state: retry_fields[:request_state],
+        auth_info: auth_info,
       )
     end
 
@@ -1579,7 +1632,7 @@ module MCP
       end
     end
 
-    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, retry_fields: nil)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil, retry_fields: 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.
@@ -1597,6 +1650,7 @@ module MCP
           envelope: envelope,
           input_responses: retry_fields&.fetch(:input_responses, nil),
           request_state: retry_fields&.fetch(:request_state, nil),
+          auth_info: auth_info,
         )
         tool.call(**args, server_context: server_context)
       else
@@ -1614,15 +1668,18 @@ module MCP
       raw_result.is_a?(InputRequiredResult) ? raw_result : raw_result.to_h
     end
 
-    def server_context_with_meta(request)
+    def server_context_with_meta(request, auth_info: nil)
       meta = request[:_meta]
-      if meta && server_context.is_a?(Hash)
-        context = server_context.dup
-        context[:_meta] = meta
+      return server_context if meta.nil? && auth_info.nil?
+
+      if server_context.is_a?(Hash) || server_context.nil?
+        context = (server_context || {}).dup
+        context[:_meta] = meta if meta
+        context[:auth_info] = auth_info if auth_info
         context
-      elsif meta && server_context.nil?
-        { _meta: meta }
       else
+        # A custom (non-Hash) user context is passed through untouched; handlers on that path read
+        # the token via `server_context.auth_info` instead.
         server_context
       end
     end

data/lib/mcp/server_context.rb

@@ -15,8 +15,11 @@ module MCP
     # (the same access model as the envelope readers).
     attr_reader :input_responses, :request_state
 
-    def initialize(context, progress:, notification_target:, related_request_id: nil, cancellation: nil, envelope: nil,
-      input_responses: nil, request_state: nil)
+    # The verified `MCP::Server::OAuth::AccessToken` for the current request, or nil when the request was not bearer-authenticated.
+    # This reader is the canonical accessor; when the underlying context is a Hash the same value is also reachable as `server_context[:auth_info]`.
+    attr_reader :auth_info
+
+    def initialize(context, progress:, notification_target:, related_request_id: nil, cancellation: nil, envelope: nil, input_responses: nil, request_state: nil, auth_info: nil)
       @context = context
       @progress = progress
       @notification_target = notification_target
@@ -25,6 +28,7 @@ module MCP
       @envelope = envelope
       @input_responses = input_responses
       @request_state = request_state
+      @auth_info = auth_info
     end
 
     # Reads one entry of {#input_responses} by its `inputRequests` key, tolerating symbol or string keys.
@@ -89,6 +93,26 @@ module MCP
       raise Server::MissingRequiredClientCapabilityError, required
     end
 
+    # Whether the current request was bearer-authenticated.
+    def authenticated?
+      !@auth_info.nil?
+    end
+
+    # Guards the current operation on OAuth scopes the token must carry, for authorization decisions finer-grained than
+    # the transport-wide `required_scopes`. Raises `Server::OAuth::InsufficientScopeError`, which surfaces as
+    # a JSON-RPC invalid-request error naming the missing scopes. HTTP-level 403 step-up challenges remain the job of
+    # the transport's `required_scopes` gate, matching how the Python and TypeScript SDKs split endpoint-level challenges
+    # from in-handler authorization. The transport's `scope_matcher:` applies here as well: the authenticator attaches it
+    # to the token it hands over, so a scope hierarchy is judged the same way at the gate and in handlers.
+    def require_scopes!(*scopes)
+      raise ArgumentError, "at least one scope is required" if scopes.empty?
+
+      missing_scopes = scopes.reject { |scope| @auth_info&.scope?(scope) }
+      return if missing_scopes.empty?
+
+      raise Server::OAuth::InsufficientScopeError.new("Token is missing required scopes: #{missing_scopes.join(", ")}", required_scopes: scopes)
+    end
+
     # Reports progress for the current tool operation.
     # The notification is automatically scoped to the originating session.
     #

data/lib/mcp/server_session.rb

@@ -120,12 +120,22 @@ module MCP
       MCP.configuration.exception_reporter.call(e, { notification: "cancelled", request_id: request_id })
     end
 
-    def handle(request)
-      @server.handle(request, session: self)
+    # Accepts the request either as a positional Hash or as bare keyword arguments (`session.handle(jsonrpc: "2.0", ...)`),
+    # a calling style that predates this method having keyword parameters. `auth_info:` is honored only alongside a positional request:
+    # in the bare-keyword style every keyword belongs to the request body, and the body is attacker-authored JSON,
+    # so a captured `auth_info` keyword is folded back into the request rather than trusted as a verified credential.
+    def handle(request = nil, auth_info: nil, **request_keywords)
+      if request.nil?
+        request = request_keywords
+        request[:auth_info] = auth_info unless auth_info.nil?
+        auth_info = nil
+      end
+
+      @server.handle(request, session: self, auth_info: auth_info)
     end
 
-    def handle_json(request_json)
-      @server.handle_json(request_json, session: self)
+    def handle_json(request_json, auth_info: nil)
+      @server.handle_json(request_json, session: self, auth_info: auth_info)
     end
 
     # Called by `Server#init` during the initialization handshake.

data/lib/mcp/transport.rb

@@ -57,6 +57,14 @@ module MCP
       false
     end
 
+    # Whether the transport delivers notifications to a connected client outside the response to one of its
+    # requests (`notifications/*/list_changed`, `notifications/resources/updated`). `Server#init` strips the
+    # `listChanged`/`subscribe` capability flags when it does not, since the handshake would promise notifications
+    # the transport drops.
+    def delivers_notifications?
+      true
+    end
+
     private
 
     def generate_request_id

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.1
 platform: ruby
 authors:
 - Model Context Protocol
@@ -85,6 +85,17 @@ files:
 - lib/mcp/server.rb
 - lib/mcp/server/capabilities.rb
 - lib/mcp/server/input_required_result.rb
+- lib/mcp/server/oauth.rb
+- lib/mcp/server/oauth/access_token.rb
+- lib/mcp/server/oauth/authenticator.rb
+- lib/mcp/server/oauth/challenge.rb
+- lib/mcp/server/oauth/errors.rb
+- lib/mcp/server/oauth/introspection_verifier.rb
+- lib/mcp/server/oauth/jwt_verifier.rb
+- lib/mcp/server/oauth/middleware.rb
+- lib/mcp/server/oauth/protected_resource_metadata.rb
+- lib/mcp/server/oauth/protected_resource_metadata_middleware.rb
+- lib/mcp/server/oauth/token_verifier.rb
 - lib/mcp/server/pagination.rb
 - lib/mcp/server/pending_response.rb
 - lib/mcp/server/request_state_security.rb
@@ -108,7 +119,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.7.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.8.1
   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