mcp 1.0.0 → 1.2.0

data/lib/mcp/configuration.rb

@@ -2,12 +2,49 @@
 
 module MCP
   class Configuration
-    LATEST_STABLE_PROTOCOL_VERSION = "2025-11-25"
+    LATEST_STABLE_PROTOCOL_VERSION = "2026-07-28"
+    ROOTS_SAMPLING_LOGGING_DEPRECATED_PROTOCOL_VERSION = "2026-07-28"
     SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
-      LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
+      LATEST_STABLE_PROTOCOL_VERSION, "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05",
     ].freeze
     DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26"
 
+    # Protocol versions of the stateless "modern" lifecycle introduced by the MCP 2026-07-28 spec release (SEP-2575),
+    # where each request carries its own version in `_meta` and is validated against this list independently,
+    # with no handshake. These are reachable only through `server/discover` and the per-request envelope.
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+    LATEST_MODERN_PROTOCOL_VERSION = "2026-07-28"
+    SUPPORTED_MODERN_PROTOCOL_VERSIONS = [LATEST_MODERN_PROTOCOL_VERSION].freeze
+
+    # Protocol versions reachable through the legacy `initialize` handshake, derived so the era partition
+    # (handshake = stable minus modern) cannot drift when a new revision lands.
+    # Per the SEP-2575 era model, an era is a property of the protocol version itself: legacy versions establish
+    # a session via `initialize` (2025-11-25 and earlier), and modern versions carry the version on every request
+    # in `_meta` with no handshake at all. The handshake therefore never negotiates a modern version:
+    # a client asking `initialize` for one is counter-offered
+    # `LATEST_HANDSHAKE_PROTOCOL_VERSION`, matching the TypeScript and Python SDKs.
+    SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS = (SUPPORTED_STABLE_PROTOCOL_VERSIONS - SUPPORTED_MODERN_PROTOCOL_VERSIONS).freeze
+    LATEST_HANDSHAKE_PROTOCOL_VERSION = SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS.first
+
+    class << self
+      def modern_protocol_version?(version)
+        SUPPORTED_MODERN_PROTOCOL_VERSIONS.include?(version)
+      end
+
+      def handshake_protocol_version?(version)
+        SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS.include?(version)
+      end
+
+      # The one statement of the client-side handshake contract, shared by every transport:
+      # a modern version cannot ride the legacy `initialize` handshake.
+      def reject_modern_handshake_version!(version)
+        return unless version && modern_protocol_version?(version)
+
+        raise ArgumentError, "protocol version #{version.inspect} cannot be negotiated through the legacy " \
+                             "`initialize` handshake; use `mode: :modern` (or `:auto`) instead"
+      end
+    end
+
     attr_writer :exception_reporter, :around_request
 
     # @deprecated Use {#around_request=} instead. `instrumentation_callback`
@@ -17,7 +54,7 @@ module MCP
     attr_writer :instrumentation_callback
 
     def initialize(exception_reporter: nil, around_request: nil, instrumentation_callback: nil, protocol_version: nil,
-      validate_tool_call_arguments: true, validate_tool_call_results: false)
+      validate_tool_call_arguments: true, validate_tool_call_results: false, instrument_server_context: false)
       @exception_reporter = exception_reporter
       @around_request = around_request
       @instrumentation_callback = instrumentation_callback
@@ -27,9 +64,11 @@ module MCP
       end
       validate_value_of_validate_tool_call_arguments!(validate_tool_call_arguments)
       validate_value_of_validate_tool_call_results!(validate_tool_call_results)
+      validate_value_of_instrument_server_context!(instrument_server_context)
 
       @validate_tool_call_arguments = validate_tool_call_arguments
       @validate_tool_call_results = validate_tool_call_results
+      @instrument_server_context = instrument_server_context
     end
 
     def protocol_version=(protocol_version)
@@ -44,14 +83,28 @@ module MCP
       @validate_tool_call_arguments = validate_tool_call_arguments
     end
 
+    # Opt in to exposing the user-defined `server_context` in the
+    # `around_request` / `instrumentation_callback` data hash. Off by default:
+    # the hash is application-supplied and may hold values a tracing backend
+    # should not receive, so surfacing it has to be a deliberate choice.
+    def instrument_server_context=(instrument_server_context)
+      validate_value_of_instrument_server_context!(instrument_server_context)
+
+      @instrument_server_context = instrument_server_context
+    end
+
     def validate_tool_call_results=(validate_tool_call_results)
       validate_value_of_validate_tool_call_results!(validate_tool_call_results)
 
       @validate_tool_call_results = validate_tool_call_results
     end
 
+    # The pin scopes the `initialize` handshake, so an unset pin reads as the version that handshake
+    # settles on by default. Reading the newest version of any era here would hand back a value
+    # the writer rejects, and no caller wants the modern revision: a modern connection carries
+    # its version on every request instead of consulting configuration.
     def protocol_version
-      @protocol_version || LATEST_STABLE_PROTOCOL_VERSION
+      @protocol_version || LATEST_HANDSHAKE_PROTOCOL_VERSION
     end
 
     def protocol_version?
@@ -91,6 +144,10 @@ module MCP
     attr_reader :validate_tool_call_arguments
     attr_reader :validate_tool_call_results
 
+    def instrument_server_context?
+      !!@instrument_server_context
+    end
+
     def validate_tool_call_arguments?
       !!@validate_tool_call_arguments
     end
@@ -136,16 +193,30 @@ module MCP
         protocol_version: protocol_version,
         validate_tool_call_arguments: validate_tool_call_arguments,
         validate_tool_call_results: validate_tool_call_results,
+        instrument_server_context: other.instrument_server_context?,
       )
     end
 
     private
 
+    # A pin scopes the `initialize` handshake, so only handshake versions are accepted:
+    # a modern version has no handshake to pin (its version rides every request in `_meta`),
+    # and accepting one here would configure nothing. Failing at construction beats
+    # a setting that silently does not apply.
     def validate_protocol_version!(protocol_version)
-      unless SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
-        message = "protocol_version must be #{SUPPORTED_STABLE_PROTOCOL_VERSIONS[0...-1].join(", ")}, or #{SUPPORTED_STABLE_PROTOCOL_VERSIONS[-1]}"
-        raise ArgumentError, message
+      return if SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS.include?(protocol_version)
+
+      # A version this SDK serves, rejected only for where it was set, deserves the reason and
+      # the alternative rather than a list it is missing from: this is the error an upgrade from
+      # a release that accepted the value lands on, so it doubles as the migration note.
+      if self.class.modern_protocol_version?(protocol_version)
+        raise ArgumentError, "protocol_version #{protocol_version.inspect} is a modern protocol version and cannot be pinned here: " \
+                             "the pin scopes the `initialize` handshake, which never negotiates a modern version. " \
+                             "Modern clients carry their version on every request and need no pin; remove the setting."
       end
+
+      raise ArgumentError, "protocol_version must be #{SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS[0...-1].join(", ")}, " \
+                           "or #{SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS[-1]}"
     end
 
     def validate_value_of_validate_tool_call_arguments!(validate_tool_call_arguments)
@@ -160,6 +231,12 @@ module MCP
       end
     end
 
+    def validate_value_of_instrument_server_context!(instrument_server_context)
+      unless instrument_server_context.is_a?(TrueClass) || instrument_server_context.is_a?(FalseClass)
+        raise ArgumentError, "instrument_server_context must be a boolean"
+      end
+    end
+
     def default_exception_reporter
       @default_exception_reporter ||= ->(exception, server_context) {}
     end

data/lib/mcp/elicitation/enum_schema.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module MCP
+  module Elicitation
+    # Builds the four enum schema variants defined by MCP 2025-11-25 (SEP-1330) plus the legacy `enumNames` form
+    # retained for backward compatibility.
+    #
+    # Each class method returns an `EnumSchema` instance; call `to_h` to get the property-value Hash and
+    # pass it through `requested_schema` to `ServerSession#create_form_elicitation`.
+    class EnumSchema
+      class << self
+        # Single-select with plain string values: `{ type: "string", enum: [...] }`.
+        def untitled_single_select(values:, default: nil, title: nil, description: nil)
+          validate_values!(values)
+
+          new(
+            type: "string",
+            extras: { enum: values },
+            default: default,
+            title: title,
+            description: description,
+          )
+        end
+
+        # Single-select with display titles per option: `{ type: "string", oneOf: [{ const, title }, ...] }`.
+        # `options` is an Array of `{ value:, title: }` hashes.
+        def titled_single_select(options:, default: nil, title: nil, description: nil)
+          validate_titled_options!(options)
+
+          new(
+            type: "string",
+            extras: { oneOf: options.map { |o| { const: o[:value], title: o[:title] } } },
+            default: default,
+            title: title,
+            description: description,
+          )
+        end
+
+        # Multi-select with plain string values: `{ type: "array", items: { type: "string", enum: [...] } }`.
+        def untitled_multi_select(values:, default: nil, title: nil, description: nil)
+          validate_values!(values)
+
+          new(
+            type: "array",
+            extras: { items: { type: "string", enum: values } },
+            default: default,
+            title: title,
+            description: description,
+          )
+        end
+
+        # Multi-select with display titles per option: `{ type: "array", items: { anyOf: [{ const, title }, ...] } }`.
+        def titled_multi_select(options:, default: nil, title: nil, description: nil)
+          validate_titled_options!(options)
+
+          items_anyof = options.map { |o| { const: o[:value], title: o[:title] } }
+          new(
+            type: "array",
+            extras: { items: { anyOf: items_anyof } },
+            default: default,
+            title: title,
+            description: description,
+          )
+        end
+
+        # Legacy single-select retained for backward compatibility with clients implementing
+        # the pre-SEP-1330 form: `{ enum, enumNames }`.
+        def legacy_titled(values:, value_titles:, default: nil, title: nil, description: nil)
+          validate_values!(values)
+          unless value_titles.is_a?(Array) && value_titles.length == values.length
+            raise ArgumentError, "value_titles must be an Array of the same length as values"
+          end
+
+          new(
+            type: "string",
+            extras: { enum: values, enumNames: value_titles },
+            default: default,
+            title: title,
+            description: description,
+          )
+        end
+
+        private
+
+        def validate_values!(values)
+          unless values.is_a?(Array) && !values.empty?
+            raise ArgumentError, "values must be a non-empty Array"
+          end
+        end
+
+        def validate_titled_options!(options)
+          unless options.is_a?(Array) && !options.empty?
+            raise ArgumentError, "options must be a non-empty Array of {value:, title:} hashes"
+          end
+
+          options.each do |option|
+            unless option.is_a?(Hash) && option.key?(:value) && option.key?(:title)
+              raise ArgumentError, "each option must be a Hash with :value and :title keys"
+            end
+          end
+        end
+      end
+
+      def initialize(type:, extras:, default: nil, title: nil, description: nil)
+        @type = type
+        @extras = extras
+        @default = default
+        @title = title
+        @description = description
+      end
+
+      def to_h
+        hash = { type: @type }.merge(@extras)
+        hash[:title] = @title if @title
+        hash[:description] = @description if @description
+        hash[:default] = @default unless @default.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/mcp/elicitation.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MCP
+  # Builders for elicitation `requestedSchema` definitions per MCP 2025-11-25.
+  # Each builder returns an instance whose `to_h` produces the JSON-Schema-shaped Hash
+  # a server passes as a property value in `create_form_elicitation(requested_schema:)`.
+  module Elicitation
+    autoload :EnumSchema, "mcp/elicitation/enum_schema"
+  end
+end

data/lib/mcp/error_codes.rb

@@ -3,18 +3,24 @@
 module MCP
   # MCP-specific JSON-RPC error codes, complementing the generic codes in `JsonRpcHandler::ErrorCode`.
   #
-  # Both constants below are introduced by the stateless lifecycle of the MCP 2026-07-28 draft (SEP-2575):
-  # `UNSUPPORTED_PROTOCOL_VERSION` rejects a request whose `_meta`-carried protocol version the server does not
-  # support (`error.data: { supported: [...], requested: "..." }`), and `MISSING_REQUIRED_CLIENT_CAPABILITY`
-  # rejects a request that requires a client capability the request did not declare
-  # (`error.data: { requiredCapabilities: {...} }`). The SDK exports the vocabulary; it does not raise
-  # these codes itself yet.
+  # All three constants below are introduced by the stateless lifecycle of the MCP 2026-07-28 draft (SEP-2575):
   #
-  # The values come from the spec's MCP-specific error code block, which is allocated sequentially from
-  # `-32020` toward `-32099`. `-32020` (`HEADER_MISMATCH`, SEP-2243) precedes the two codes defined here.
+  # - `HEADER_MISMATCH` rejects an HTTP request whose headers do not match the corresponding body values,
+  #   or whose required headers are missing or malformed (no `error.data`). It is reserved for
+  #   the Streamable HTTP transport, since headers do not exist on stdio.
+  # - `MISSING_REQUIRED_CLIENT_CAPABILITY` rejects a request that requires a client capability
+  #   the request did not declare (`error.data: { requiredCapabilities: {...} }`).
+  #   Raised via `Server::MissingRequiredClientCapabilityError`.
+  # - `UNSUPPORTED_PROTOCOL_VERSION` rejects a request whose `_meta`-carried protocol version the server
+  #   does not support (`error.data: { supported: [...], requested: "..." }`). Raised via
+  #   `Server::UnsupportedProtocolVersionError`.
+  #
+  # The values come from the spec's MCP-specific error code block, which is allocated sequentially from `-32020`
+  # toward `-32099`.
   #
   # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
   module ErrorCodes
+    HEADER_MISMATCH = -32020
     MISSING_REQUIRED_CLIENT_CAPABILITY = -32021
     UNSUPPORTED_PROTOCOL_VERSION = -32022
   end

data/lib/mcp/instrumentation.rb

@@ -7,6 +7,12 @@ module MCP
       begin
         @instrumentation_data = {}
         add_instrumentation_data(method: method)
+        # `self.` is required: the `server_context:` keyword above shadows the
+        # reader, and the value we want here is the user-defined hash passed to
+        # `Server.new`, not the per-call reporter context.
+        if configuration.instrument_server_context? && respond_to?(:server_context)
+          add_instrumentation_data(server_context: self.server_context)
+        end
 
         result = configuration.around_request.call(@instrumentation_data, &block)
 

data/lib/mcp/methods.rb

@@ -7,6 +7,10 @@ module MCP
     LOGGING_SET_LEVEL = "logging/setLevel"
     # Sessionless capability discovery (MCP 2026-07-28 draft, SEP-2575).
     SERVER_DISCOVER = "server/discover"
+    # Long-lived notification subscription stream (MCP 2026-07-28, SEP-2575),
+    # replacing the legacy HTTP GET listening stream. Served at the transport layer
+    # (Streamable HTTP modern path); transports without streaming support answer `-32601`.
+    SUBSCRIPTIONS_LISTEN = "subscriptions/listen"
 
     PROMPTS_GET = "prompts/get"
     PROMPTS_LIST = "prompts/list"
@@ -21,6 +25,20 @@ module MCP
     TOOLS_CALL = "tools/call"
     TOOLS_LIST = "tools/list"
 
+    # RPC methods the stateless modern lifecycle removes (MCP 2026-07-28, SEP-2575):
+    # `initialize` is replaced by the per-request `_meta` envelope plus `server/discover`,
+    # `logging/setLevel` by the envelope's `logLevel` member, and `ping` and the resource
+    # subscription pair by the connectionless model, which leaves nothing to keep alive
+    # or subscribe on. A modern-era request naming one of these answers with `-32601`
+    # Method not found (HTTP 404 on Streamable HTTP).
+    MODERN_REMOVED_METHODS = [
+      INITIALIZE,
+      PING,
+      LOGGING_SET_LEVEL,
+      RESOURCES_SUBSCRIBE,
+      RESOURCES_UNSUBSCRIBE,
+    ].freeze
+
     ROOTS_LIST = "roots/list"
     SAMPLING_CREATE_MESSAGE = "sampling/createMessage"
     ELICITATION_CREATE = "elicitation/create"
@@ -36,6 +54,9 @@ module MCP
     NOTIFICATIONS_PROGRESS = "notifications/progress"
     NOTIFICATIONS_CANCELLED = "notifications/cancelled"
     NOTIFICATIONS_ELICITATION_COMPLETE = "notifications/elicitation/complete"
+    # First message on a `subscriptions/listen` stream (SEP-2575): reports the subset
+    # of requested notification types the server agreed to honor.
+    NOTIFICATIONS_SUBSCRIPTIONS_ACKNOWLEDGED = "notifications/subscriptions/acknowledged"
 
     class MissingRequiredCapabilityError < StandardError
       attr_reader :method

data/lib/mcp/prompt.rb

@@ -111,8 +111,15 @@ module MCP
         missing = required_args - args.keys
         return if missing.empty?
 
+        # The explicit `error_code` maps a missing prompt argument to Invalid Params (-32602) rather
+        # than the default Internal Error (-32603); a missing required argument is client input, not a
+        # server fault. `error_type: :missing_required_arguments` keeps the descriptive message and
+        # instrumentation label. Mirrors `MCP::Server::ResourceNotFoundError`.
         raise MCP::Server::RequestHandlerError.new(
-          "Missing required arguments: #{missing.join(", ")}", nil, error_type: :missing_required_arguments
+          "Missing required arguments: #{missing.join(", ")}",
+          nil,
+          error_type: :missing_required_arguments,
+          error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
         )
       end
 

data/lib/mcp/protocol_deprecations.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+
+module MCP
+  # Warning texts for the features SEP-2577 deprecates at 2026-07-28.
+  #
+  # Only the client emits these, from the modern connect, where the capabilities it declares are
+  # the ones being deprecated. No server-side trigger remains: the `initialize` handshake never lands on
+  # a deprecating revision and `Configuration` rejects a modern pin, so nothing on that side can reach
+  # a version these apply to. `LOGGING_MESSAGE` in particular has no caller left
+  # (a modern client declares no logging capability, and `notify_log_message` on that wire is
+  # the SEP-2575 sanctioned delivery path rather than a deprecated call). It stays public and
+  # callable for embedders, and because deleting it would be a breaking change for no gain.
+  module ProtocolDeprecations
+    extend self
+
+    ROOTS_MESSAGE =
+      "MCP Roots (`roots/list` and `notifications/roots/list_changed`) is deprecated as of protocol version " \
+        "2026-07-28 (SEP-2577). Use tool parameters, resource URIs, server configuration, or environment " \
+        "variables instead."
+    SAMPLING_MESSAGE =
+      "MCP Sampling (`sampling/createMessage`) is deprecated as of protocol version 2026-07-28 (SEP-2577). " \
+        "Use direct LLM provider APIs instead."
+    LOGGING_MESSAGE =
+      "MCP Logging (`logging/setLevel` and `notifications/message`) is deprecated as of protocol version " \
+        "2026-07-28 (SEP-2577). Use stderr or OpenTelemetry instead."
+
+    MESSAGES = {
+      roots: ROOTS_MESSAGE,
+      sampling: SAMPLING_MESSAGE,
+      logging: LOGGING_MESSAGE,
+    }.freeze
+
+    def deprecated_roots_sampling_logging?(protocol_version)
+      return false unless protocol_version
+
+      protocol_version >= Configuration::ROOTS_SAMPLING_LOGGING_DEPRECATED_PROTOCOL_VERSION
+    end
+
+    def warn_for(feature, protocol_version:, uplevel: 1)
+      return unless deprecated_roots_sampling_logging?(protocol_version)
+
+      Kernel.warn(MESSAGES.fetch(feature), uplevel: uplevel)
+    end
+
+    def warn_for_client_capabilities(capabilities, protocol_version:, uplevel: 1)
+      return unless deprecated_roots_sampling_logging?(protocol_version)
+      return unless capabilities
+
+      warn_for(:roots, protocol_version: protocol_version, uplevel: uplevel) if capability?(capabilities, :roots)
+      warn_for(:sampling, protocol_version: protocol_version, uplevel: uplevel) if capability?(capabilities, :sampling)
+    end
+
+    private
+
+    def capability?(capabilities, key)
+      capabilities.key?(key) || capabilities.key?(key.to_s)
+    end
+  end
+end

data/lib/mcp/request_envelope.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module MCP
+  # The per-request `_meta` envelope of the stateless "modern" lifecycle (MCP 2026-07-28, SEP-2575).
+  # The modern lifecycle has no `initialize` handshake: every request identifies its protocol version
+  # and client capabilities through reserved `_meta` keys (plus an optional client identity),
+  # and the server validates each request independently. Servers MUST NOT infer capabilities from
+  # prior requests, which is why the envelope is a per-request value object rather than session state.
+  #
+  # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+  class RequestEnvelope
+    PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion"
+    CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo"
+    CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities"
+
+    # Optional per-request log level, replacing the `logging/setLevel` RPC in the modern lifecycle.
+    # Deprecated as of 2026-07-28 (SEP-2577) but still part of the wire format.
+    LOG_LEVEL_META_KEY = "io.modelcontextprotocol/logLevel"
+    # Notification-side reserved key (SEP-2575): correlates a notification delivered on
+    # a `subscriptions/listen` stream (and the stream's closing result) with the JSON-RPC id of
+    # the `subscriptions/listen` request that opened it. Not part of the request envelope triple.
+    SUBSCRIPTION_ID_META_KEY = "io.modelcontextprotocol/subscriptionId"
+
+    # Result-side counterpart of the request envelope: the server's identity rides in
+    # the result's `_meta` as an optional stamp, not as a top-level field, since the SEP was
+    # finalized (spec PR modelcontextprotocol/modelcontextprotocol#3002). A server MAY omit it.
+    SERVER_INFO_META_KEY = "io.modelcontextprotocol/serverInfo"
+
+    # `clientInfo` is deliberately absent: it became optional after the SEP was finalized
+    # (spec PR modelcontextprotocol/modelcontextprotocol#3002), so servers MUST accept
+    # envelopes without it. The TypeScript and Python SDKs validate the same required pair.
+    REQUIRED_META_KEYS = [
+      PROTOCOL_VERSION_META_KEY,
+      CLIENT_CAPABILITIES_META_KEY,
+    ].freeze
+
+    class << self
+      # A request claims the modern lifecycle when its `_meta` carries `io.modelcontextprotocol/protocolVersion`,
+      # matching the TypeScript SDK's envelope claim and the Python SDK's `_has_modern_envelope`.
+      # Classification is deliberately looser than validation: a claimed-but-malformed envelope is
+      # rejected by {parse!} with `-32602` instead of silently flowing through the legacy path,
+      # while `_meta` without the claim key (`progressToken`, trace context) stays legacy.
+      def modern?(params)
+        meta = extract_meta(params)
+        return false unless meta.is_a?(Hash)
+
+        !read(meta, PROTOCOL_VERSION_META_KEY).nil?
+      end
+
+      # Parses and validates the envelope: `protocolVersion` and `clientCapabilities` are required,
+      # `clientInfo` is optional. A missing or mistyped field is Invalid params (`-32602`) naming
+      # the offending keys, the code and shape the spec mandates and the reference SDKs emit.
+      # `request` is only used to enrich the raised error; callers dispatching notifications can omit it.
+      def parse!(params, request: nil)
+        meta = extract_meta(params)
+        meta = {} unless meta.is_a?(Hash)
+
+        protocol_version = read(meta, PROTOCOL_VERSION_META_KEY)
+        client_info = read(meta, CLIENT_INFO_META_KEY)
+        client_capabilities = read(meta, CLIENT_CAPABILITIES_META_KEY)
+
+        invalid_keys = []
+        invalid_keys << PROTOCOL_VERSION_META_KEY unless protocol_version.is_a?(String)
+        invalid_keys << CLIENT_CAPABILITIES_META_KEY unless client_capabilities.is_a?(Hash)
+        invalid_keys << CLIENT_INFO_META_KEY unless client_info.nil? || client_info.is_a?(Hash)
+
+        unless invalid_keys.empty?
+          raise Server::RequestHandlerError.new(
+            "Invalid params: missing or invalid `#{invalid_keys.join("`, `")}` in `_meta`",
+            request,
+            error_type: :invalid_params,
+            error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+          )
+        end
+
+        unless Configuration.modern_protocol_version?(protocol_version)
+          raise Server::UnsupportedProtocolVersionError.new(protocol_version, request)
+        end
+
+        new(
+          protocol_version: protocol_version,
+          client_info: client_info,
+          client_capabilities: client_capabilities,
+          log_level: read(meta, LOG_LEVEL_META_KEY),
+        )
+      end
+
+      private
+
+      # `Server#handle` accepts hashes parsed with either symbol or string keys, so read both forms
+      # (the same tolerance as `Server#handle_cancelled_notification`).
+      def extract_meta(params)
+        return unless params.is_a?(Hash)
+
+        meta = params[:_meta]
+        meta.nil? ? params["_meta"] : meta
+      end
+
+      def read(meta, key)
+        value = meta[key.to_sym]
+        value.nil? ? meta[key] : value
+      end
+    end
+
+    # `client_info` is `nil` when the client chose not to identify itself, which is legal:
+    # it is self-reported data and MUST NOT drive behavior or security decisions anyway.
+    attr_reader :protocol_version, :client_info, :client_capabilities, :log_level
+
+    def initialize(protocol_version:, client_capabilities:, client_info: nil, log_level: nil)
+      @protocol_version = protocol_version
+      @client_info = client_info
+      @client_capabilities = client_capabilities
+      @log_level = log_level
+      freeze
+    end
+  end
+end