mcp 0.13.0 → 0.15.0

data/lib/mcp/server.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "../json_rpc_handler"
+require_relative "cancellation"
+require_relative "cancelled_error"
 require_relative "instrumentation"
 require_relative "methods"
 require_relative "logging_message_notification"
 require_relative "progress"
 require_relative "server_context"
+require_relative "server/pagination"
 require_relative "server/transports"
 
 module MCP
@@ -65,9 +68,10 @@ module MCP
     end
 
     include Instrumentation
+    include Pagination
 
     attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
-    attr_reader :client_capabilities
+    attr_reader :page_size, :client_capabilities
 
     def initialize(
       description: nil,
@@ -84,6 +88,7 @@ module MCP
       server_context: nil,
       configuration: nil,
       capabilities: nil,
+      page_size: nil,
       transport: nil
     )
       @description = description
@@ -100,6 +105,7 @@ module MCP
       @resource_templates = resource_templates
       @resource_index = index_resources_by_uri(resources)
       @server_context = server_context
+      self.page_size = page_size
       @configuration = MCP.configuration.merge(configuration)
       @client = nil
 
@@ -113,6 +119,8 @@ module MCP
         Methods::RESOURCES_LIST => method(:list_resources),
         Methods::RESOURCES_READ => method(:read_resource_no_content),
         Methods::RESOURCES_TEMPLATES_LIST => method(:list_resource_templates),
+        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
+        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
         Methods::TOOLS_LIST => method(:list_tools),
         Methods::TOOLS_CALL => method(:call_tool),
         Methods::PROMPTS_LIST => method(:list_prompts),
@@ -121,12 +129,9 @@ module MCP
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
         Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
+        Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED => ->(_) {},
         Methods::COMPLETION_COMPLETE => ->(_) { DEFAULT_COMPLETION_RESULT },
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
-
-        # No op handlers for currently unsupported methods
-        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
-        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
       }
       @transport = transport
     end
@@ -182,6 +187,14 @@ module MCP
       @handlers[method_name] = block
     end
 
+    def page_size=(page_size)
+      unless page_size.nil? || (page_size.is_a?(Integer) && page_size > 0)
+        raise ArgumentError, "page_size must be nil or a positive integer"
+      end
+
+      @page_size = page_size
+    end
+
     def notify_tools_list_changed
       return unless @transport
 
@@ -218,6 +231,14 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
+    # Sets a handler for `notifications/roots/list_changed` notifications.
+    # Called when a client notifies the server that its filesystem roots have changed.
+    #
+    # @yield [params] The notification params (typically `nil`).
+    def roots_list_changed_handler(&block)
+      @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
+    end
+
     # Sets a custom handler for `resources/read` requests.
     # The block receives the parsed request params and should return resource
     # contents. The return value is set as the `contents` field of the response.
@@ -237,6 +258,24 @@ module MCP
       @handlers[Methods::COMPLETION_COMPLETE] = block
     end
 
+    # Sets a custom handler for `resources/subscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_subscribe_handler(&block)
+      @handlers[Methods::RESOURCES_SUBSCRIBE] = block
+    end
+
+    # Sets a custom handler for `resources/unsubscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_unsubscribe_handler(&block)
+      @handlers[Methods::RESOURCES_UNSUBSCRIBE] = block
+    end
+
     def build_sampling_params(
       capabilities,
       messages:,
@@ -347,6 +386,13 @@ module MCP
     end
 
     def handle_request(request, method, session: nil, related_request_id: nil)
+      # `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.
+      if method == Methods::NOTIFICATIONS_CANCELLED
+        return ->(params) { handle_cancelled_notification(params, session: session) }
+      end
+
       handler = @handlers[method]
       unless handler
         instrument_call("unsupported_method", server_context: { request: request }) do
@@ -358,6 +404,12 @@ module MCP
 
       Methods.ensure_capability!(method, capabilities)
 
+      # `initialize` MUST NOT be cancelled (MCP spec 2025-11-25, cancellation item 2),
+      # so do not track it in the in-flight registry.
+      cancellation = if related_request_id && method != Methods::INITIALIZE
+        session&.register_in_flight(related_request_id)
+      end
+
       ->(params) {
         reported_exception = nil
         instrument_call(
@@ -368,29 +420,34 @@ module MCP
           result = case method
           when Methods::INITIALIZE
             init(params, session: session)
-          when Methods::TOOLS_LIST
-            { tools: @handlers[Methods::TOOLS_LIST].call(params) }
-          when Methods::PROMPTS_LIST
-            { prompts: @handlers[Methods::PROMPTS_LIST].call(params) }
-          when Methods::RESOURCES_LIST
-            { resources: @handlers[Methods::RESOURCES_LIST].call(params) }
           when Methods::RESOURCES_READ
-            { contents: @handlers[Methods::RESOURCES_READ].call(params) }
-          when Methods::RESOURCES_TEMPLATES_LIST
-            { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
+            { contents: read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation) }
+          when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
+            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+            {}
           when Methods::TOOLS_CALL
-            call_tool(params, session: session, related_request_id: related_request_id)
+            call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+          when Methods::PROMPTS_GET
+            get_prompt(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
           when Methods::COMPLETION_COMPLETE
-            complete(params)
+            complete(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
           when Methods::LOGGING_SET_LEVEL
             configure_logging_level(params, session: session)
           else
-            @handlers[method].call(params)
+            dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation)
           end
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
 
+          if cancellation&.cancelled?
+            add_instrumentation_data(cancelled: true, cancellation_reason: cancellation.reason)
+            next JsonRpcHandler::NO_RESPONSE
+          end
+
           result
+        rescue CancelledError => e
+          add_instrumentation_data(cancelled: true, cancellation_reason: e.reason)
+          next JsonRpcHandler::NO_RESPONSE
         rescue RequestHandlerError => e
           report_exception(e.original_error || e, { request: request })
           add_instrumentation_data(error: e.error_type)
@@ -402,10 +459,23 @@ module MCP
           wrapped = RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
           reported_exception = wrapped
           raise wrapped
+        ensure
+          session&.unregister_in_flight(related_request_id) if related_request_id
         end
       }
     end
 
+    def handle_cancelled_notification(params, session: nil)
+      return unless session
+      return unless params.is_a?(Hash)
+
+      request_id = params[:requestId] || params["requestId"]
+      return if request_id.nil?
+
+      reason = params[:reason] || params["reason"]
+      session.cancel_incoming(request_id: request_id, reason: reason)
+    end
+
     def default_capabilities
       {
         tools: { listChanged: true },
@@ -479,10 +549,12 @@ module MCP
     end
 
     def list_tools(request)
-      @tools.values.map(&:to_h)
+      page = paginate(@tools.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { tools: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
-    def call_tool(request, session: nil, related_request_id: nil)
+    def call_tool(request, session: nil, related_request_id: nil, cancellation: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -499,7 +571,7 @@ module MCP
         add_instrumentation_data(error: :missing_required_arguments)
 
         missing = tool.input_schema.missing_required_arguments(arguments).join(", ")
-        raise RequestHandlerError.new("Missing required arguments: #{missing}", request, error_type: :invalid_params)
+        return error_tool_response("Missing required arguments: #{missing}")
       end
 
       if configuration.validate_tool_call_arguments && tool.input_schema
@@ -508,14 +580,18 @@ module MCP
         rescue Tool::InputSchema::ValidationError => e
           add_instrumentation_data(error: :invalid_schema)
 
-          raise RequestHandlerError.new(e.message, request, error_type: :invalid_params)
+          return error_tool_response(e.message)
         end
       end
 
       progress_token = request.dig(:_meta, :progressToken)
 
-      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id)
-    rescue RequestHandlerError
+      call_tool_with_args(
+        tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id, cancellation: cancellation
+      )
+    rescue RequestHandlerError, CancelledError
+      # CancelledError is intentionally not wrapped so `handle_request` can turn it into
+      # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
       raise
     rescue => e
       raise RequestHandlerError.new(
@@ -527,10 +603,12 @@ module MCP
     end
 
     def list_prompts(request)
-      @prompts.values.map(&:to_h)
+      page = paginate(@prompts.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { prompts: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
-    def get_prompt(request)
+    def get_prompt(request, session: nil, related_request_id: nil, cancellation: nil)
       prompt_name = request[:name]
       prompt = @prompts[prompt_name]
       unless prompt
@@ -543,11 +621,20 @@ module MCP
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
 
-      call_prompt_template_with_args(prompt, prompt_args, server_context_with_meta(request))
+      server_context = build_server_context(
+        request: request,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+
+      call_prompt_template_with_args(prompt, prompt_args, server_context)
     end
 
     def list_resources(request)
-      @resources.map(&:to_h)
+      page = paginate(@resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resources: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     # Server implementation should set `resources_read_handler` to override no-op default
@@ -557,17 +644,87 @@ module MCP
     end
 
     def list_resource_templates(request)
-      @resource_templates.map(&:to_h)
+      page = paginate(@resource_templates, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resourceTemplates: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
-    def complete(params)
+    def complete(params, session: nil, related_request_id: nil, cancellation: nil)
       validate_completion_params!(params)
 
-      result = @handlers[Methods::COMPLETION_COMPLETE].call(params)
+      result = dispatch_optional_context_handler(
+        @handlers[Methods::COMPLETION_COMPLETE],
+        params,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
 
       normalize_completion_result(result)
     end
 
+    # 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)
+      dispatch_optional_context_handler(
+        @handlers[Methods::RESOURCES_READ],
+        request,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+    end
+
+    # Opt-in `server_context:` dispatch for block-based handlers registered via `resources_read_handler`,
+    # `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)
+      return handler.call(params) unless handler_declares_server_context?(handler)
+
+      server_context = build_server_context(
+        request: params,
+        session: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+      handler.call(params, server_context: server_context)
+    end
+
+    # Stricter than `accepts_server_context?`: requires `server_context` to appear as a named keyword parameter
+    # (`:key` optional, `:keyreq` required). Positional parameters named `server_context` (`:req` / `:opt`) are NOT
+    # treated as opt-in - otherwise `handler.call(params, server_context: ctx)` would pass the `{server_context: ctx}`
+    # Hash as the handler's second positional argument, which is never what the user meant.
+    #
+    # `**kwargs`-only signatures (`:keyrest` without a named `server_context`) are also not opt-in here,
+    # because the dispatch site passes a positional `params`, and a `**kwargs`-only block cannot accept
+    # that positional argument (lambdas/methods raise `ArgumentError`; non-lambda procs silently drop `params`).
+    # Tool handlers intentionally allow `**kwargs` opt-in via `accepts_server_context?` because they are invoked
+    # via `tool.call(**args, server_context: …)` without a positional argument.
+    def handler_declares_server_context?(handler)
+      return false unless handler.respond_to?(:parameters)
+
+      handler.parameters.any? do |type, name|
+        name == :server_context && (type == :key || type == :keyreq)
+      end
+    end
+
+    # 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:)
+      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)
+      ServerContext.new(
+        server_context_with_meta(meta_source),
+        progress: progress,
+        notification_target: session,
+        related_request_id: related_request_id,
+        cancellation: cancellation,
+      )
+    end
+
     def report_exception(exception, server_context = {})
       configuration.exception_reporter.call(exception, server_context)
     end
@@ -588,18 +745,32 @@ module MCP
       ).to_h
     end
 
+    # Whether a tool/prompt handler opts in to receiving an `MCP::ServerContext`.
+    # Recognizes `:keyrest` (`**kwargs`) because tools are invoked without a positional argument
+    # (`tool.call(**args, server_context:)`), soa `**kwargs`-only signature safely captures `server_context:`.
+    # Named keyword `server_context` must be `:key` or `:keyreq` - positional parameters (`:req` / `:opt`) that
+    # happen to be named `server_context` are excluded because the call site passes `server_context:` as a keyword,
+    # and a positional slot would receive the `{server_context: ctx}` Hash instead.
     def accepts_server_context?(method_object)
       parameters = method_object.parameters
 
-      parameters.any? { |type, name| type == :keyrest || name == :server_context }
+      parameters.any? do |type, name|
+        type == :keyrest || (name == :server_context && (type == :key || type == :keyreq))
+      end
     end
 
-    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil, cancellation: nil)
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
         progress = Progress.new(notification_target: session, progress_token: progress_token, related_request_id: related_request_id)
-        server_context = ServerContext.new(context, progress: progress, notification_target: session, related_request_id: related_request_id)
+        server_context = ServerContext.new(
+          context,
+          progress: progress,
+          notification_target: session,
+          related_request_id: related_request_id,
+          cancellation: cancellation,
+        )
         tool.call(**args, server_context: server_context).to_h
       else
         tool.call(**args).to_h

data/lib/mcp/server_context.rb

@@ -2,11 +2,22 @@
 
 module MCP
   class ServerContext
-    def initialize(context, progress:, notification_target:, related_request_id: nil)
+    attr_reader :cancellation
+
+    def initialize(context, progress:, notification_target:, related_request_id: nil, cancellation: nil)
       @context = context
       @progress = progress
       @notification_target = notification_target
       @related_request_id = related_request_id
+      @cancellation = cancellation
+    end
+
+    def cancelled?
+      !!@cancellation&.cancelled?
+    end
+
+    def raise_if_cancelled!
+      @cancellation&.raise_if_cancelled!
     end
 
     # Reports progress for the current tool operation.
@@ -30,6 +41,24 @@ module MCP
       @notification_target.notify_log_message(data: data, level: level, logger: logger, related_request_id: @related_request_id)
     end
 
+    # Sends a resource updated notification scoped to the originating session.
+    #
+    # @param uri [String] The URI of the updated resource.
+    def notify_resources_updated(uri:)
+      return unless @notification_target
+
+      @notification_target.notify_resources_updated(uri: uri)
+    end
+
+    # Delegates to the session so the request is scoped to the originating client.
+    def list_roots
+      if @notification_target.respond_to?(:list_roots)
+        @notification_target.list_roots(related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'list_roots' for #{self}"
+      end
+    end
+
     # Delegates to the session so the request is scoped to the originating client.
     # Falls back to `@context` (via `method_missing`) when `@notification_target`
     # does not support sampling.

data/lib/mcp/server_session.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "cancellation"
 require_relative "methods"
 
 module MCP
@@ -15,6 +16,48 @@ module MCP
       @client = nil
       @client_capabilities = nil
       @logging_message_notification = nil
+      @in_flight = {}
+      @in_flight_mutex = Mutex.new
+    end
+
+    # Registers a `Cancellation` token for an in-flight request.
+    def register_in_flight(request_id)
+      return if request_id.nil?
+
+      cancellation = Cancellation.new(request_id: request_id)
+      @in_flight_mutex.synchronize { @in_flight[request_id] = cancellation }
+      cancellation
+    end
+
+    def unregister_in_flight(request_id)
+      return if request_id.nil?
+
+      @in_flight_mutex.synchronize { @in_flight.delete(request_id) }
+    end
+
+    def lookup_in_flight(request_id)
+      @in_flight_mutex.synchronize { @in_flight[request_id] }
+    end
+
+    # Flips the `Cancellation` for a matching in-flight request received from the peer.
+    # Silently ignores unknown IDs per MCP spec (cancellation utilities, item 5).
+    def cancel_incoming(request_id:, reason: nil)
+      cancellation = lookup_in_flight(request_id)
+      cancellation&.cancel(reason: reason)
+    end
+
+    # Sends `notifications/cancelled` to the peer for a previously-issued request.
+    # Also unblocks any transport-level `send_request` waiting on a response for `request_id`.
+    def cancel_request(request_id:, reason: nil)
+      params = { requestId: request_id }
+      params[:reason] = reason if reason
+      send_to_transport(Methods::NOTIFICATIONS_CANCELLED, params)
+
+      if @transport.respond_to?(:cancel_pending_request)
+        @transport.cancel_pending_request(request_id, reason: reason)
+      end
+    rescue => e
+      MCP.configuration.exception_reporter.call(e, { notification: "cancelled", request_id: request_id })
     end
 
     def handle(request)
@@ -41,6 +84,15 @@ module MCP
       @client_capabilities || @server.client_capabilities
     end
 
+    # Sends a `roots/list` request scoped to this session.
+    def list_roots(related_request_id: nil)
+      unless client_capabilities&.dig(:roots)
+        raise "Client does not support roots."
+      end
+
+      send_to_transport_request(Methods::ROOTS_LIST, nil, related_request_id: related_request_id)
+    end
+
     # Sends a `sampling/createMessage` request scoped to this session.
     def create_sampling_message(related_request_id: nil, **kwargs)
       params = @server.build_sampling_params(client_capabilities, **kwargs)
@@ -69,6 +121,23 @@ module MCP
       send_to_transport_request(Methods::ELICITATION_CREATE, params, related_request_id: related_request_id)
     end
 
+    # Sends `notifications/cancelled` to the peer for a nested server-to-client request
+    # that was started inside a now-cancelled parent request. `related_request_id`
+    # is the parent request id so the notification is routed to the same stream
+    # (e.g. the parent's POST response stream on `StreamableHTTPTransport`) rather than
+    # the GET SSE stream.
+    def send_peer_cancellation(nested_request_id:, related_request_id: nil, reason: nil)
+      params = { requestId: nested_request_id }
+      params[:reason] = reason if reason
+      send_to_transport(Methods::NOTIFICATIONS_CANCELLED, params, related_request_id: related_request_id)
+
+      if @transport.respond_to?(:cancel_pending_request)
+        @transport.cancel_pending_request(nested_request_id, reason: reason)
+      end
+    rescue => e
+      MCP.configuration.exception_reporter.call(e, { notification: "cancelled", request_id: nested_request_id })
+    end
+
     # Sends an elicitation complete notification scoped to this session.
     def notify_elicitation_complete(elicitation_id:)
       send_to_transport(Methods::NOTIFICATIONS_ELICITATION_COMPLETE, { elicitationId: elicitation_id })
@@ -76,6 +145,13 @@ module MCP
       @server.report_exception(e, notification: "elicitation_complete")
     end
 
+    # Sends a resource updated notification to this session only.
+    def notify_resources_updated(uri:)
+      send_to_transport(Methods::NOTIFICATIONS_RESOURCES_UPDATED, { "uri" => uri })
+    rescue => e
+      @server.report_exception(e, notification: "resources_updated")
+    end
+
     # Sends a progress notification to this session only.
     def notify_progress(progress_token:, progress:, total: nil, message: nil, related_request_id: nil)
       params = {
@@ -105,32 +181,57 @@ module MCP
 
     private
 
-    # Branches on `@session_id` because `StdioTransport` creates a `ServerSession` without
-    # a `session_id` (`session_id: nil`), while `StreamableHTTPTransport` always provides one.
-    #
-    # TODO: When Ruby 2.7 support is dropped, replace with a direct call:
-    # `@transport.send_notification(method, params, session_id: @session_id)` and
-    # add `**` to `Transport#send_notification` and `StdioTransport#send_notification`.
+    # Forwards `send_notification` to the transport with only the kwargs the transport's method signature
+    # actually accepts. Custom transports that implement the abstract `send_notification(method, params = nil)`
+    # contract continue to work unchanged; bundled transports that declare `session_id:` / `related_request_id:`
+    # receive the session-scoped routing information.
     def send_to_transport(method, params, related_request_id: nil)
-      if @session_id
-        @transport.send_notification(method, params, session_id: @session_id, related_request_id: related_request_id)
-      else
-        @transport.send_notification(method, params)
-      end
+      kwargs = {
+        session_id: @session_id,
+        related_request_id: related_request_id,
+      }.compact
+
+      forward_to_transport(@transport.method(:send_notification), method, params, kwargs)
     end
 
-    # Branches on `@session_id` because `StdioTransport` creates a `ServerSession` without
-    # a `session_id` (`session_id: nil`), while `StreamableHTTPTransport` always provides one.
-    #
-    # TODO: When Ruby 2.7 support is dropped, replace with a direct call:
-    # `@transport.send_request(method, params, session_id: @session_id)` and
-    # add `**` to `Transport#send_request` and `StdioTransport#send_request`.
+    # Forwards `send_request` to the transport with only the kwargs the transport's method signature
+    # actually accepts. Custom transports that implement the abstract `send_request(method, params = nil)`
+    # contract continue to work; bundled transports that declare `session_id:` / `related_request_id:` /
+    # `parent_cancellation:` / `server_session:` receive the nested-cancellation plumbing.
+    # When `related_request_id` names an in-flight request, its `Cancellation` token is looked up
+    # so that cancelling the parent also cancels this nested server-to-client request.
     def send_to_transport_request(method, params, related_request_id: nil)
-      if @session_id
-        @transport.send_request(method, params, session_id: @session_id, related_request_id: related_request_id)
+      parent_cancellation = related_request_id ? lookup_in_flight(related_request_id) : nil
+
+      kwargs = {
+        session_id: @session_id,
+        related_request_id: related_request_id,
+        parent_cancellation: parent_cancellation,
+        server_session: self,
+      }.compact
+
+      forward_to_transport(@transport.method(:send_request), method, params, kwargs)
+    end
+
+    # Calls `transport_method(method, params, **supported)` where `supported` contains only the keys
+    # the transport's method signature accepts. This keeps bundled transports (which declare the new kwargs)
+    # working while preserving compatibility with custom transports that implement only the abstract
+    # `(method, params = nil)` contract.
+    def forward_to_transport(transport_method, method, params, kwargs)
+      parameters = transport_method.parameters
+      accepts_keyrest = parameters.any? { |type, _| type == :keyrest }
+      supported = if accepts_keyrest
+        kwargs
       else
-        @transport.send_request(method, params)
+        allowed = parameters.filter_map { |type, name| name if type == :key || type == :keyreq }
+        kwargs.slice(*allowed)
       end
+
+      # Always splat `**supported` even when empty: on Ruby 2.7 the bare `transport_method.call(method, params)`
+      # form would let the trailing `params` Hash be auto-promoted to keyword arguments when the receiver
+      # accepts `**kwargs`, breaking handlers that rely on `params` arriving as a positional Hash.
+      # The explicit splat suppresses that conversion and is a no-op when `supported` is empty.
+      transport_method.call(method, params, **supported)
     end
   end
 end

data/lib/mcp/version.rb

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

data/lib/mcp.rb

@@ -8,6 +8,8 @@ require_relative "mcp/version"
 
 module MCP
   autoload :Annotations, "mcp/annotations"
+  autoload :Cancellation, "mcp/cancellation"
+  autoload :CancelledError, "mcp/cancelled_error"
   autoload :Client, "mcp/client"
   autoload :Content, "mcp/content"
   autoload :Icon, "mcp/icon"