mcp 0.20.0 → 0.22.0

data/lib/mcp/client.rb

@@ -77,7 +77,9 @@ module MCP
     #
     # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
     # @param protocol_version [String, nil] Protocol version to offer.
-    # @param capabilities [Hash] Capabilities advertised by the client.
+    # @param capabilities [Hash] Capabilities advertised by the client. May include
+    #   an `extensions` member per SEP-2133, keyed by reverse-DNS extension identifiers,
+    #   e.g. `{ extensions: { "com.example/feature" => {} } }`.
     # @return [Hash, nil] The server's `InitializeResult`, or `nil` when the transport
     #   does not expose an explicit handshake.
     # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
@@ -105,6 +107,8 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional token; cancelling it sends
+    #   `notifications/cancelled` to the server and raises `MCP::CancelledError` from this call.
     # @return [MCP::Client::ListToolsResult] Result with `tools` (Array<MCP::Client::Tool>)
     #   and `next_cursor` (String or nil).
     #
@@ -116,9 +120,9 @@ module MCP
     #     cursor = page.next_cursor
     #     break unless cursor
     #   end
-    def list_tools(cursor: nil, meta: nil)
+    def list_tools(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "tools/list", params: params, meta: meta)
+      response = request(method: "tools/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       tools = (result["tools"] || []).map do |tool|
@@ -139,6 +143,9 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
+    #   Cancelling it aborts whichever page is currently in flight; pages already returned are kept,
+    #   but the call raises `MCP::CancelledError` instead of returning the partial set.
     # @return [Array<MCP::Client::Tool>] An array of available tools.
     #
     # @example
@@ -146,9 +153,9 @@ module MCP
     #   tools.each do |tool|
     #     puts tool.name
     #   end
-    def tools
+    def tools(cancellation: nil)
       # TODO: consider renaming to `list_all_tools`.
-      fetch_all_pages { |cursor| list_tools(cursor: cursor) }.flat_map(&:tools)
+      fetch_all_pages { |cursor| list_tools(cursor: cursor, cancellation: cancellation) }.flat_map(&:tools)
     end
 
     # Returns a single page of resources from the server.
@@ -156,11 +163,12 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [MCP::Client::ListResourcesResult] Result with `resources` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_resources(cursor: nil, meta: nil)
+    def list_resources(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/list", params: params, meta: meta)
+      response = request(method: "resources/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       ListResourcesResult.new(
@@ -176,10 +184,11 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available resources.
-    def resources
+    def resources(cancellation: nil)
       # TODO: consider renaming to `list_all_resources`.
-      fetch_all_pages { |cursor| list_resources(cursor: cursor) }.flat_map(&:resources)
+      fetch_all_pages { |cursor| list_resources(cursor: cursor, cancellation: cancellation) }.flat_map(&:resources)
     end
 
     # Returns a single page of resource templates from the server.
@@ -187,11 +196,12 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [MCP::Client::ListResourceTemplatesResult] Result with `resource_templates`
     #   (Array<Hash>) and `next_cursor` (String or nil).
-    def list_resource_templates(cursor: nil, meta: nil)
+    def list_resource_templates(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/templates/list", params: params, meta: meta)
+      response = request(method: "resources/templates/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       ListResourceTemplatesResult.new(
@@ -207,10 +217,11 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available resource templates.
-    def resource_templates
+    def resource_templates(cancellation: nil)
       # TODO: consider renaming to `list_all_resource_templates`.
-      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor) }.flat_map(&:resource_templates)
+      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor, cancellation: cancellation) }.flat_map(&:resource_templates)
     end
 
     # Returns a single page of prompts from the server.
@@ -218,11 +229,12 @@ module MCP
     # @param cursor [String, nil] Cursor from a previous page response.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [MCP::Client::ListPromptsResult] Result with `prompts` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_prompts(cursor: nil, meta: nil)
+    def list_prompts(cursor: nil, meta: nil, cancellation: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "prompts/list", params: params, meta: meta)
+      response = request(method: "prompts/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
       ListPromptsResult.new(
@@ -238,10 +250,11 @@ module MCP
     #
     # Each call will make a new request - the result is not cached.
     #
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available prompts.
-    def prompts
+    def prompts(cancellation: nil)
       # TODO: consider renaming to `list_all_prompts`.
-      fetch_all_pages { |cursor| list_prompts(cursor: cursor) }.flat_map(&:prompts)
+      fetch_all_pages { |cursor| list_prompts(cursor: cursor, cancellation: cancellation) }.flat_map(&:prompts)
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -254,6 +267,8 @@ module MCP
     #   e.g. the W3C Trace Context keys reserved by SEP-414
     #   (`MCP::TraceContext::TRACEPARENT_META_KEY`, `tracestate`, `baggage`).
     #   `progress_token` takes precedence over a `progressToken` entry in `meta`.
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token. Cancelling it from another thread
+    #   sends `notifications/cancelled` to the server and raises `MCP::CancelledError` from this call.
     # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example Call by name
@@ -265,10 +280,19 @@ module MCP
     #   response = client.call_tool(tool: tool, arguments: { foo: "bar" })
     #   structured_content = response.dig("result", "structuredContent")
     #
+    # @example Cancellable call
+    #   cancellation = MCP::Cancellation.new
+    #   Thread.new do
+    #     client.call_tool(name: "slow_tool", arguments: {}, cancellation: cancellation)
+    #   rescue MCP::CancelledError
+    #     # cleanup
+    #   end
+    #   cancellation.cancel(reason: "user pressed cancel")
+    #
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
-    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil)
+    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil, cancellation: nil)
       tool_name = name || tool&.name
       raise ArgumentError, "Either `name:` or `tool:` must be provided." unless tool_name
 
@@ -280,7 +304,7 @@ module MCP
       end
       params[:_meta] = meta_entries unless meta_entries.empty?
 
-      request(method: "tools/call", params: params)
+      request(method: "tools/call", params: params, cancellation: cancellation)
     end
 
     # Reads a resource from the server by URI and returns the contents.
@@ -288,9 +312,10 @@ module MCP
     # @param uri [String] The URI of the resource to read.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Array<Hash>] An array of resource contents (text or blob).
-    def read_resource(uri:, meta: nil)
-      response = request(method: "resources/read", params: { uri: uri }, meta: meta)
+    def read_resource(uri:, meta: nil, cancellation: nil)
+      response = request(method: "resources/read", params: { uri: uri }, meta: meta, cancellation: cancellation)
 
       response.dig("result", "contents") || []
     end
@@ -300,9 +325,10 @@ module MCP
     # @param name [String] The name of the prompt to get.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Hash] A hash containing the prompt details.
-    def get_prompt(name:, meta: nil)
-      response = request(method: "prompts/get", params: { name: name }, meta: meta)
+    def get_prompt(name:, meta: nil, cancellation: nil)
+      response = request(method: "prompts/get", params: { name: name }, meta: meta, cancellation: cancellation)
 
       response.fetch("result", {})
     end
@@ -315,12 +341,13 @@ module MCP
     # @param context [Hash, nil] Optional context with previously resolved arguments.
     # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Hash] The completion result with `"values"`, `"hasMore"`, and optionally `"total"`.
-    def complete(ref:, argument:, context: nil, meta: nil)
+    def complete(ref:, argument:, context: nil, meta: nil, cancellation: nil)
       params = { ref: ref, argument: argument }
       params[:context] = context if context
 
-      response = request(method: "completion/complete", params: params, meta: meta)
+      response = request(method: "completion/complete", params: params, meta: meta, cancellation: cancellation)
 
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
@@ -328,6 +355,9 @@ module MCP
     # Sends a `ping` request to the server to verify the connection is alive.
     # Per the MCP spec, the server responds with an empty result.
     #
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Hash] An empty hash on success.
     # @raise [ServerError] If the server returns a JSON-RPC error.
     # @raise [ValidationError] If the response `result` is missing or not a Hash.
@@ -336,8 +366,8 @@ module MCP
     #   client.ping # => {}
     #
     # @see https://modelcontextprotocol.io/specification/latest/basic/utilities/ping
-    def ping(meta: nil)
-      result = request(method: Methods::PING, meta: meta)["result"]
+    def ping(meta: nil, cancellation: nil)
+      result = request(method: Methods::PING, meta: meta, cancellation: cancellation)["result"]
       raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
 
       result
@@ -370,17 +400,21 @@ module MCP
     # without mutating the caller's hashes. Per SEP-414, `_meta` carries
     # request-specific metadata such as W3C trace context (`traceparent`,
     # `tracestate`, `baggage`); see {MCP::TraceContext}.
-    def request(method:, params: nil, meta: nil)
+    def request(method:, params: nil, meta: nil, cancellation: nil)
       params = (params || {}).merge(_meta: meta) if meta && !meta.empty?
 
       request_body = {
         jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
+        id: generate_request_id,
         method: method,
       }
       request_body[:params] = params if params
 
-      response = transport.send_request(request: request_body)
+      response = if cancellation
+        dispatch_with_cancellation(request_body, cancellation)
+      else
+        transport.send_request(request: request_body)
+      end
 
       # Guard with `is_a?(Hash)` because custom transports may return non-Hash values.
       if response.is_a?(Hash) && response.key?("error")
@@ -391,8 +425,140 @@ module MCP
       response
     end
 
-    def request_id
+    # Generates a fresh JSON-RPC request id for an outgoing request.
+    # Ids are an internal concern: the public API never accepts or exposes them, and cancellation is driven through
+    # an `MCP::Cancellation` token instead.
+    def generate_request_id
       SecureRandom.uuid
     end
+
+    # Sends `request_body` while watching `cancellation`. The actual blocking `transport.send_request` runs on
+    # a worker thread; the calling thread waits on a Queue that is woken either by the response or by a cancel signal
+    # (whichever arrives first - matching the server-side `StreamableHTTPTransport#cancel_pending_request` race contract).
+    #
+    # When a cancel wins the race, the calling thread raises `MCP::CancelledError` immediately and the `notifications/cancelled`
+    # dispatch runs fire-and-forget on its own thread. We deliberately do not wait for that dispatch here: the calling thread
+    # must not be blocked by a slow or stalled transport write on the cancel path.
+    # The worker thread is also not force-killed; it stays blocked on the underlying I/O until the server actually responds
+    # (or the transport closes). This is the same trade-off the server-side `StreamableHTTPTransport#send_request` accepts and
+    # is noted in the README's Cancellation section.
+    def dispatch_with_cancellation(request_body, cancellation)
+      unless transport.respond_to?(:send_notification)
+        raise NoMethodError, "Cancellation support requires a transport that responds to `send_notification(notification:)` " \
+          "so `notifications/cancelled` can be delivered to the peer. The bundled `MCP::Client::Stdio` and `MCP::Client::HTTP` transports " \
+          "implement this interface; custom transports must add it before passing `cancellation:` to a request method."
+      end
+
+      cancellation.raise_if_cancelled!
+
+      request_id = request_body[:id]
+      queue = Queue.new
+
+      # First-writer-wins gate. Whichever side (worker or on_cancel) flips `completed` first owns the queue's single slot; the loser bails.
+      # This closes the late-cancel window between the worker pushing `:response` and the main thread completing `dispatch_with_cancellation`,
+      # where a callback firing in that gap would otherwise emit a stray `notifications/cancelled` for a request that already succeeded.
+      completion_mutex = Mutex.new
+      completed = false
+      sent_mutex = Mutex.new
+      sent_cond = ConditionVariable.new
+      request_sent = false
+      signal_sent = lambda do
+        sent_mutex.synchronize do
+          unless request_sent
+            request_sent = true
+            sent_cond.broadcast
+          end
+        end
+      end
+
+      Thread.new do
+        Thread.current.report_on_exception = false
+        begin
+          result = transport.send_request(request: request_body, &signal_sent)
+          completion_mutex.synchronize do
+            next if completed
+
+            completed = true
+            queue.push([:response, result])
+          end
+        rescue StandardError => e
+          completion_mutex.synchronize do
+            next if completed
+
+            completed = true
+            queue.push([:error, e])
+          end
+        ensure
+          # Unblock any waiting cancel-dispatch thread on completion (or error)
+          # so it does not stall when the transport ignored the block.
+          signal_sent.call
+        end
+      end
+
+      cancel_hook = cancellation.on_cancel do |reason|
+        should_dispatch = completion_mutex.synchronize do
+          next false if completed
+
+          completed = true
+
+          # Wake the waiting thread first, then dispatch the `notifications/cancelled` send on a separate thread.
+          # The wake-first ordering matters because the cancellation callback can run on the worker thread itself
+          # (e.g. a tool that triggers cancel from within `transport.send_request`), and a synchronous `send_notification`
+          # here would deadlock when the worker holds a transport-level mutex.
+          queue.push([:cancelled, reason])
+          true
+        end
+
+        next unless should_dispatch
+
+        Thread.new do
+          Thread.current.report_on_exception = false
+          # Wait for the worker's send-boundary signal before issuing `notifications/cancelled`. Bundled transports raise
+          # the signal via `&on_sent` from inside `send_request`; custom transports that ignore the block still raise it
+          # via the worker's `ensure -> signal_sent.call`, so the loop is bounded by worker termination rather than by wall-clock time.
+          # The previous fixed-duration fallback could release this thread before the worker reached its send-boundary at all,
+          # allowing the cancel to be issued without any prior request commitment - which the spec only covers under
+          # the receiver's MAY-ignore-unknown-id clause and is therefore avoided here.
+          sent_mutex.synchronize do
+            sent_cond.wait(sent_mutex) until request_sent
+          end
+          cancel(request_id: request_id, reason: reason)
+        rescue StandardError
+          # Swallow notification-send failures: the calling thread has already been woken with `:cancelled` above and
+          # is on its way to raising `MCP::CancelledError`.
+        end
+      end
+
+      tag, payload = queue.pop
+
+      case tag
+      when :response
+        payload
+      when :error
+        raise payload
+      when :cancelled
+        raise MCP::CancelledError.new(request_id: request_id, reason: payload)
+      end
+    ensure
+      cancellation&.off_cancel(cancel_hook) if cancel_hook
+    end
+
+    # Sends `notifications/cancelled` to the server for an in-flight request.
+    # Per spec, this is fire-and-forget: the server is expected to stop processing and suppress its response,
+    # with no acknowledgement returned. Driven internally by {#dispatch_with_cancellation} when a request's
+    # `cancellation` token fires.
+    def cancel(request_id:, reason: nil)
+      params = { requestId: request_id }
+      params[:reason] = reason if reason
+
+      notification = {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        method: Methods::NOTIFICATIONS_CANCELLED,
+        params: params,
+      }
+
+      transport.send_notification(notification: notification)
+      nil
+    end
   end
 end

data/lib/mcp/server/capabilities.rb

@@ -6,6 +6,7 @@ module MCP
       def initialize(capabilities_hash = nil)
         @completions = nil
         @experimental = nil
+        @extensions = nil
         @logging = nil
         @prompts = nil
         @resources = nil
@@ -14,6 +15,7 @@ module MCP
         if capabilities_hash
           support_completions if capabilities_hash.key?(:completions)
           support_experimental(capabilities_hash[:experimental]) if capabilities_hash.key?(:experimental)
+          support_extensions(capabilities_hash[:extensions]) if capabilities_hash.key?(:extensions)
           support_logging if capabilities_hash.key?(:logging)
 
           if capabilities_hash.key?(:prompts)
@@ -45,6 +47,17 @@ module MCP
         @experimental = config || {}
       end
 
+      # Declares support for capability extensions per SEP-2133. Keys are
+      # extension identifiers using the reverse-DNS prefix convention
+      # (e.g. `"io.modelcontextprotocol/tasks"`, `"com.example/feature"`);
+      # values are arbitrary extension-defined configuration objects,
+      # with an empty hash meaning "supported with no settings".
+      # Repeated calls merge, so several extensions can be declared independently.
+      # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133
+      def support_extensions(extensions = {})
+        @extensions = (@extensions || {}).merge(extensions || {})
+      end
+
       def support_logging
         @logging ||= {}
       end
@@ -85,6 +98,7 @@ module MCP
         {
           completions: @completions,
           experimental: @experimental,
+          extensions: @extensions,
           logging: @logging,
           prompts: @prompts,
           resources: @resources,

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

@@ -85,8 +85,10 @@ module MCP
         end
 
         def send_notification(method, params = nil, session_id: nil, related_request_id: nil)
-          # Stateless mode doesn't support notifications
-          raise "Stateless mode does not support notifications" if @stateless
+          # Stateless mode has no streams to deliver notifications on. Report non-delivery instead of raising
+          # so the ephemeral per-request session's notify_* helpers (e.g. progress or log notifications from
+          # a tool handler) degrade gracefully rather than spamming the exception reporter on every call.
+          return false if @stateless
 
           notification = {
             jsonrpc: "2.0",
@@ -575,7 +577,9 @@ module MCP
         # `notifications/initialized`) through the server so it can update session state.
         def dispatch_notification(body_string, session_id)
           server_session = nil
-          if session_id && !@stateless
+          if @stateless
+            server_session = ephemeral_session
+          elsif session_id
             @mutex.synchronize do
               session = @sessions[session_id]
               server_session = session[:server_session] if session
@@ -611,9 +615,10 @@ module MCP
 
         def handle_initialization(body_string, body)
           session_id = nil
-          server_session = nil
 
-          unless @stateless
+          if @stateless
+            server_session = ephemeral_session
+          else
             session_id = SecureRandom.uuid
             server_session = ServerSession.new(server: @server, transport: self, session_id: session_id)
 
@@ -626,17 +631,13 @@ module MCP
             end
           end
 
-          response = if server_session
-            server_session.handle_json(body_string)
-          else
-            @server.handle_json(body_string)
-          end
+          response = server_session.handle_json(body_string)
 
           # If `Server#init` produced an error response (e.g., malformed JSON-RPC envelope),
           # `mark_initialized!` was never called. Discard the orphaned session and omit
           # the `Mcp-Session-Id` header so the client retries from a clean state instead of
           # reusing a never-initialized ID that would later look like a duplicate `initialize`.
-          if server_session && !server_session.initialized?
+          if session_id && !server_session.initialized?
             cleanup_session(session_id)
             session_id = nil
           end
@@ -657,15 +658,15 @@ module MCP
         def handle_regular_request(body_string, session_id, related_request_id: nil)
           server_session = nil
 
-          unless @stateless
-            if session_id
-              error_response = validate_and_touch_session(session_id)
-              return error_response if error_response
+          if @stateless
+            server_session = ephemeral_session
+          elsif session_id
+            error_response = validate_and_touch_session(session_id)
+            return error_response if error_response
 
-              @mutex.synchronize do
-                session = @sessions[session_id]
-                server_session = session[:server_session] if session
-              end
+            @mutex.synchronize do
+              session = @sessions[session_id]
+              server_session = session[:server_session] if session
             end
           end
 
@@ -775,6 +776,13 @@ module MCP
           @mutex.synchronize { @sessions.key?(session_id) }
         end
 
+        # Each stateless POST is self-contained (SEP-2567): handlers run against an ephemeral per-request `ServerSession`
+        # so client info, logging level, and initialized state never leak onto the shared `Server` instance or across concurrent requests.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567
+        def ephemeral_session
+          ServerSession.new(server: @server, transport: self, session_id: nil)
+        end
+
         # Returns true iff a session exists and is not past its idle timeout. Expired sessions
         # are evicted as a side effect so a live request never observes a zombie session that
         # the reaper hasn't yet pruned. Does NOT update `last_active_at`; callers that are

data/lib/mcp/server.rb

@@ -8,6 +8,7 @@ require_relative "methods"
 require_relative "logging_message_notification"
 require_relative "progress"
 require_relative "server_context"
+require_relative "server/capabilities"
 require_relative "server/pagination"
 require_relative "server/transports"
 
@@ -142,7 +143,12 @@ module MCP
 
       validate!
 
-      @capabilities = capabilities || default_capabilities
+      # Accept either a plain Hash or an `MCP::Server::Capabilities` builder.
+      @capabilities = if capabilities.is_a?(Capabilities)
+        capabilities.to_h
+      else
+        capabilities || default_capabilities
+      end
       @client_capabilities = nil
       @logging_message_notification = nil
 
@@ -630,7 +636,7 @@ module MCP
         tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id, cancellation: cancellation
       )
       validate_tool_call_result!(tool, result)
-      result
+      serialize_structured_content_fallback(result)
     rescue RequestHandlerError, CancelledError
       # CancelledError is intentionally not wrapped so `handle_request` can turn it into
       # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
@@ -795,6 +801,18 @@ module MCP
       tool.output_schema.validate_result(result[:structuredContent])
     end
 
+    # Per SEP-2106, `structuredContent` may be any JSON value, not only an object.
+    # Clients on older protocol versions may only read `content`,
+    # so when a tool returns non-object structured content without providing
+    # any content blocks, mirror the value into `content` as serialized JSON text.
+    def serialize_structured_content_fallback(result)
+      structured = result[:structuredContent]
+      return result if structured.nil? || structured.is_a?(Hash)
+      return result unless result[:content].nil? || result[:content].empty?
+
+      result.merge(content: [{ type: "text", text: JSON.generate(structured) }])
+    end
+
     # Whether a tool/prompt handler opts in to receiving an `MCP::ServerContext`.
     # Recognizes `:keyrest` (`**kwargs`) because tools are invoked without a positional argument
     # (`tool.call(**args, server_context:)`), soa `**kwargs`-only signature safely captures `server_context:`.
@@ -810,6 +828,10 @@ module MCP
     end
 
     def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil, related_request_id: nil, cancellation: nil)
+      # Transports parse incoming JSON with `symbolize_names: true`, so `arguments` already arrives symbolized
+      # at every nesting level. This top-level transform only guards callers that hand in string-keyed top-level arguments;
+      # it does not recurse, and nested object keys remain symbols. Tools therefore receive symbol keys all the way down.
+      # See docs/building-servers.md ("Tool argument keys").
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))

data/lib/mcp/server_context.rb

@@ -130,9 +130,14 @@ module MCP
       end
     end
 
-    def method_missing(name, ...)
+    # Forward arguments explicitly with `*args, **kwargs, &block` rather than the `...` forwarding syntax.
+    # The gem supports Ruby 2.7.0 (see `required_ruby_version`), but RuboCop's Parser backend only runs on Ruby 2.7.8,
+    # so leading-argument forwarding like `def method_missing(name, ...)` is allowed by the linter even though it
+    # raises a `SyntaxError` on Ruby 2.7.0 through 2.7.2 (it was added in Ruby 2.7.3). Explicit forwarding keeps
+    # this method loadable on Ruby 2.7.0.
+    def method_missing(name, *args, **kwargs, &block)
       if @context.respond_to?(name)
-        @context.public_send(name, ...)
+        @context.public_send(name, *args, **kwargs, &block)
       else
         super
       end

data/lib/mcp/tool/output_schema.rb

@@ -7,12 +7,29 @@ module MCP
     class OutputSchema < Schema
       class ValidationError < StandardError; end
 
+      # Root-level keywords whose presence means the user already chose a root schema shape,
+      # so no `type: "object"` default should be merged in.
+      ROOT_SCHEMA_KEYWORDS = [:type, :"$ref", :oneOf, :anyOf, :allOf, :not, :if, :const, :enum].freeze
+
       def validate_result(result)
         errors = fully_validate(result)
         if errors.any?
           raise ValidationError, "Invalid result: #{errors.join(", ")}"
         end
       end
+
+      private
+
+      # Per SEP-2106, an output schema may be ANY valid JSON Schema 2020-12 document: object, array, primitive,
+      # or a root-level composition.
+      # Default the root to an object only when no root schema keyword is present, which preserves the wire output
+      # of the common `properties`-only shape while leaving e.g. `{ type: "array" }` or `{ oneOf: [...] }` untouched
+      # (the old unconditional default merged `type: "object"` into root combinators, producing a wrong schema).
+      def apply_default_root_type!
+        return if ROOT_SCHEMA_KEYWORDS.any? { |keyword| @schema.key?(keyword) }
+
+        super
+      end
     end
   end
 end