mcp 0.10.0 → 0.14.0

data/lib/mcp/server.rb

@@ -6,6 +6,7 @@ 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
@@ -24,15 +25,34 @@ module MCP
     UNSUPPORTED_PROPERTIES_UNTIL_2025_06_18 = [:description, :icons].freeze
     UNSUPPORTED_PROPERTIES_UNTIL_2025_03_26 = [:title, :websiteUrl].freeze
 
+    DEFAULT_COMPLETION_RESULT = { completion: { values: [], hasMore: false } }.freeze
+
+    # Servers return an array of completion values ranked by relevance, with maximum 100 items per response.
+    # https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion#completion-results
+    MAX_COMPLETION_VALUES = 100
+
     class RequestHandlerError < StandardError
-      attr_reader :error_type
-      attr_reader :original_error
+      attr_reader :error_type, :original_error, :error_code, :error_data
 
-      def initialize(message, request, error_type: :internal_error, original_error: nil)
+      def initialize(message, request, error_type: :internal_error, original_error: nil, error_code: nil, error_data: nil)
         super(message)
         @request = request
         @error_type = error_type
         @original_error = original_error
+        @error_code = error_code
+        @error_data = error_data
+      end
+    end
+
+    class URLElicitationRequiredError < RequestHandlerError
+      def initialize(elicitations)
+        super(
+          "URL elicitation required",
+          nil,
+          error_type: :url_elicitation_required,
+          error_code: -32042,
+          error_data: { elicitations: elicitations },
+        )
       end
     end
 
@@ -46,8 +66,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 :page_size, :client_capabilities
 
     def initialize(
       description: nil,
@@ -64,6 +86,7 @@ module MCP
       server_context: nil,
       configuration: nil,
       capabilities: nil,
+      page_size: nil,
       transport: nil
     )
       @description = description
@@ -80,18 +103,22 @@ 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
 
       validate!
 
       @capabilities = capabilities || default_capabilities
+      @client_capabilities = nil
       @logging_message_notification = nil
 
       @handlers = {
         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),
@@ -100,13 +127,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 => ->(_) { {} },
-        Methods::COMPLETION_COMPLETE => ->(_) { { completion: { values: [], hasMore: false } } },
-        Methods::ELICITATION_CREATE => ->(_) {},
       }
       @transport = transport
     end
@@ -119,8 +142,8 @@ module MCP
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
     # @return [Hash, nil] The JSON-RPC response, or `nil` for notifications.
     def handle(request, session: nil)
-      JsonRpcHandler.handle(request) do |method|
-        handle_request(request, method, session: session)
+      JsonRpcHandler.handle(request) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
@@ -132,8 +155,8 @@ module MCP
     #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
     # @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|
-        handle_request(request, method, session: session)
+      JsonRpcHandler.handle_json(request) do |method, request_id|
+        handle_request(request, method, session: session, related_request_id: request_id)
       end
     end
 
@@ -162,6 +185,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
 
@@ -198,6 +229,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.
@@ -208,6 +247,72 @@ module MCP
       @handlers[Methods::RESOURCES_READ] = block
     end
 
+    # Sets a custom handler for `completion/complete` requests.
+    # The block receives the parsed request params and should return completion values.
+    #
+    # @yield [params] The request params containing `:ref`, `:argument`, and optionally `:context`.
+    # @yieldreturn [Hash] A hash with `:completion` key containing `:values`, optional `:total`, and `:hasMore`.
+    def completion_handler(&block)
+      @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:,
+      max_tokens:,
+      system_prompt: nil,
+      model_preferences: nil,
+      include_context: nil,
+      temperature: nil,
+      stop_sequences: nil,
+      metadata: nil,
+      tools: nil,
+      tool_choice: nil
+    )
+      unless capabilities&.dig(:sampling)
+        raise "Client does not support sampling."
+      end
+
+      if tools && !capabilities.dig(:sampling, :tools)
+        raise "Client does not support sampling with tools."
+      end
+
+      if tool_choice && !capabilities.dig(:sampling, :tools)
+        raise "Client does not support sampling with tool_choice."
+      end
+
+      {
+        messages: messages,
+        maxTokens: max_tokens,
+        systemPrompt: system_prompt,
+        modelPreferences: model_preferences,
+        includeContext: include_context,
+        temperature: temperature,
+        stopSequences: stop_sequences,
+        metadata: metadata,
+        tools: tools,
+        toolChoice: tool_choice,
+      }.compact
+    end
+
     private
 
     def validate!
@@ -278,10 +383,10 @@ module MCP
       end
     end
 
-    def handle_request(request, method, session: nil)
+    def handle_request(request, method, session: nil, related_request_id: nil)
       handler = @handlers[method]
       unless handler
-        instrument_call("unsupported_method") do
+        instrument_call("unsupported_method", server_context: { request: request }) do
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
         end
@@ -291,22 +396,24 @@ module MCP
       Methods.ensure_capability!(method, capabilities)
 
       ->(params) {
-        instrument_call(method) do
+        reported_exception = nil
+        instrument_call(
+          method,
+          server_context: { request: request },
+          exception_already_reported: ->(e) { reported_exception.equal?(e) },
+        ) do
           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) }
+          when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
+            @handlers[method].call(params)
+            {}
           when Methods::TOOLS_CALL
-            call_tool(params, session: session)
+            call_tool(params, session: session, related_request_id: related_request_id)
+          when Methods::COMPLETION_COMPLETE
+            complete(params)
           when Methods::LOGGING_SET_LEVEL
             configure_logging_level(params, session: session)
           else
@@ -316,15 +423,17 @@ module MCP
           add_instrumentation_data(client: client) if client
 
           result
+        rescue RequestHandlerError => e
+          report_exception(e.original_error || e, { request: request })
+          add_instrumentation_data(error: e.error_type)
+          reported_exception = e
+          raise e
         rescue => e
           report_exception(e, { request: request })
-          if e.is_a?(RequestHandlerError)
-            add_instrumentation_data(error: e.error_type)
-            raise e
-          end
-
           add_instrumentation_data(error: :internal_error)
-          raise RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+          wrapped = RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+          reported_exception = wrapped
+          raise wrapped
         end
       }
     end
@@ -355,10 +464,11 @@ module MCP
           session.store_client_info(client: params[:clientInfo], capabilities: params[:capabilities])
         else
           @client = params[:clientInfo]
+          @client_capabilities = params[:capabilities]
         end
+        protocol_version = params[:protocolVersion]
       end
 
-      protocol_version = params[:protocolVersion] if params
       negotiated_version = if Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
         protocol_version
       else
@@ -401,10 +511,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)
+    def call_tool(request, session: nil, related_request_id: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -421,7 +533,7 @@ module MCP
         add_instrumentation_data(error: :missing_required_arguments)
 
         missing = tool.input_schema.missing_required_arguments(arguments).join(", ")
-        return error_tool_response("Missing required arguments: #{missing}")
+        raise RequestHandlerError.new("Missing required arguments: #{missing}", request, error_type: :invalid_params)
       end
 
       if configuration.validate_tool_call_arguments && tool.input_schema
@@ -430,23 +542,28 @@ module MCP
         rescue Tool::InputSchema::ValidationError => e
           add_instrumentation_data(error: :invalid_schema)
 
-          return error_tool_response(e.message)
+          raise RequestHandlerError.new(e.message, request, error_type: :invalid_params)
         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)
+      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
       raise
     rescue => e
-      report_exception(e, request: request)
-
-      error_tool_response("Internal error calling tool #{tool_name}: #{e.message}")
+      raise RequestHandlerError.new(
+        "Internal error calling tool #{tool_name}: #{e.message}",
+        request,
+        error_type: :internal_error,
+        original_error: e,
+      )
     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)
@@ -466,7 +583,9 @@ module MCP
     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
@@ -476,7 +595,17 @@ 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)
+      validate_completion_params!(params)
+
+      result = @handlers[Methods::COMPLETION_COMPLETE].call(params)
+
+      normalize_completion_result(result)
     end
 
     def report_exception(exception, server_context = {})
@@ -505,12 +634,12 @@ module MCP
       parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil)
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
-        progress = Progress.new(notification_target: session, progress_token: progress_token)
-        server_context = ServerContext.new(context, progress: progress, notification_target: session)
+        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)
         tool.call(**args, server_context: server_context).to_h
       else
         tool.call(**args).to_h
@@ -537,5 +666,56 @@ module MCP
         server_context
       end
     end
+
+    def validate_completion_params!(params)
+      unless params.is_a?(Hash)
+        raise RequestHandlerError.new("Invalid params", params, error_type: :invalid_params)
+      end
+
+      ref = params[:ref]
+      if ref.nil? || ref[:type].nil?
+        raise RequestHandlerError.new("Missing or invalid ref", params, error_type: :invalid_params)
+      end
+
+      argument = params[:argument]
+      if argument.nil? || argument[:name].nil? || !argument.key?(:value)
+        raise RequestHandlerError.new("Missing argument name or value", params, error_type: :invalid_params)
+      end
+
+      case ref[:type]
+      when "ref/prompt"
+        unless @prompts[ref[:name]]
+          raise RequestHandlerError.new("Prompt not found: #{ref[:name]}", params, error_type: :invalid_params)
+        end
+      when "ref/resource"
+        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)
+        end
+      else
+        raise RequestHandlerError.new("Invalid ref type: #{ref[:type]}", params, error_type: :invalid_params)
+      end
+    end
+
+    def normalize_completion_result(result)
+      return DEFAULT_COMPLETION_RESULT unless result.is_a?(Hash)
+
+      completion = result[:completion] || result["completion"]
+      return DEFAULT_COMPLETION_RESULT unless completion.is_a?(Hash)
+
+      values = completion[:values] || completion["values"] || []
+      total = completion[:total] || completion["total"]
+      has_more = completion[:hasMore] || completion["hasMore"] || false
+
+      count = values.length
+      if count > MAX_COMPLETION_VALUES
+        has_more = true
+        total ||= count
+        values = values.first(MAX_COMPLETION_VALUES)
+      end
+
+      { completion: { values: values, total: total, hasMore: has_more }.compact }
+    end
   end
 end

data/lib/mcp/server_context.rb

@@ -2,10 +2,11 @@
 
 module MCP
   class ServerContext
-    def initialize(context, progress:, notification_target:)
+    def initialize(context, progress:, notification_target:, related_request_id: nil)
       @context = context
       @progress = progress
       @notification_target = notification_target
+      @related_request_id = related_request_id
     end
 
     # Reports progress for the current tool operation.
@@ -26,7 +27,74 @@ module MCP
     def notify_log_message(data:, level:, logger: nil)
       return unless @notification_target
 
-      @notification_target.notify_log_message(data: data, level: level, logger: logger)
+      @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.
+    def create_sampling_message(**kwargs)
+      if @notification_target.respond_to?(:create_sampling_message)
+        @notification_target.create_sampling_message(**kwargs, related_request_id: @related_request_id)
+      elsif @context.respond_to?(:create_sampling_message)
+        @context.create_sampling_message(**kwargs, related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'create_sampling_message' 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 elicitation.
+    def create_form_elicitation(**kwargs)
+      if @notification_target.respond_to?(:create_form_elicitation)
+        @notification_target.create_form_elicitation(**kwargs, related_request_id: @related_request_id)
+      elsif @context.respond_to?(:create_form_elicitation)
+        @context.create_form_elicitation(**kwargs, related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'create_form_elicitation' for #{self}"
+      end
+    end
+
+    # Delegates to the session so the request is scoped to the originating client.
+    # Falls back to `@context` when `@notification_target` does not support URL mode elicitation.
+    def create_url_elicitation(**kwargs)
+      if @notification_target.respond_to?(:create_url_elicitation)
+        @notification_target.create_url_elicitation(**kwargs, related_request_id: @related_request_id)
+      elsif @context.respond_to?(:create_url_elicitation)
+        @context.create_url_elicitation(**kwargs, related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'create_url_elicitation' for #{self}"
+      end
+    end
+
+    # Delegates to the session so the notification is scoped to the originating client.
+    def notify_elicitation_complete(**kwargs)
+      if @notification_target.respond_to?(:notify_elicitation_complete)
+        @notification_target.notify_elicitation_complete(**kwargs)
+      elsif @context.respond_to?(:notify_elicitation_complete)
+        @context.notify_elicitation_complete(**kwargs)
+      else
+        raise NoMethodError, "undefined method 'notify_elicitation_complete' for #{self}"
+      end
     end
 
     def method_missing(name, ...)

data/lib/mcp/server_session.rb

@@ -13,7 +13,7 @@ module MCP
       @transport = transport
       @session_id = session_id
       @client = nil
-      @client_capabilities = nil # TODO: Use for per-session capability validation.
+      @client_capabilities = nil
       @logging_message_notification = nil
     end
 
@@ -36,8 +36,64 @@ module MCP
       @logging_message_notification = logging_message_notification
     end
 
+    # Returns per-session client capabilities, falling back to global.
+    def client_capabilities
+      @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)
+      send_to_transport_request(Methods::SAMPLING_CREATE_MESSAGE, params, related_request_id: related_request_id)
+    end
+
+    # Sends an `elicitation/create` request (form mode) scoped to this session.
+    def create_form_elicitation(message:, requested_schema:, related_request_id: nil)
+      unless client_capabilities&.dig(:elicitation)
+        raise "Client does not support elicitation. " \
+          "The client must declare the `elicitation` capability during initialization."
+      end
+
+      params = { mode: "form", message: message, requestedSchema: requested_schema }
+      send_to_transport_request(Methods::ELICITATION_CREATE, params, related_request_id: related_request_id)
+    end
+
+    # Sends an `elicitation/create` request (URL mode) scoped to this session.
+    def create_url_elicitation(message:, url:, elicitation_id:, related_request_id: nil)
+      unless client_capabilities&.dig(:elicitation, :url)
+        raise "Client does not support URL mode elicitation. " \
+          "The client must declare the `elicitation.url` capability during initialization."
+      end
+
+      params = { mode: "url", message: message, url: url, elicitationId: elicitation_id }
+      send_to_transport_request(Methods::ELICITATION_CREATE, params, related_request_id: related_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 })
+    rescue => e
+      @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)
+    def notify_progress(progress_token:, progress:, total: nil, message: nil, related_request_id: nil)
       params = {
         "progressToken" => progress_token,
         "progress" => progress,
@@ -45,35 +101,52 @@ module MCP
         "message" => message,
       }.compact
 
-      send_to_transport(Methods::NOTIFICATIONS_PROGRESS, params)
+      send_to_transport(Methods::NOTIFICATIONS_PROGRESS, params, related_request_id: related_request_id)
     rescue => e
       @server.report_exception(e, notification: "progress")
     end
 
     # Sends a log message notification to this session only.
-    def notify_log_message(data:, level:, logger: nil)
+    def notify_log_message(data:, level:, logger: nil, related_request_id: nil)
       effective_logging = @logging_message_notification || @server.logging_message_notification
       return unless effective_logging&.should_notify?(level)
 
       params = { "data" => data, "level" => level }
       params["logger"] = logger if logger
 
-      send_to_transport(Methods::NOTIFICATIONS_MESSAGE, params)
+      send_to_transport(Methods::NOTIFICATIONS_MESSAGE, params, related_request_id: related_request_id)
     rescue => e
       @server.report_exception(e, { notification: "log_message" })
     end
 
     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`.
-    def send_to_transport(method, params)
+    def send_to_transport(method, params, related_request_id: nil)
       if @session_id
-        @transport.send_notification(method, params, session_id: @session_id)
+        @transport.send_notification(method, params, session_id: @session_id, related_request_id: related_request_id)
       else
         @transport.send_notification(method, params)
       end
     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`.
+    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)
+      else
+        @transport.send_request(method, params)
+      end
+    end
   end
 end