mcp 1.9.0 → 1.10.0

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

@@ -2,6 +2,7 @@
 
 require "json"
 require "set"
+require "timeout"
 require_relative "../../result_type"
 require_relative "../../transport"
 
@@ -188,6 +189,13 @@ module MCP
         # @param server_to_client_request_timeout [Numeric] seconds a server-to-client request waits for its
         #   response before the transport stops waiting and raises `MCP::Server::RequestTimeoutError`.
         #   Defaults to `DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT` (600); individual calls override it with `timeout:`.
+        # @param stream_write_timeout [Numeric, nil] seconds a notification, a server-to-client request, a listen
+        #   acknowledgement or a keepalive may take to be written to an SSE stream before the stream is dropped as stalled.
+        #   These writes are made on behalf of every stream in turn, so a peer that stops reading would otherwise hold
+        #   the writer, and the streams after it, for as long as its buffers stay full. The response of a request is not bounded:
+        #   it is written on that request's own thread and may be large. The bound is per stream, so several stalled streams delay
+        #   a notification by the sum of their waits, once each. Closing a stream is given the same number of seconds, once.
+        #   Defaults to `DEFAULT_STREAM_WRITE_TIMEOUT` (10); pass `nil` to wait without limit.
         # @param token_verifier [#verify, nil] enables built-in OAuth 2.1 bearer enforcement: anything responding to
         #   `verify(token) -> MCP::Server::OAuth::AccessToken | nil` (see `MCP::Server::OAuth::TokenVerifier` for
         #   the contract and the built-in JWT/introspection implementations). Every POST, GET, and DELETE is verified
@@ -227,6 +235,7 @@ module MCP
           listen_keepalive_interval: DEFAULT_LISTEN_KEEPALIVE_INTERVAL,
           serve_subscriptions_listen: true,
           server_to_client_request_timeout: DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT,
+          stream_write_timeout: DEFAULT_STREAM_WRITE_TIMEOUT,
           token_verifier: nil,
           required_scopes: [],
           resource_metadata: nil,
@@ -325,6 +334,15 @@ module MCP
 
           @server_to_client_request_timeout = server_to_client_request_timeout
 
+          unless stream_write_timeout.nil? || (stream_write_timeout.is_a?(Numeric) && stream_write_timeout.positive?)
+            raise ArgumentError, "stream_write_timeout must be a positive number or nil"
+          end
+
+          @stream_write_timeout = stream_write_timeout
+
+          # Keyed by identity and weak, so a stream is not kept alive for having been recorded here.
+          @streams_with_abandoned_close = ObjectSpace::WeakMap.new
+
           if token_verifier
             @oauth_authenticator = OAuth::Authenticator.new(
               token_verifier: token_verifier,
@@ -358,6 +376,14 @@ module MCP
         REQUIRED_POST_ACCEPT_TYPES_JSON = ["application/json"].freeze
         REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze
         STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
+
+        # Raised from a write the transport pushes onto an SSE stream when it has not finished within `stream_write_timeout:` seconds.
+        # An `IOError`, so every path that drops a stream on a failed write drops this one the same way.
+        class StreamWriteTimeoutError < IOError; end
+
+        # A write blocks only once the peer's socket buffers are full, which takes a reader already hundreds of kilobytes behind;
+        # one that still has not taken the frame after this long is dropped whether it stopped reading or is only that slow.
+        DEFAULT_STREAM_WRITE_TIMEOUT = 10
         SESSION_REAP_INTERVAL = 60
         # Seconds `close` waits for a reap in progress to finish closing its streams before it kills the reaper.
         REAPER_JOIN_TIMEOUT = 5
@@ -509,6 +535,20 @@ module MCP
           end
         end
 
+        # Sessions a server-wide log broadcast is offered to, each applying its own level or the server default.
+        # Public only so that `Server#notify_log_message` can call it. Custom transports may implement this hook;
+        # returning `nil` keeps the server-wide filter.
+        #
+        # @api private
+        # @return [Array<ServerSession>]
+        def logging_sessions
+          @mutex.synchronize do
+            @sessions.values.filter_map do |session|
+              session[:server_session] if session[:get_sse_stream]
+            end
+          end
+        end
+
         def send_notification(method, params = nil, session_id: nil, related_request_id: nil)
           # `subscriptions/listen` streams (SEP-2575) receive matching change notifications regardless of the delivery below:
           # a resource updated by one session's tool call changed globally, so modern subscribers hear about it too.
@@ -619,7 +659,7 @@ module MCP
         # Writes a notification to an SSE stream without holding `@mutex`. On a write error,
         # drops the broken stream and returns false; on success returns true.
         def write_notification(stream, notification, session_id, related_request_id)
-          send_to_stream(stream, notification)
+          push_to_stream(stream, notification)
           true
         rescue *STREAM_WRITE_ERRORS => e
           MCP.configuration.exception_reporter.call(e, { session_id: session_id, error: "Failed to send notification" })
@@ -722,7 +762,7 @@ module MCP
           sent = false
           if stream
             begin
-              send_to_stream(stream, request)
+              push_to_stream(stream, request)
               sent = true
             rescue *STREAM_WRITE_ERRORS
               drop_broken_stream(session_id, stream, related_request_id)
@@ -866,6 +906,41 @@ module MCP
           stream.flush
         end
 
+        # `send_to_stream` and `send_ping_to_stream` for the frames the transport pushes onto a stream on its own: a notification,
+        # a server-to-client request, a listen acknowledgement, a keepalive. One thread writes them to stream after stream,
+        # and a keepalive write holds its stream's write mutex, so a peer that stopped reading would stall the notifications of
+        # every other client, and each thread that sends one, for as long as its buffers stay full.
+        # The write is given `stream_write_timeout:` seconds; past that it fails as a write to a broken stream does, and the caller drops the stream.
+        #
+        # The deadline may cut a frame short, so the stream is closed here, before the error leaves: a listen stream is written under its write mutex,
+        # which the error releases on its way out, ahead of the caller's removal of the entry, and a writer waiting on that mutex would otherwise put
+        # its frame after the cut one. Closed first, every later write fails as on any closed stream. The entry of a listen stream, passed as `subscription`,
+        # is marked closed as well, still under its write mutex, so those writers skip it even when the close itself had to be abandoned.
+        #
+        #
+        # The deadline interrupts the write with the exception `Timeout` raises on its own, which no `rescue` of an `IOError` or a `StandardError` inside
+        # a stream implementation catches, and becomes `StreamWriteTimeoutError` only here, where it leaves the write.
+        def push_to_stream(stream, data, subscription: nil)
+          within_stream_write_timeout(stream, subscription) { send_to_stream(stream, data) }
+        end
+
+        def push_ping_to_stream(stream, subscription: nil)
+          within_stream_write_timeout(stream, subscription) { send_ping_to_stream(stream) }
+        end
+
+        def within_stream_write_timeout(stream, subscription, &block)
+          return yield unless @stream_write_timeout
+
+          begin
+            Timeout.timeout(@stream_write_timeout, &block)
+          rescue Timeout::Error
+            subscription[:closed] = true if subscription
+            close_stream_safely(stream)
+
+            raise StreamWriteTimeoutError, "SSE stream write did not finish within #{@stream_write_timeout} seconds"
+          end
+        end
+
         # Serves one request of the stateless modern lifecycle (MCP 2026-07-28, SEP-2575):
         # a single POST/JSON exchange with no session. The modern path never consults
         # `@stateless`, `@sessions`, or `@enable_json_response`, and never issues or accepts
@@ -905,9 +980,9 @@ module MCP
               message: "Unsupported protocol version",
               data: {
                 supported: MCP::Configuration::SUPPORTED_MODERN_PROTOCOL_VERSIONS,
-                requested: header_version,
+                requested: printable_value(header_version),
               },
-              id: body[:id],
+              id: echoable_id(body[:id]),
             )
           end
 
@@ -916,13 +991,20 @@ module MCP
               status: 400,
               code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
               message: "Bad Request: Mcp-Session-Id is not accepted in the modern lifecycle",
-              id: body[:id],
+              id: echoable_id(body[:id]),
             )
           end
 
           mismatch_error = validate_modern_headers(request, body, header_version)
           return mismatch_error if mismatch_error
 
+          # SEP-2243 custom headers: the `Mcp-Param-*` headers of a `tools/call` are checked against the body here,
+          # before dispatch, so a disagreement is refused without the tool ever running.
+          if body[:method] == Methods::TOOLS_CALL
+            param_error = validate_mcp_param_headers(request, body)
+            return param_error if param_error
+          end
+
           # `subscriptions/listen` is a long-lived notification stream served at the transport layer;
           # it never dispatches through `Server#handle`. A transport constructed with
           # `serve_subscriptions_listen: false` skips the interception, so the method falls through
@@ -983,7 +1065,7 @@ module MCP
           meta_version = params.is_a?(Hash) && params[:_meta].is_a?(Hash) ? params.dig(:_meta, :"io.modelcontextprotocol/protocolVersion") : nil
           if meta_version && meta_version != header_version
             return header_mismatch_response(
-              "MCP-Protocol-Version header value '#{header_version}' does not match body value '#{meta_version}'",
+              "MCP-Protocol-Version header value '#{printable_value(header_version)}' does not match body value '#{printable_value(meta_version)}'",
               body[:id],
             )
           end
@@ -1002,7 +1084,7 @@ module MCP
           end
           if method_header != body[:method]
             return header_mismatch_response(
-              "Mcp-Method header value '#{method_header}' does not match body value '#{body[:method]}'",
+              "Mcp-Method header value '#{printable_value(method_header)}' does not match body value '#{printable_value(body[:method])}'",
               body[:id],
             )
           end
@@ -1013,7 +1095,7 @@ module MCP
             if body_name
               if name_header.to_s.empty?
                 return header_mismatch_response(
-                  "Mcp-Name header is required for `#{body[:method]}`",
+                  "Mcp-Name header is required for `#{printable_value(body[:method])}`",
                   body[:id],
                 )
               end
@@ -1021,7 +1103,7 @@ module MCP
               decoded_name = decode_header_value(name_header)
               if decoded_name != body_name
                 return header_mismatch_response(
-                  "Mcp-Name header value '#{decoded_name}' does not match body value '#{body_name}'",
+                  "Mcp-Name header value '#{printable_value(decoded_name)}' does not match body value '#{printable_value(body_name)}'",
                   body[:id],
                 )
               end
@@ -1031,6 +1113,39 @@ module MCP
           nil
         end
 
+        # Enforces the SEP-2243 server behavior for custom headers (`-32020`, HTTP 400) on a modern `tools/call`: each
+        # `x-mcp-header` parameter of the called tool must have its `Mcp-Param-{Name}` header present exactly when the body
+        # carries a value for it, agreeing with that value once a `=?base64?...?=` sentinel is decoded, and a malformed
+        # sentinel is refused outright. The comparison runs before the tool does, on the schema the server itself serves
+        # in `tools/list`, so the body a handler acts on is the one an intermediary routed on. A tool the server does not
+        # know, or one whose declarations are invalid (a conforming client drops such a tool and sends no headers for it),
+        # is left to the dispatcher, and headers for parameters no declaration names are ignored, as the spec asks of any
+        # server that does not recognize them. The refusal names the header and the argument, not their values.
+        #
+        # Rack folds header names into `HTTP_` keys with `-` as `_`, so `Mcp-Param-Region-A` and `Mcp-Param-Region_A` land
+        # on one key; a token that differs only in that way is the schema author's choice, and the value still has to
+        # agree with the body.
+        def validate_mcp_param_headers(request, body)
+          params = body[:params]
+          return unless params.is_a?(Hash)
+
+          tool = @server.tools[params[:name]]
+          return unless tool
+
+          scan = McpParamHeaders.scan(tool.input_schema.to_h)
+          return unless scan[:valid] && !scan[:declarations].empty?
+
+          arguments = params[:arguments] || {}
+          return unless arguments.is_a?(Hash)
+
+          message = McpParamHeaders.mismatch(scan[:declarations], arguments) do |header_name|
+            header_bytes(request, "HTTP_#{header_name.upcase.tr("-", "_")}")
+          end
+          return unless message
+
+          header_mismatch_response(message, body[:id])
+        end
+
         # Serves `subscriptions/listen` (SEP-2575): opens a long-lived SSE stream whose first message is
         # `notifications/subscriptions/acknowledged` with the subset of requested notification types
         # the server agreed to honor. Notifications delivered on the stream carry `io.modelcontextprotocol/subscriptionId`
@@ -1135,6 +1250,14 @@ module MCP
           false
         end
 
+        # The id a refusal built here can echo: an Integer, or a String that is valid UTF-8. A String holding other
+        # bytes would make the body's `to_json` raise, so the refusal carries no id, as for an id it could not read.
+        def echoable_id(id)
+          return id if id.is_a?(Integer) || (id.is_a?(String) && id.valid_encoding?)
+
+          nil
+        end
+
         def listen_subscriptions_full?
           return false unless @max_listen_subscriptions
 
@@ -1222,7 +1345,7 @@ module MCP
                 acknowledged = subscription[:write_mutex].synchronize do
                   next false if subscription[:closed]
 
-                  send_to_stream(stream, acknowledgement)
+                  push_to_stream(stream, acknowledgement, subscription: subscription)
 
                   # Set on the entry itself, not through the registry: a concurrent close may already have cleared the registry
                   # while its result write waits on this mutex, and that write must still find the stream acknowledged.
@@ -1303,7 +1426,7 @@ module MCP
           subscription[:write_mutex].synchronize do
             next if subscription[:closed]
 
-            send_ping_to_stream(subscription[:stream])
+            push_ping_to_stream(subscription[:stream], subscription: subscription)
           end
         end
 
@@ -1445,7 +1568,7 @@ module MCP
               subscription[:write_mutex].synchronize do
                 next if subscription[:closed]
 
-                send_to_stream(subscription[:stream], notification)
+                push_to_stream(subscription[:stream], notification, subscription: subscription)
               end
             rescue *STREAM_WRITE_ERRORS => e
               MCP.configuration.exception_reporter.call(
@@ -1535,6 +1658,10 @@ module MCP
         # The stream is left open for the caller to close.
         def write_listen_closing_result(subscription)
           subscription[:write_mutex].synchronize do
+            # Already marked by a write that ran into its deadline: the last frame on the stream may be cut short,
+            # and the stream may still be open because its close was abandoned, so the result must not follow it.
+            next if subscription[:closed]
+
             subscription[:closed] = true
 
             # A stream whose acknowledgement was never written gets no result either: SEP-2575 makes
@@ -1571,12 +1698,21 @@ module MCP
           end
         end
 
+        # A client-supplied value for an error message or `data` member. A header value reaches the transport as
+        # ASCII-8BIT from a Rack server, or tagged UTF-8 from a test request or a framework, and a body value comes
+        # out of the JSON parser; a value holding bytes that are not valid UTF-8 would make the response's `to_json`
+        # raise and turn the intended 400 into a 500 with an exception report. Such bytes are replaced with U+FFFD;
+        # a valid value comes through unchanged.
+        def printable_value(value)
+          value.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+        end
+
         def header_mismatch_response(message, id)
           json_rpc_error_response(
             status: 400,
             code: ErrorCodes::HEADER_MISMATCH,
             message: "Header mismatch: #{message}",
-            id: id,
+            id: echoable_id(id),
           )
         end
 
@@ -1653,7 +1789,7 @@ module MCP
             if header_version && MCP::Configuration.modern_protocol_version?(header_version)
               return invalid_request_response(
                 "Invalid Request: the session already negotiated the legacy lifecycle via `initialize`",
-                request_id: body[:id],
+                request_id: echoable_id(body[:id]),
               )
             end
 
@@ -1699,7 +1835,7 @@ module MCP
                 session = @mutex.synchronize { @sessions[session_id] }
                 return session_not_found_response unless session && session_principal_matches?(session, request)
 
-                return already_initialized_response(body[:id])
+                return already_initialized_response(echoable_id(body[:id]))
               end
 
               return session_not_found_response
@@ -1834,8 +1970,21 @@ module MCP
           removed[:post_request_streams]&.each_value { |stream| streams_to_close << stream }
         end
 
+        # A close can block on the same full buffers a write does (a TLS stream writes its closing alert, a buffered one flushes),
+        # and it runs on the threads that deliver to every stream, in places under a stream's write mutex,
+        # so it gets `stream_write_timeout:` seconds as well. One that has not finished by then is abandoned,
+        # and not tried again: the path that drops a stream after its write timed out closes it a second time,
+        # which would wait out the same block once more.
         def close_stream_safely(stream)
-          stream&.close
+          return unless stream
+          return stream.close unless @stream_write_timeout
+          return if @streams_with_abandoned_close.key?(stream)
+
+          begin
+            Timeout.timeout(@stream_write_timeout) { stream.close }
+          rescue Timeout::Error
+            @streams_with_abandoned_close[stream] = true
+          end
         rescue StandardError
           # Ignore close-related errors from already closed/broken streams.
         end
@@ -1966,7 +2115,7 @@ module MCP
             status: 413,
             code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
             message: "Payload too large: initialize request #{reason}",
-            id: request_id,
+            id: echoable_id(request_id),
           )
         end
 
@@ -2055,7 +2204,7 @@ module MCP
           json_rpc_error_response(
             status: 400,
             code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
-            message: "Bad Request: Unsupported protocol version: #{header_value}. Supported versions: #{supported}",
+            message: "Bad Request: Unsupported protocol version: #{printable_value(header_value)}. Supported versions: #{supported}",
           )
         end
 
@@ -2657,7 +2806,7 @@ module MCP
         def send_keepalive_ping(session_id, stream)
           return unless session_holds_stream?(session_id, stream)
 
-          send_ping_to_stream(stream)
+          push_ping_to_stream(stream)
         rescue *STREAM_WRITE_ERRORS => e
           MCP.configuration.exception_reporter.call(
             e,

data/lib/mcp/server.rb

@@ -447,6 +447,13 @@ module MCP
     #   Use stderr or OpenTelemetry instead.
     def notify_log_message(data:, level:, logger: nil)
       return unless @transport
+
+      if @transport.respond_to?(:logging_sessions) && (sessions = @transport.logging_sessions)
+        sessions.each do |session|
+          session.notify_log_message(data: data, level: level, logger: logger)
+        end
+        return
+      end
       return unless logging_message_notification&.should_notify?(level)
 
       params = { "data" => data, "level" => level }
@@ -733,9 +740,9 @@ module MCP
 
       handler = @handlers[method]
       unless handler
-        instrument_call("unsupported_method", server_context: { request: request }) do
+        instrument_call("unsupported_method", server_context: { request: request }) do |instrumentation_data|
           client = session&.client || @client
-          add_instrumentation_data(client: client) if client
+          instrumentation_data.merge!(client: client) if client
         end
         return
       end
@@ -798,7 +805,7 @@ module MCP
           method,
           server_context: { request: request },
           exception_already_reported: ->(e) { reported_exception.equal?(e) },
-        ) do
+        ) do |instrumentation_data|
           refuse_non_object_meta!(params)
           envelope = lift_request_envelope(params, method: method, session: session)
 
@@ -817,7 +824,7 @@ 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, auth_info: auth_info)
+            contents = read_resource_contents(params, instrumentation_data: instrumentation_data, 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)
@@ -827,9 +834,9 @@ module MCP
 
             subscription_result(handler_result)
           when Methods::TOOLS_CALL
-            call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope, auth_info: auth_info)
+            call_tool(params, instrumentation_data: instrumentation_data, 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, auth_info: auth_info)
+            get_prompt(params, instrumentation_data: instrumentation_data, 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, auth_info: auth_info)
           when Methods::LOGGING_SET_LEVEL
@@ -838,10 +845,10 @@ module MCP
             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
+          instrumentation_data.merge!(client: client) if client
 
           if cancellation&.cancelled?
-            add_instrumentation_data(cancelled: true, cancellation_reason: cancellation.reason)
+            instrumentation_data.merge!(cancelled: true, cancellation_reason: cancellation.reason)
             next JsonRpcHandler::NO_RESPONSE
           end
 
@@ -851,6 +858,7 @@ module MCP
             result = if envelope.nil? && @input_required_legacy_shim && session
               run_legacy_input_required_shim(
                 result,
+                instrumentation_data: instrumentation_data,
                 method: method,
                 params: params,
                 session: session,
@@ -858,7 +866,7 @@ module MCP
                 cancellation: cancellation,
               )
             else
-              serialize_input_required_result(result, envelope: envelope, request: params, method: method)
+              serialize_input_required_result(result, instrumentation_data: instrumentation_data, envelope: envelope, request: params, method: method)
             end
           end
 
@@ -884,25 +892,25 @@ module MCP
 
           result
         rescue CancelledError => e
-          add_instrumentation_data(cancelled: true, cancellation_reason: e.reason)
+          instrumentation_data.merge!(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)
+          instrumentation_data.merge!(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)
+          instrumentation_data.merge!(error: e.error_type)
           reported_exception = e
           raise e
         rescue => e
           report_exception(e, { request: request })
-          add_instrumentation_data(error: :internal_error)
+          instrumentation_data.merge!(error: :internal_error)
           wrapped = RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
           reported_exception = wrapped
           raise wrapped
@@ -998,7 +1006,7 @@ module MCP
     # a final result. The capability gate enforces the SEP-2575 rule that servers MUST NOT rely on
     # (or embed requests for) capabilities the client did not declare, and reports every missing capability at
     # once so the client sees the full set.
-    def serialize_input_required_result(result, envelope:, request:, method:)
+    def serialize_input_required_result(result, instrumentation_data:, envelope:, request:, method:)
       if envelope.nil?
         raise RequestHandlerError.new(
           "input_required results require the 2026-07-28 stateless lifecycle (SEP-2322)",
@@ -1010,7 +1018,7 @@ module MCP
       missing = result.missing_client_capabilities(envelope.client_capabilities)
       raise MissingRequiredClientCapabilityError.new(missing, request) unless missing.empty?
 
-      add_instrumentation_data(input_required: true)
+      instrumentation_data.merge!(input_required: true)
       serialized = result.to_h
 
       if @request_state_security && serialized[:requestState]
@@ -1039,7 +1047,7 @@ module MCP
     # re-runs with `inputResponses`/`requestState` merged into the original params - the same deterministic replay
     # contract the modern client driver follows. The `requestState` round-trips in-process as the raw value
     # the handler wrote; `RequestStateSecurity` sealing is wire hardening and does not apply.
-    def run_legacy_input_required_shim(result, method:, params:, session:, related_request_id:, cancellation:)
+    def run_legacy_input_required_shim(result, instrumentation_data:, method:, params:, session:, related_request_id:, cancellation:)
       rounds = 0
 
       loop do
@@ -1071,6 +1079,7 @@ module MCP
         result = redispatch_mrtr_method(
           method,
           retry_params,
+          instrumentation_data: instrumentation_data,
           session: session,
           related_request_id: related_request_id,
           cancellation: cancellation,
@@ -1104,14 +1113,14 @@ module MCP
 
     # Re-runs the handler of one of the three MRTR-capable methods for
     # the legacy shim. Legacy wire, so no envelope is threaded.
-    def redispatch_mrtr_method(method, params, session:, related_request_id:, cancellation:)
+    def redispatch_mrtr_method(method, params, instrumentation_data:, session:, related_request_id:, cancellation:)
       case method
       when Methods::TOOLS_CALL
-        call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+        call_tool(params, instrumentation_data: instrumentation_data, 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)
+        get_prompt(params, instrumentation_data: instrumentation_data, session: session, related_request_id: related_request_id, cancellation: cancellation)
       when Methods::RESOURCES_READ
-        contents = read_resource_contents(params, session: session, related_request_id: related_request_id, cancellation: cancellation)
+        contents = read_resource_contents(params, instrumentation_data: instrumentation_data, session: session, related_request_id: related_request_id, cancellation: cancellation)
         contents.is_a?(InputRequiredResult) ? contents : build_read_resource_result(contents)
       else
         raise RequestHandlerError.new(
@@ -1382,8 +1391,11 @@ module MCP
         raise RequestHandlerError.new("Invalid log level #{request[:level]}", request, error_type: :invalid_params)
       end
 
-      session&.configure_logging(logging_message_notification)
-      @logging_message_notification = logging_message_notification
+      if session
+        session.configure_logging(logging_message_notification)
+      else
+        @logging_message_notification = logging_message_notification
+      end
 
       {}
     end
@@ -1394,21 +1406,21 @@ 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, auth_info: nil)
+    def call_tool(request, instrumentation_data:, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
       unless tool
-        add_instrumentation_data(tool_name: tool_name, error: :tool_not_found)
+        instrumentation_data.merge!(tool_name: tool_name, error: :tool_not_found)
 
         raise RequestHandlerError.new("Tool not found: #{tool_name}", request, error_type: :invalid_params)
       end
 
       arguments = request[:arguments] || {}
-      add_instrumentation_data(tool_name: tool_name, tool_arguments: arguments)
+      instrumentation_data.merge!(tool_name: tool_name, tool_arguments: arguments)
 
       if tool.input_schema&.missing_required_arguments?(arguments)
-        add_instrumentation_data(error: :missing_required_arguments)
+        instrumentation_data.merge!(error: :missing_required_arguments)
 
         missing = tool.input_schema.missing_required_arguments(arguments).join(", ")
         return error_tool_response("Missing required arguments: #{missing}")
@@ -1418,7 +1430,7 @@ module MCP
         begin
           tool.input_schema.validate_arguments(arguments)
         rescue Tool::InputSchema::ValidationError => e
-          add_instrumentation_data(error: :invalid_schema)
+          instrumentation_data.merge!(error: :invalid_schema)
 
           return error_tool_response(e.message)
         end
@@ -1473,11 +1485,11 @@ 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, auth_info: nil)
+    def get_prompt(request, instrumentation_data:, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
       prompt_name = request[:name]
       prompt = @prompts[prompt_name]
       unless prompt
-        add_instrumentation_data(error: :prompt_not_found)
+        instrumentation_data.merge!(error: :prompt_not_found)
         # The explicit `error_code` maps an unknown prompt to Invalid Params (-32602) rather than
         # the default Internal Error (-32603), matching the `tools/call`, `resources/read`, and
         # `completion/complete` siblings for the same not-found condition, while `error_type:
@@ -1490,7 +1502,7 @@ module MCP
         )
       end
 
-      add_instrumentation_data(prompt_name: prompt_name)
+      instrumentation_data.merge!(prompt_name: prompt_name)
 
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
@@ -1766,9 +1778,9 @@ module MCP
     # Default `resources/read` handler: routes to class-based resources and resource templates.
     # Fully replaced when `resources_read_handler` is set. When no class-based resource or template is registered,
     # unknown URIs keep the historical no-op `[]` response instead of raising.
-    def read_resource(request, server_context: nil)
+    def read_resource(request, instrumentation_data:, server_context: nil)
       uri = request[:uri]
-      add_instrumentation_data(resource_uri: uri)
+      instrumentation_data.merge!(resource_uri: uri)
 
       # Files of directory-backed skills are looked up by exact string equality in a map built at construction,
       # so request data never reaches the filesystem; a miss falls through to the routing below.
@@ -1798,7 +1810,7 @@ module MCP
         params = template.match_uri(uri)
         next unless params
 
-        add_instrumentation_data(resource_template: template.uri_template)
+        instrumentation_data.merge!(resource_template: template.uri_template)
         return normalize_resource_contents(call_template_contents(template, params, server_context))
       end
 
@@ -1884,9 +1896,22 @@ 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, auth_info: nil)
+    def read_resource_contents(request, instrumentation_data:, session: nil, related_request_id: nil, cancellation: nil, envelope: nil, auth_info: nil)
+      handler = @handlers[Methods::RESOURCES_READ]
+      if handler == method(:read_resource)
+        server_context = build_server_context(
+          request: request,
+          session: session,
+          related_request_id: related_request_id,
+          cancellation: cancellation,
+          envelope: envelope,
+          auth_info: auth_info,
+        )
+        return read_resource(request, instrumentation_data: instrumentation_data, server_context: server_context)
+      end
+
       dispatch_optional_context_handler(
-        @handlers[Methods::RESOURCES_READ],
+        handler,
         request,
         session: session,
         related_request_id: related_request_id,