mcp 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bd75cccadc2edeac35f1784b485b51437d5e504dd9dda10f436b263a813f7b4
-  data.tar.gz: f8b241425d0f10a292718572ccb2f68119b7d58bc14c9da46e6e3f8603a44b1c
+  metadata.gz: f6a956181733036c09b8431db1d1da47e3757165123efd5d5dab5fe1cc522e6a
+  data.tar.gz: fc611e55e4f88e9ca61ad64d4d2578c6e5a9680ceb4d667337787098ca59bbde
 SHA512:
-  metadata.gz: 8008f588d3053237d5c6eec6520979a456fc5dc7ab26f7db9f93eeda7ff72f3f0aeb67d591a590cd260e2281ef601df99a950cb62f75f53f2085a65acf02a8ae
-  data.tar.gz: 2c7af049ec323b39e72ab046731e698319897b3e84f1625d8a3ca735a1775a1ab04baaf207e5e6ab0da9c274165653b13f23d9908d19771c5e247795935e910a
+  metadata.gz: '010991cbd4a1b18214d12d8ce3cb09b3658cba4a1cf72c7475ff76688fe87eef4137bd76eb5ebd7b15309e1aec7ed84909125858accd474f052e1a915ec37ad8'
+  data.tar.gz: 5b9b2994a4fb3769bda007a39ce0cf02c2a9b4fbeeecb48dc74aa4ca66e4d6e066c545f5d473b339561af06cf14f8e546a6e87a92d4d9c0939fe90858cddb3a8

data/README.md

@@ -53,6 +53,7 @@ It implements the Model Context Protocol specification, handling model context r
 - `resources/templates/list` - Lists all registered resource templates and their schemas
 - `completion/complete` - Returns autocompletion suggestions for prompt arguments and resource URIs
 - `sampling/createMessage` - Requests LLM completion from the client (server-to-client)
+- `elicitation/create` - Requests user input from the client (server-to-client)
 
 ### Usage
 
@@ -103,14 +104,56 @@ $ ruby examples/stdio_server.rb
 {"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}
 ```
 
-#### Rails Controller
+#### Streamable HTTP Transport
 
-When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming
-[Streamable HTTP](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http) transport
-requests.
+`MCP::Server::Transports::StreamableHTTPTransport` is a standard Rack app, so it can be mounted in any Rack-compatible framework.
+The following examples show two common integration styles in Rails.
 
-You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
-status codes (e.g., 202 Accepted for notifications).
+> [!IMPORTANT]
+> `MCP::Server::Transports::StreamableHTTPTransport` stores session and SSE stream state in memory,
+> so it must run in a single process. Use a single-process server (e.g., Puma with `workers 0`).
+> Multi-process configurations (Unicorn, or Puma with `workers > 0`) fork separate processes that
+> do not share memory, which breaks session management and SSE connections.
+>
+> When running multiple server instances behind a load balancer, configure your load balancer to use
+> sticky sessions (session affinity) so that requests with the same `Mcp-Session-Id` header are always
+> routed to the same instance.
+>
+> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
+
+##### Rails (mount)
+
+`StreamableHTTPTransport` is a Rack app that can be mounted directly in Rails routes:
+
+```ruby
+# config/routes.rb
+server = MCP::Server.new(
+  name: "my_server",
+  title: "Example Server Display Name",
+  version: "1.0.0",
+  instructions: "Use the tools of this server as a last resort",
+  tools: [SomeTool, AnotherTool],
+  prompts: [MyPrompt],
+)
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+
+Rails.application.routes.draw do
+  mount transport => "/mcp"
+end
+```
+
+`mount` directs all HTTP methods on `/mcp` to the transport. `StreamableHTTPTransport` internally dispatches
+`POST` (client-to-server JSON-RPC messages, with responses optionally streamed via SSE),
+`GET` (optional standalone SSE stream for server-to-client messages), and `DELETE` (session termination) per
+the [MCP Streamable HTTP transport spec](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http),
+so no additional route configuration is needed.
+
+##### Rails (controller)
+
+While the mount approach creates a single server at boot time, the controller approach creates a new server per request.
+This allows you to customize tools, prompts, or configuration based on the request (e.g., different tools per route).
+
+`StreamableHTTPTransport#handle_request` returns proper HTTP status codes (e.g., 202 Accepted for notifications):
 
 ```ruby
 class McpController < ActionController::API
@@ -133,18 +176,6 @@ class McpController < ActionController::API
 end
 ```
 
-> [!IMPORTANT]
-> `MCP::Server::Transports::StreamableHTTPTransport` stores session and SSE stream state in memory,
-> so it must run in a single process. Use a single-process server (e.g., Puma with `workers 0`).
-> Multi-process configurations (Unicorn, or Puma with `workers > 0`) fork separate processes that
-> do not share memory, which breaks session management and SSE connections.
->
-> When running multiple server instances behind a load balancer, configure your load balancer to use
-> sticky sessions (session affinity) so that requests with the same `Mcp-Session-Id` header are always
-> routed to the same instance.
->
-> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
-
 ### Configuration
 
 The gem can be configured using the `MCP.configure` block:
@@ -159,15 +190,17 @@ MCP.configure do |config|
     end
   }
 
-  config.instrumentation_callback = ->(data) {
-    puts "Got instrumentation data #{data.inspect}"
+  config.around_request = ->(data, &request_handler) {
+    logger.info("Start: #{data[:method]}")
+    request_handler.call
+    logger.info("Done: #{data[:method]}, tool: #{data[:tool_name]}")
   }
 end
 ```
 
 or by creating an explicit configuration and passing it into the server.
 This is useful for systems where an application hosts more than one MCP server but
-they might require different instrumentation callbacks.
+they might require different configurations.
 
 ```ruby
 configuration = MCP::Configuration.new
@@ -179,8 +212,10 @@ configuration.exception_reporter = ->(exception, server_context) {
   end
 }
 
-configuration.instrumentation_callback = ->(data) {
-  puts "Got instrumentation data #{data.inspect}"
+configuration.around_request = ->(data, &request_handler) {
+  logger.info("Start: #{data[:method]}")
+  request_handler.call
+  logger.info("Done: #{data[:method]}, tool: #{data[:tool_name]}")
 }
 
 server = MCP::Server.new(
@@ -193,7 +228,8 @@ server = MCP::Server.new(
 
 #### `server_context`
 
-The `server_context` is a user-defined hash that is passed into the server instance and made available to tools, prompts, and exception/instrumentation callbacks. It can be used to provide contextual information such as authentication state, user IDs, or request-specific data.
+The `server_context` is a user-defined hash that is passed into the server instance and made available to tool and prompt calls.
+It can be used to provide contextual information such as authentication state, user IDs, or request-specific data.
 
 **Type:**
 
@@ -210,7 +246,9 @@ server = MCP::Server.new(
 )
 ```
 
-This hash is then passed as the `server_context` argument to tool and prompt calls, and is included in exception and instrumentation callbacks.
+This hash is then passed as the `server_context` keyword argument to tool and prompt calls.
+Note that exception and instrumentation callbacks do not receive this user-defined hash.
+See the relevant sections below for the arguments they receive.
 
 #### Request-specific `_meta` Parameter
 
@@ -263,7 +301,9 @@ end
 The exception reporter receives:
 
 - `exception`: The Ruby exception object that was raised
-- `server_context`: The context hash provided to the server
+- `server_context`: A hash describing where the failure occurred (e.g., `{ request: <raw JSON-RPC request> }`
+  for request handling, `{ notification: "tools_list_changed" }` for notification delivery).
+  This is not the user-defined `server_context` passed to `Server.new`.
 
 **Signature:**
 
@@ -271,9 +311,67 @@ The exception reporter receives:
 exception_reporter = ->(exception, server_context) { ... }
 ```
 
-##### Instrumentation Callback
+##### Around Request
 
-The instrumentation callback receives a hash with the following possible keys:
+The `around_request` hook wraps request handling, allowing you to execute code before and after each request.
+This is useful for Application Performance Monitoring (APM) tracing, logging, or other observability needs.
+
+The hook receives a `data` hash and a `request_handler` block. You must call `request_handler.call` to execute the request:
+
+**Signature:**
+
+```ruby
+around_request = ->(data, &request_handler) { request_handler.call }
+```
+
+**`data` availability by timing:**
+
+- Before `request_handler.call`: `method`
+- After `request_handler.call`: `tool_name`, `tool_arguments`, `prompt_name`, `resource_uri`, `error`, `client`
+- Not available inside `around_request`: `duration` (added after `around_request` returns)
+
+> [!NOTE]
+> `tool_name`, `prompt_name` and `resource_uri` may only be populated for the corresponding request methods
+> (`tools/call`, `prompts/get`, `resources/read`), and may not be set depending on how the request is handled
+> (for example, `prompt_name` is not recorded when the prompt is not found).
+> `duration` is added after `around_request` returns, so it is not visible from within the hook.
+
+**Example:**
+
+```ruby
+MCP.configure do |config|
+  config.around_request = ->(data, &request_handler) {
+    logger.info("Start: #{data[:method]}")
+    request_handler.call
+    logger.info("Done: #{data[:method]}, tool: #{data[:tool_name]}")
+  }
+end
+```
+
+##### Instrumentation Callback (soft-deprecated)
+
+> [!NOTE]
+> `instrumentation_callback` is soft-deprecated. Use `around_request` instead.
+>
+> To migrate, wrap the call in `begin/ensure` so the callback still runs when the request fails:
+>
+> ```ruby
+> # Before
+> config.instrumentation_callback = ->(data) { log(data) }
+>
+> # After
+> config.around_request = ->(data, &request_handler) do
+>   request_handler.call
+> ensure
+>   log(data)
+> end
+> ```
+>
+> Note that `data[:duration]` is not available inside `around_request`.
+> If you need it, measure elapsed time yourself within the hook, or keep using `instrumentation_callback`.
+
+The instrumentation callback is called after each request finishes, whether successfully or with an error.
+It receives a hash with the following possible keys:
 
 - `method`: (String) The protocol method called (e.g., "ping", "tools/list")
 - `tool_name`: (String, optional) The name of the tool called
@@ -284,25 +382,10 @@ The instrumentation callback receives a hash with the following possible keys:
 - `duration`: (Float) Duration of the call in seconds
 - `client`: (Hash, optional) Client information with `name` and `version` keys, from the initialize request
 
-> [!NOTE]
-> `tool_name`, `prompt_name` and `resource_uri` are only populated if a matching handler is registered.
-> This is to avoid potential issues with metric cardinality.
-
-**Type:**
+**Signature:**
 
 ```ruby
 instrumentation_callback = ->(data) { ... }
-# where data is a Hash with keys as described above
-```
-
-**Example:**
-
-```ruby
-MCP.configure do |config|
-  config.instrumentation_callback = ->(data) {
-    puts "Instrumentation: #{data.inspect}"
-  }
-end
 ```
 
 ### Server Protocol Version
@@ -823,8 +906,7 @@ This enables servers to leverage the client's LLM capabilities without needing d
 **Using Sampling in Tools:**
 
 Tools that accept a `server_context:` parameter can call `create_sampling_message` on it.
-The request is automatically routed to the correct client session.
-Set `server.server_context = server` so that `server_context.create_sampling_message` delegates to the server:
+The request is automatically routed to the correct client session:
 
 ```ruby
 class SummarizeTool < MCP::Tool
@@ -852,7 +934,6 @@ class SummarizeTool < MCP::Tool
 end
 
 server = MCP::Server.new(name: "my_server", tools: [SummarizeTool])
-server.server_context = server
 ```
 
 **Parameters:**
@@ -873,86 +954,8 @@ Optional:
 - `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
 - `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
 
-**Direct Usage:**
-
-`Server#create_sampling_message` can also be called directly outside of tools:
-
-```ruby
-result = server.create_sampling_message(
-  messages: [
-    { role: "user", content: { type: "text", text: "What is the capital of France?" } }
-  ],
-  max_tokens: 100,
-  system_prompt: "You are a helpful assistant.",
-  temperature: 0.7
-)
-```
-
-Result contains the LLM response:
-
-```ruby
-{
-  role: "assistant",
-  content: { type: "text", text: "The capital of France is Paris." },
-  model: "claude-3-sonnet-20240307",
-  stopReason: "endTurn"
-}
-```
-
-For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools
-to route the request to the correct client session.
-
-**Tool Use in Sampling:**
-
-When tools are provided in a sampling request, the LLM can call them during generation.
-The server must handle tool calls and continue the conversation with tool results:
-
-```ruby
-result = server.create_sampling_message(
-  messages: [
-    { role: "user", content: { type: "text", text: "What's the weather in Paris?" } }
-  ],
-  max_tokens: 1000,
-  tools: [
-    {
-      name: "get_weather",
-      description: "Get weather for a city",
-      inputSchema: {
-        type: "object",
-        properties: { city: { type: "string" } },
-        required: ["city"]
-      }
-    }
-  ],
-  tool_choice: { mode: "auto" }
-)
-
-if result[:stopReason] == "toolUse"
-  tool_results = result[:content].map do |tool_use|
-    weather_data = get_weather(tool_use[:input][:city])
-
-    {
-      type: "tool_result",
-      toolUseId: tool_use[:id],
-      content: [{ type: "text", text: weather_data.to_json }]
-    }
-  end
-
-  final_result = server.create_sampling_message(
-    messages: [
-      { role: "user", content: { type: "text", text: "What's the weather in Paris?" } },
-      { role: "assistant", content: result[:content] },
-      { role: "user", content: tool_results }
-    ],
-    max_tokens: 1000,
-    tools: [...]
-  )
-end
-```
-
 **Error Handling:**
 
-- Raises `RuntimeError` if transport is not set
 - Raises `RuntimeError` if client does not support `sampling` capability
 - Raises `RuntimeError` if `tools` are used but client lacks `sampling.tools` capability
 - Raises `StandardError` if client returns an error response
@@ -1085,6 +1088,108 @@ The SDK automatically enforces the 100-item limit per the MCP specification.
 The server validates that the referenced prompt, resource, or resource template is registered before calling the handler.
 Requests for unknown references return an error.
 
+### Elicitation
+
+The MCP Ruby SDK supports [elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation),
+which allows servers to request additional information from users through the client during tool execution.
+
+Elicitation is a **server-to-client request**. The server sends a request and blocks until the user responds via the client.
+
+#### Capabilities
+
+Clients must declare the `elicitation` capability during initialization. The server checks this before sending any elicitation request
+and raises a `RuntimeError` if the client does not support it.
+
+For URL mode support, the client must also declare `elicitation.url` capability.
+
+#### Using Elicitation in Tools
+
+Tools that accept a `server_context:` parameter can call `create_form_elicitation` on it:
+
+```ruby
+server.define_tool(name: "collect_info", description: "Collect user info") do |server_context:|
+  result = server_context.create_form_elicitation(
+    message: "Please provide your name",
+    requested_schema: {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"],
+    },
+  )
+
+  MCP::Tool::Response.new([{ type: "text", text: "Hello, #{result[:content][:name]}" }])
+end
+```
+
+#### Form Mode
+
+Form mode collects structured data from the user directly through the MCP client:
+
+```ruby
+server.define_tool(name: "collect_contact", description: "Collect contact info") do |server_context:|
+  result = server_context.create_form_elicitation(
+    message: "Please provide your contact information",
+    requested_schema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Your full name" },
+        email: { type: "string", format: "email", description: "Your email address" },
+      },
+      required: ["name", "email"],
+    },
+  )
+
+  text = case result[:action]
+  when "accept"
+    "Hello, #{result[:content][:name]} (#{result[:content][:email]})"
+  when "decline"
+    "User declined"
+  when "cancel"
+    "User cancelled"
+  end
+
+  MCP::Tool::Response.new([{ type: "text", text: text }])
+end
+```
+
+#### URL Mode
+
+URL mode directs the user to an external URL for out-of-band interactions such as OAuth flows:
+
+```ruby
+server.define_tool(name: "authorize_github", description: "Authorize GitHub") do |server_context:|
+  elicitation_id = SecureRandom.uuid
+
+  result = server_context.create_url_elicitation(
+    message: "Please authorize access to your GitHub account",
+    url: "https://example.com/oauth/authorize?elicitation_id=#{elicitation_id}",
+    elicitation_id: elicitation_id,
+  )
+
+  server_context.notify_elicitation_complete(elicitation_id: elicitation_id)
+
+  MCP::Tool::Response.new([{ type: "text", text: "Authorization complete" }])
+end
+```
+
+#### URLElicitationRequiredError
+
+When a tool cannot proceed until an out-of-band elicitation is completed, raise `MCP::Server::URLElicitationRequiredError`.
+This returns a JSON-RPC error with code `-32042` to the client:
+
+```ruby
+server.define_tool(name: "access_github", description: "Access GitHub") do |server_context:|
+  raise MCP::Server::URLElicitationRequiredError.new([
+    {
+      mode: "url",
+      elicitationId: SecureRandom.uuid,
+      url: "https://example.com/oauth/authorize",
+      message: "GitHub authorization is required.",
+    },
+  ])
+end
+```
+
 ### Logging
 
 The MCP Ruby SDK supports structured logging through the `notify_log_message` method, following the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
@@ -1250,7 +1355,6 @@ end
 ### Unsupported Features (to be implemented in future versions)
 
 - Resource subscriptions
-- Elicitation
 
 ## Building an MCP Client
 

data/lib/json_rpc_handler.rb

@@ -117,20 +117,27 @@ module JsonRpcHandler
   end
 
   def handle_request_error(error, id, id_validation_pattern)
-    error_type = error.respond_to?(:error_type) ? error.error_type : nil
-
-    code, message = case error_type
-    when :invalid_request then [ErrorCode::INVALID_REQUEST, "Invalid Request"]
-    when :invalid_params then [ErrorCode::INVALID_PARAMS, "Invalid params"]
-    when :parse_error then [ErrorCode::PARSE_ERROR, "Parse error"]
-    when :internal_error then [ErrorCode::INTERNAL_ERROR, "Internal error"]
-    else [ErrorCode::INTERNAL_ERROR, "Internal error"]
+    if error.respond_to?(:error_code) && error.error_code
+      code = error.error_code
+      message = error.message
+    else
+      error_type = error.respond_to?(:error_type) ? error.error_type : nil
+
+      code, message = case error_type
+      when :invalid_request then [ErrorCode::INVALID_REQUEST, "Invalid Request"]
+      when :invalid_params then [ErrorCode::INVALID_PARAMS, "Invalid params"]
+      when :parse_error then [ErrorCode::PARSE_ERROR, "Parse error"]
+      when :internal_error then [ErrorCode::INTERNAL_ERROR, "Internal error"]
+      else [ErrorCode::INTERNAL_ERROR, "Internal error"]
+      end
     end
 
+    data = error.respond_to?(:error_data) && error.error_data ? error.error_data : error.message
+
     error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
       code: code,
       message: message,
-      data: error.message,
+      data: data,
     })
   end
 

data/lib/mcp/configuration.rb

@@ -7,11 +7,18 @@ module MCP
       LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
     ]
 
-    attr_writer :exception_reporter, :instrumentation_callback
+    attr_writer :exception_reporter, :around_request
 
-    def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil,
+    # @deprecated Use {#around_request=} instead. `instrumentation_callback`
+    #   fires only after a request completes and cannot wrap execution in a
+    #   surrounding block (e.g. for Application Performance Monitoring (APM) spans).
+    # @see #around_request=
+    attr_writer :instrumentation_callback
+
+    def initialize(exception_reporter: nil, around_request: nil, instrumentation_callback: nil, protocol_version: nil,
       validate_tool_call_arguments: true)
       @exception_reporter = exception_reporter
+      @around_request = around_request
       @instrumentation_callback = instrumentation_callback
       @protocol_version = protocol_version
       if protocol_version
@@ -50,10 +57,24 @@ module MCP
       !@exception_reporter.nil?
     end
 
+    def around_request
+      @around_request || default_around_request
+    end
+
+    def around_request?
+      !@around_request.nil?
+    end
+
+    # @deprecated Use {#around_request} instead. `instrumentation_callback`
+    #   fires only after a request completes and cannot wrap execution in a
+    #   surrounding block (e.g. for Application Performance Monitoring (APM) spans).
+    # @see #around_request
     def instrumentation_callback
       @instrumentation_callback || default_instrumentation_callback
     end
 
+    # @deprecated Use {#around_request?} instead.
+    # @see #around_request?
     def instrumentation_callback?
       !@instrumentation_callback.nil?
     end
@@ -72,20 +93,30 @@ module MCP
       else
         @exception_reporter
       end
+
+      around_request = if other.around_request?
+        other.around_request
+      else
+        @around_request
+      end
+
       instrumentation_callback = if other.instrumentation_callback?
         other.instrumentation_callback
       else
         @instrumentation_callback
       end
+
       protocol_version = if other.protocol_version?
         other.protocol_version
       else
         @protocol_version
       end
+
       validate_tool_call_arguments = other.validate_tool_call_arguments
 
       Configuration.new(
         exception_reporter: exception_reporter,
+        around_request: around_request,
         instrumentation_callback: instrumentation_callback,
         protocol_version: protocol_version,
         validate_tool_call_arguments: validate_tool_call_arguments,
@@ -111,6 +142,11 @@ module MCP
       @default_exception_reporter ||= ->(exception, server_context) {}
     end
 
+    def default_around_request
+      @default_around_request ||= ->(_data, &request_handler) { request_handler.call }
+    end
+
+    # @deprecated Use {#default_around_request} instead.
     def default_instrumentation_callback
       @default_instrumentation_callback ||= ->(data) {}
     end

data/lib/mcp/content.rb

@@ -3,56 +3,60 @@
 module MCP
   module Content
     class Text
-      attr_reader :text, :annotations
+      attr_reader :text, :annotations, :meta
 
-      def initialize(text, annotations: nil)
+      def initialize(text, annotations: nil, meta: nil)
         @text = text
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { text: text, annotations: annotations, type: "text" }.compact
+        { text: text, annotations: annotations, _meta: meta, type: "text" }.compact
       end
     end
 
     class Image
-      attr_reader :data, :mime_type, :annotations
+      attr_reader :data, :mime_type, :annotations, :meta
 
-      def initialize(data, mime_type, annotations: nil)
+      def initialize(data, mime_type, annotations: nil, meta: nil)
         @data = data
         @mime_type = mime_type
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { data: data, mimeType: mime_type, annotations: annotations, type: "image" }.compact
+        { data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "image" }.compact
       end
     end
 
     class Audio
-      attr_reader :data, :mime_type, :annotations
+      attr_reader :data, :mime_type, :annotations, :meta
 
-      def initialize(data, mime_type, annotations: nil)
+      def initialize(data, mime_type, annotations: nil, meta: nil)
         @data = data
         @mime_type = mime_type
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { data: data, mimeType: mime_type, annotations: annotations, type: "audio" }.compact
+        { data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "audio" }.compact
       end
     end
 
     class EmbeddedResource
-      attr_reader :resource, :annotations
+      attr_reader :resource, :annotations, :meta
 
-      def initialize(resource, annotations: nil)
+      def initialize(resource, annotations: nil, meta: nil)
         @resource = resource
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { resource: resource.to_h, annotations: annotations, type: "resource" }.compact
+        { resource: resource.to_h, annotations: annotations, _meta: meta, type: "resource" }.compact
       end
     end
   end

data/lib/mcp/instrumentation.rb

@@ -2,19 +2,40 @@
 
 module MCP
   module Instrumentation
-    def instrument_call(method, &block)
+    def instrument_call(method, server_context: {}, exception_already_reported: nil, &block)
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       begin
         @instrumentation_data = {}
         add_instrumentation_data(method: method)
 
-        result = yield block
+        result = configuration.around_request.call(@instrumentation_data, &block)
 
         result
+      rescue => e
+        already_reported = begin
+          !!exception_already_reported&.call(e)
+        # rubocop:disable Lint/RescueException
+        rescue Exception
+          # rubocop:enable Lint/RescueException
+          # The predicate is expected to be side-effect-free and return a boolean.
+          # Any exception raised from it (including non-StandardError such as SystemExit)
+          # must not shadow the original exception.
+          false
+        end
+
+        unless already_reported
+          add_instrumentation_data(error: :internal_error) unless @instrumentation_data.key?(:error)
+          configuration.exception_reporter.call(e, server_context)
+        end
+
+        raise
       ensure
         end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         add_instrumentation_data(duration: end_time - start_time)
 
+        # Backward compatibility: `instrumentation_callback` is soft-deprecated
+        # in favor of `around_request`, but existing callers still expect it
+        # to fire after every request until it is removed in a future version.
         configuration.instrumentation_callback.call(@instrumentation_data)
       end
     end

data/lib/mcp/methods.rb

@@ -33,6 +33,7 @@ module MCP
     NOTIFICATIONS_MESSAGE = "notifications/message"
     NOTIFICATIONS_PROGRESS = "notifications/progress"
     NOTIFICATIONS_CANCELLED = "notifications/cancelled"
+    NOTIFICATIONS_ELICITATION_COMPLETE = "notifications/elicitation/complete"
 
     class MissingRequiredCapabilityError < StandardError
       attr_reader :method
@@ -79,8 +80,8 @@ module MCP
           require_capability!(method, capabilities, :sampling)
         when ELICITATION_CREATE
           require_capability!(method, capabilities, :elicitation)
-        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED
-          # No specific capability required for initialize, ping, progress or cancelled
+        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
+          # No specific capability required.
         end
       end
 

data/lib/mcp/prompt/result.rb

@@ -3,15 +3,16 @@
 module MCP
   class Prompt
     class Result
-      attr_reader :description, :messages
+      attr_reader :description, :messages, :meta
 
-      def initialize(description: nil, messages: [])
+      def initialize(description: nil, messages: [], meta: nil)
         @description = description
         @messages = messages
+        @meta = meta
       end
 
       def to_h
-        { description: description, messages: messages.map(&:to_h) }.compact
+        { description: description, messages: messages.map(&:to_h), _meta: meta }.compact
       end
     end
   end

data/lib/mcp/resource/contents.rb

@@ -3,23 +3,24 @@
 module MCP
   class Resource
     class Contents
-      attr_reader :uri, :mime_type
+      attr_reader :uri, :mime_type, :meta
 
-      def initialize(uri:, mime_type: nil)
+      def initialize(uri:, mime_type: nil, meta: nil)
         @uri = uri
         @mime_type = mime_type
+        @meta = meta
       end
 
       def to_h
-        { uri: uri, mimeType: mime_type }.compact
+        { uri: uri, mimeType: mime_type, _meta: meta }.compact
       end
     end
 
     class TextContents < Contents
       attr_reader :text
 
-      def initialize(text:, uri:, mime_type:)
-        super(uri: uri, mime_type: mime_type)
+      def initialize(text:, uri:, mime_type:, meta: nil)
+        super(uri: uri, mime_type: mime_type, meta: meta)
         @text = text
       end
 
@@ -31,8 +32,8 @@ module MCP
     class BlobContents < Contents
       attr_reader :data
 
-      def initialize(data:, uri:, mime_type:)
-        super(uri: uri, mime_type: mime_type)
+      def initialize(data:, uri:, mime_type:, meta: nil)
+        super(uri: uri, mime_type: mime_type, meta: meta)
         @data = data
       end
 

data/lib/mcp/resource.rb

@@ -5,15 +5,16 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :icons, :mime_type
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @meta = meta
     end
 
     def to_h
@@ -24,6 +25,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        _meta: meta,
       }.compact
     end
   end

data/lib/mcp/resource_template.rb

@@ -2,15 +2,16 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type
+    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :meta
 
-    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @meta = meta
     end
 
     def to_h
@@ -21,6 +22,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        _meta: meta,
       }.compact
     end
   end

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

@@ -3,6 +3,15 @@
 require "json"
 require_relative "../../transport"
 
+# This file is autoloaded only when `StreamableHTTPTransport` is referenced,
+# so the `rack` dependency does not affect `StdioTransport` users.
+begin
+  require "rack"
+rescue LoadError
+  raise LoadError, "The 'rack' gem is required to use the StreamableHTTPTransport. " \
+    "Add it to your Gemfile: gem 'rack'"
+end
+
 module MCP
   class Server
     module Transports
@@ -39,6 +48,11 @@ module MCP
         STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
         SESSION_REAP_INTERVAL = 60
 
+        # Rack app interface. This transport can be mounted as a Rack app.
+        def call(env)
+          handle_request(Rack::Request.new(env))
+        end
+
         def handle_request(request)
           case request.env["REQUEST_METHOD"]
           when "POST"
@@ -546,7 +560,7 @@ module MCP
             end
           end
 
-          [200, SSE_HEADERS, body]
+          [200, SSE_HEADERS.dup, body]
         end
 
         # Returns the SSE stream available for server-to-client messages.
@@ -628,7 +642,7 @@ module MCP
         def setup_sse_stream(session_id)
           body = create_sse_body(session_id)
 
-          [200, SSE_HEADERS, body]
+          [200, SSE_HEADERS.dup, body]
         end
 
         def create_sse_body(session_id)

data/lib/mcp/server.rb

@@ -31,14 +31,27 @@ module MCP
     MAX_COMPLETION_VALUES = 100
 
     class RequestHandlerError < StandardError
-      attr_reader :error_type
-      attr_reader :original_error
+      attr_reader :error_type, :original_error, :error_code, :error_data
 
-      def initialize(message, request, error_type: :internal_error, original_error: nil)
+      def initialize(message, request, error_type: :internal_error, original_error: nil, error_code: nil, error_data: nil)
         super(message)
         @request = request
         @error_type = error_type
         @original_error = original_error
+        @error_code = error_code
+        @error_data = error_data
+      end
+    end
+
+    class URLElicitationRequiredError < RequestHandlerError
+      def initialize(elicitations)
+        super(
+          "URL elicitation required",
+          nil,
+          error_type: :url_elicitation_required,
+          error_code: -32042,
+          error_data: { elicitations: elicitations },
+        )
       end
     end
 
@@ -114,7 +127,6 @@ module MCP
         # No op handlers for currently unsupported methods
         Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
         Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
-        Methods::ELICITATION_CREATE => ->(_) {},
       }
       @transport = transport
     end
@@ -206,44 +218,6 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
-    # Sends a `sampling/createMessage` request to the client.
-    # For single-client transports (e.g., `StdioTransport`). For multi-client transports
-    # (e.g., `StreamableHTTPTransport`), use `ServerSession#create_sampling_message` instead
-    # to ensure the request is routed to the correct client.
-    def create_sampling_message(
-      messages:,
-      max_tokens:,
-      system_prompt: nil,
-      model_preferences: nil,
-      include_context: nil,
-      temperature: nil,
-      stop_sequences: nil,
-      metadata: nil,
-      tools: nil,
-      tool_choice: nil,
-      related_request_id: nil
-    )
-      unless @transport
-        raise "Cannot send sampling request without a transport."
-      end
-
-      params = build_sampling_params(
-        @client_capabilities,
-        messages: messages,
-        max_tokens: max_tokens,
-        system_prompt: system_prompt,
-        model_preferences: model_preferences,
-        include_context: include_context,
-        temperature: temperature,
-        stop_sequences: stop_sequences,
-        metadata: metadata,
-        tools: tools,
-        tool_choice: tool_choice,
-      )
-
-      @transport.send_request(Methods::SAMPLING_CREATE_MESSAGE, params)
-    end
-
     # Sets a custom handler for `resources/read` requests.
     # The block receives the parsed request params and should return resource
     # contents. The return value is set as the `contents` field of the response.
@@ -375,7 +349,7 @@ module MCP
     def handle_request(request, method, session: nil, related_request_id: nil)
       handler = @handlers[method]
       unless handler
-        instrument_call("unsupported_method") do
+        instrument_call("unsupported_method", server_context: { request: request }) do
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
         end
@@ -385,7 +359,12 @@ module MCP
       Methods.ensure_capability!(method, capabilities)
 
       ->(params) {
-        instrument_call(method) do
+        reported_exception = nil
+        instrument_call(
+          method,
+          server_context: { request: request },
+          exception_already_reported: ->(e) { reported_exception.equal?(e) },
+        ) do
           result = case method
           when Methods::INITIALIZE
             init(params, session: session)
@@ -415,11 +394,14 @@ module MCP
         rescue RequestHandlerError => e
           report_exception(e.original_error || e, { request: request })
           add_instrumentation_data(error: e.error_type)
+          reported_exception = e
           raise e
         rescue => e
           report_exception(e, { request: request })
           add_instrumentation_data(error: :internal_error)
-          raise RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+          wrapped = RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+          reported_exception = wrapped
+          raise wrapped
         end
       }
     end

data/lib/mcp/server_context.rb

@@ -43,6 +43,42 @@ module MCP
       end
     end
 
+    # Delegates to the session so the request is scoped to the originating client.
+    # Falls back to `@context` (via `method_missing`) when `@notification_target`
+    # does not support elicitation.
+    def create_form_elicitation(**kwargs)
+      if @notification_target.respond_to?(:create_form_elicitation)
+        @notification_target.create_form_elicitation(**kwargs, related_request_id: @related_request_id)
+      elsif @context.respond_to?(:create_form_elicitation)
+        @context.create_form_elicitation(**kwargs, related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'create_form_elicitation' for #{self}"
+      end
+    end
+
+    # Delegates to the session so the request is scoped to the originating client.
+    # Falls back to `@context` when `@notification_target` does not support URL mode elicitation.
+    def create_url_elicitation(**kwargs)
+      if @notification_target.respond_to?(:create_url_elicitation)
+        @notification_target.create_url_elicitation(**kwargs, related_request_id: @related_request_id)
+      elsif @context.respond_to?(:create_url_elicitation)
+        @context.create_url_elicitation(**kwargs, related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'create_url_elicitation' for #{self}"
+      end
+    end
+
+    # Delegates to the session so the notification is scoped to the originating client.
+    def notify_elicitation_complete(**kwargs)
+      if @notification_target.respond_to?(:notify_elicitation_complete)
+        @notification_target.notify_elicitation_complete(**kwargs)
+      elsif @context.respond_to?(:notify_elicitation_complete)
+        @context.notify_elicitation_complete(**kwargs)
+      else
+        raise NoMethodError, "undefined method 'notify_elicitation_complete' for #{self}"
+      end
+    end
+
     def method_missing(name, ...)
       if @context.respond_to?(name)
         @context.public_send(name, ...)

data/lib/mcp/server_session.rb

@@ -47,6 +47,35 @@ module MCP
       send_to_transport_request(Methods::SAMPLING_CREATE_MESSAGE, params, related_request_id: related_request_id)
     end
 
+    # Sends an `elicitation/create` request (form mode) scoped to this session.
+    def create_form_elicitation(message:, requested_schema:, related_request_id: nil)
+      unless client_capabilities&.dig(:elicitation)
+        raise "Client does not support elicitation. " \
+          "The client must declare the `elicitation` capability during initialization."
+      end
+
+      params = { mode: "form", message: message, requestedSchema: requested_schema }
+      send_to_transport_request(Methods::ELICITATION_CREATE, params, related_request_id: related_request_id)
+    end
+
+    # Sends an `elicitation/create` request (URL mode) scoped to this session.
+    def create_url_elicitation(message:, url:, elicitation_id:, related_request_id: nil)
+      unless client_capabilities&.dig(:elicitation, :url)
+        raise "Client does not support URL mode elicitation. " \
+          "The client must declare the `elicitation.url` capability during initialization."
+      end
+
+      params = { mode: "url", message: message, url: url, elicitationId: elicitation_id }
+      send_to_transport_request(Methods::ELICITATION_CREATE, params, related_request_id: related_request_id)
+    end
+
+    # Sends an elicitation complete notification scoped to this session.
+    def notify_elicitation_complete(elicitation_id:)
+      send_to_transport(Methods::NOTIFICATIONS_ELICITATION_COMPLETE, { elicitationId: elicitation_id })
+    rescue => e
+      @server.report_exception(e, notification: "elicitation_complete")
+    end
+
     # Sends a progress notification to this session only.
     def notify_progress(progress_token:, progress:, total: nil, message: nil, related_request_id: nil)
       params = {

data/lib/mcp/tool/response.rb

@@ -5,9 +5,9 @@ module MCP
     class Response
       NOT_GIVEN = Object.new.freeze
 
-      attr_reader :content, :structured_content
+      attr_reader :content, :structured_content, :meta
 
-      def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil)
+      def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil, meta: nil)
         if deprecated_error != NOT_GIVEN
           warn("Passing `error` with the 2nd argument of `Response.new` is deprecated. Use keyword argument like `Response.new(content, error: error)` instead.", uplevel: 1)
           error = deprecated_error
@@ -16,6 +16,7 @@ module MCP
         @content = content || []
         @error = error
         @structured_content = structured_content
+        @meta = meta
       end
 
       def error?
@@ -23,7 +24,7 @@ module MCP
       end
 
       def to_h
-        { content: content, isError: error?, structuredContent: @structured_content }.compact
+        { content: content, isError: error?, structuredContent: @structured_content, _meta: meta }.compact
       end
     end
   end

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -78,7 +78,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.12.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.13.0
   homepage_uri: https://github.com/modelcontextprotocol/ruby-sdk
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues