mcp 0.10.0 → 0.15.0

data/README.md

@@ -38,6 +38,10 @@ It implements the Model Context Protocol specification, handling model context r
 - Supports resource registration and retrieval
 - Supports stdio & Streamable HTTP (including SSE) transports
 - Supports notifications for list changes (tools, prompts, resources)
+- Supports roots (server-to-client filesystem boundary queries)
+- Supports sampling (server-to-client LLM completion requests)
+- Supports cursor-based pagination for list operations
+- Supports server-side cancellation of in-flight requests (notifications/cancelled)
 
 ### Supported Methods
 
@@ -50,1012 +54,1682 @@ It implements the Model Context Protocol specification, handling model context r
 - `resources/list` - Lists all registered resources and their schemas
 - `resources/read` - Retrieves a specific resource by name
 - `resources/templates/list` - Lists all registered resource templates and their schemas
+- `resources/subscribe` - Subscribes to updates for a specific resource
+- `resources/unsubscribe` - Unsubscribes from updates for a specific resource
+- `completion/complete` - Returns autocompletion suggestions for prompt arguments and resource URIs
+- `roots/list` - Requests filesystem roots from the client (server-to-client)
+- `sampling/createMessage` - Requests LLM completion from the client (server-to-client)
+- `elicitation/create` - Requests user input from the client (server-to-client)
 
-### Custom Methods
+### Usage
 
-The server allows you to define custom JSON-RPC methods beyond the standard MCP protocol methods using the `define_custom_method` method:
+#### Stdio Transport
+
+If you want to build a local command-line application, you can use the stdio transport:
 
 ```ruby
-server = MCP::Server.new(name: "my_server")
+require "mcp"
 
-# Define a custom method that returns a result
-server.define_custom_method(method_name: "add") do |params|
-  params[:a] + params[:b]
-end
+# Create a simple tool
+class ExampleTool < MCP::Tool
+  description "A simple example tool that echoes back its arguments"
+  input_schema(
+    properties: {
+      message: { type: "string" },
+    },
+    required: ["message"]
+  )
 
-# Define a custom notification method (returns nil)
-server.define_custom_method(method_name: "notify") do |params|
-  # Process notification
-  nil
+  class << self
+    def call(message:, server_context:)
+      MCP::Tool::Response.new([{
+        type: "text",
+        text: "Hello from example tool! Message: #{message}",
+      }])
+    end
+  end
 end
+
+# Set up the server
+server = MCP::Server.new(
+  name: "example_server",
+  tools: [ExampleTool],
+)
+
+# Create and start the transport
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open
 ```
 
-**Key Features:**
+You can run this script and then type in requests to the server at the command line.
 
-- Accepts any method name as a string
-- Block receives the request parameters as a hash
-- Can handle both regular methods (with responses) and notifications
-- Prevents overriding existing MCP protocol methods
-- Supports instrumentation callbacks for monitoring
+```console
+$ ruby examples/stdio_server.rb
+{"jsonrpc":"2.0","id":"1","method":"ping"}
+{"jsonrpc":"2.0","id":"2","method":"tools/list"}
+{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}
+```
 
-**Usage Example:**
+#### Streamable HTTP Transport
+
+`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.
+
+> [!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
-# Client request
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "method": "add",
-  "params": { "a": 5, "b": 3 }
-}
+# 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)
 
-# Server response
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "result": 8
-}
+Rails.application.routes.draw do
+  mount transport => "/mcp"
+end
 ```
 
-**Error Handling:**
-
-- Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
-- Supports the same exception reporting and instrumentation as standard methods
+`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.
 
-### Notifications
+##### Rails (controller)
 
-The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
+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).
 
-#### Notification Methods
+`StreamableHTTPTransport#handle_request` returns proper HTTP status codes (e.g., 202 Accepted for notifications):
 
-The server provides the following notification methods:
+```ruby
+class McpController < ActionController::API
+  def create
+    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],
+      server_context: { user_id: current_user.id },
+    )
+    # Since the `MCP-Session-Id` is not shared across requests, `stateless: true` is set.
+    transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
+    status, headers, body = transport.handle_request(request)
 
-- `notify_tools_list_changed` - Send a notification when the tools list changes
-- `notify_prompts_list_changed` - Send a notification when the prompts list changes
-- `notify_resources_list_changed` - Send a notification when the resources list changes
-- `notify_log_message` - Send a structured logging notification message
+    render(json: body.first, status: status, headers: headers)
+  end
+end
+```
 
-#### Session Scoping
+### Configuration
 
-When using Streamable HTTP transport with multiple clients, each client connection gets its own session. Notifications are scoped as follows:
+The gem can be configured using the `MCP.configure` block:
 
-- **`report_progress`** and **`notify_log_message`** called via `server_context` inside a tool handler are automatically sent only to the requesting client.
-No extra configuration is needed.
-- **`notify_tools_list_changed`**, **`notify_prompts_list_changed`**, and **`notify_resources_list_changed`** are always broadcast to all connected clients,
-as they represent server-wide state changes. These should be called on the `server` instance directly.
+```ruby
+MCP.configure do |config|
+  config.exception_reporter = ->(exception, server_context) {
+    # Your exception reporting logic here
+    # For example with Bugsnag:
+    Bugsnag.notify(exception) do |report|
+      report.add_metadata(:model_context_protocol, server_context)
+    end
+  }
 
-#### Notification Format
+  config.around_request = ->(data, &request_handler) {
+    logger.info("Start: #{data[:method]}")
+    request_handler.call
+    logger.info("Done: #{data[:method]}, tool: #{data[:tool_name]}")
+  }
+end
+```
 
-Notifications follow the JSON-RPC 2.0 specification and use these method names:
+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 configurations.
 
-- `notifications/tools/list_changed`
-- `notifications/prompts/list_changed`
-- `notifications/resources/list_changed`
-- `notifications/progress`
-- `notifications/message`
+```ruby
+configuration = MCP::Configuration.new
+configuration.exception_reporter = ->(exception, server_context) {
+  # Your exception reporting logic here
+  # For example with Bugsnag:
+  Bugsnag.notify(exception) do |report|
+    report.add_metadata(:model_context_protocol, server_context)
+  end
+}
 
-### Progress
+configuration.around_request = ->(data, &request_handler) {
+  logger.info("Start: #{data[:method]}")
+  request_handler.call
+  logger.info("Done: #{data[:method]}, tool: #{data[:tool_name]}")
+}
 
-The MCP Ruby SDK supports progress tracking for long-running tool operations,
-following the [MCP Progress specification](https://modelcontextprotocol.io/specification/latest/server/utilities/progress).
+server = MCP::Server.new(
+  # ... all other options
+  configuration:,
+)
+```
 
-#### How Progress Works
+### Server Context and Configuration Block Data
 
-1. **Client Request**: The client sends a `progressToken` in the `_meta` field when calling a tool
-2. **Server Notification**: The server sends `notifications/progress` messages back to the client during tool execution
-3. **Tool Integration**: Tools call `server_context.report_progress` to report incremental progress
+#### `server_context`
 
-#### Server-Side: Tool with Progress
+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.
 
-Tools that accept a `server_context:` parameter can call `report_progress` on it.
-The server automatically wraps the context in an `MCP::ServerContext` instance that provides this method:
+**Type:**
 
 ```ruby
-class LongRunningTool < MCP::Tool
-  description "A tool that reports progress during execution"
-  input_schema(
-    properties: {
-      count: { type: "integer" },
-    },
-    required: ["count"]
-  )
+server_context: { [String, Symbol] => Any }
+```
 
-  def self.call(count:, server_context:)
-    count.times do |i|
-      # Do work here.
-      server_context.report_progress(i + 1, total: count, message: "Processing item #{i + 1}")
-    end
+**Example:**
 
-    MCP::Tool::Response.new([{ type: "text", text: "Done" }])
-  end
-end
+```ruby
+server = MCP::Server.new(
+  name: "my_server",
+  server_context: { user_id: current_user.id, request_id: request.uuid }
+)
 ```
 
-The `server_context.report_progress` method accepts:
+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.
 
-- `progress` (required) — current progress value (numeric)
-- `total:` (optional) — total expected value, so clients can display a percentage
-- `message:` (optional) — human-readable status message
+#### Request-specific `_meta` Parameter
 
-**Key Features:**
+The MCP protocol supports a special [`_meta` parameter](https://modelcontextprotocol.io/specification/2025-06-18/basic#general-fields) in requests that allows clients to pass request-specific metadata. The server automatically extracts this parameter and makes it available to tools and prompts as a nested field within the `server_context`.
 
-- Tools report progress via `server_context.report_progress`
-- `report_progress` is a no-op when no `progressToken` was provided by the client
-- Supports both numeric and string progress tokens
+**Access Pattern:**
 
-### Logging
+When a client includes `_meta` in the request params, it becomes available as `server_context[:_meta]`:
 
-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).
+```ruby
+class MyTool < MCP::Tool
+  def self.call(message:, server_context:)
+    # Access provider-specific metadata
+    session_id = server_context.dig(:_meta, :session_id)
+    request_id = server_context.dig(:_meta, :request_id)
 
-The `notifications/message` notification is used for structured logging between client and server.
+    # Access server's original context
+    user_id = server_context.dig(:user_id)
 
-#### Log Levels
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: "Processing for user #{user_id} in session #{session_id}"
+    }])
+  end
+end
+```
 
-The SDK supports 8 log levels with increasing severity:
+**Client Request Example:**
 
-- `debug` - Detailed debugging information
-- `info` - General informational messages
-- `notice` - Normal but significant events
-- `warning` - Warning conditions
-- `error` - Error conditions
-- `critical` - Critical conditions
-- `alert` - Action must be taken immediately
-- `emergency` - System is unusable
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "my_tool",
+    "arguments": { "message": "Hello" },
+    "_meta": {
+      "session_id": "abc123",
+      "request_id": "req_456"
+    }
+  }
+}
+```
 
-#### How Logging Works
+#### Configuration Block Data
 
-1. **Client Configuration**: The client sends a `logging/setLevel` request to configure the minimum log level
-2. **Server Filtering**: The server only sends log messages at the configured level or higher severity
-3. **Notification Delivery**: Log messages are sent as `notifications/message` to the client
+##### Exception Reporter
 
-For example, if the client sets the level to `"error"` (severity 4), the server will send messages with levels: `error`, `critical`, `alert`, and `emergency`.
+The exception reporter receives:
 
-For more details, see the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
+- `exception`: The Ruby exception object that was raised
+- `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`.
 
-**Usage Example:**
+**Signature:**
 
 ```ruby
-server = MCP::Server.new(name: "my_server")
-transport = MCP::Server::Transports::StdioTransport.new(server)
-server.transport = transport
+exception_reporter = ->(exception, server_context) { ... }
+```
 
-# The client first configures the logging level (on the client side):
-transport.send_request(
-  request: {
-    jsonrpc: "2.0",
-    method: "logging/setLevel",
-    params: { level: "info" },
-    id: session_id # Unique request ID within the session
+##### Around Request
+
+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
+```
 
-# Send log messages at different severity levels
-server.notify_log_message(
-  data: { message: "Application started successfully" },
-  level: "info"
-)
+##### Instrumentation Callback (soft-deprecated)
 
-server.notify_log_message(
-  data: { message: "Configuration file not found, using defaults" },
-  level: "warning"
-)
+> [!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:
 
-server.notify_log_message(
-  data: {
-    error: "Database connection failed",
-    details: { host: "localhost", port: 5432 }
-  },
-  level: "error",
-  logger: "DatabaseLogger" # Optional logger name
-)
+- `method`: (String) The protocol method called (e.g., "ping", "tools/list")
+- `tool_name`: (String, optional) The name of the tool called
+- `tool_arguments`: (Hash, optional) The arguments passed to the tool
+- `prompt_name`: (String, optional) The name of the prompt called
+- `resource_uri`: (String, optional) The URI of the resource called
+- `error`: (String, optional) Error code if a lookup failed
+- `duration`: (Float) Duration of the call in seconds
+- `client`: (Hash, optional) Client information with `name` and `version` keys, from the initialize request
+
+**Signature:**
+
+```ruby
+instrumentation_callback = ->(data) { ... }
 ```
 
-**Key Features:**
+### Server Protocol Version
 
-- Supports 8 log levels (debug, info, notice, warning, error, critical, alert, emergency) based on https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging#log-levels
-- Server has capability `logging` to send log messages
-- Messages are only sent if a transport is configured
-- Messages are filtered based on the client's configured log level
-- If the log level hasn't been set by the client, no messages will be sent
+The server's protocol version can be overridden using the `protocol_version` keyword argument:
 
-#### Transport Support
+```ruby
+configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
+MCP::Server.new(name: "test_server", configuration: configuration)
+```
 
-- **stdio**: Notifications are sent as JSON-RPC 2.0 messages to stdout
-- **Streamable HTTP**: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE)
+If no protocol version is specified, the latest stable version will be applied by default.
+The latest stable version includes new features from the [draft version](https://modelcontextprotocol.io/specification/draft).
 
-#### Usage Example
+This will make all new server instances use the specified protocol version instead of the default version. The protocol version can be reset to the default by setting it to `nil`:
 
 ```ruby
-server = MCP::Server.new(name: "my_server")
+MCP::Configuration.new(protocol_version: nil)
+```
 
-# Default Streamable HTTP - session oriented
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
 
-server.transport = transport
+Be sure to check the [MCP spec](https://modelcontextprotocol.io/specification/versioning) for the protocol version to understand the supported features for the version being set.
 
-# When tools change, notify clients
-server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
-server.notify_tools_list_changed
+### Exception Reporting
+
+The exception reporter receives two arguments:
+
+- `exception`: The Ruby exception object that was raised
+- `server_context`: A hash containing contextual information about where the error occurred
+
+The server_context hash includes:
+
+- For tool calls: `{ tool_name: "name", arguments: { ... } }`
+- For general request handling: `{ request: { ... } }`
+
+When an exception occurs:
+
+1. The exception is reported via the configured reporter
+2. For tool calls, a generic error response is returned to the client: `{ error: "Internal error occurred", isError: true }`
+3. For other requests, the exception is re-raised after reporting
+
+If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
+
+### Tools
+
+MCP spec includes [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) which provide functionality to LLM apps.
+
+This gem provides a `MCP::Tool` class that can be used to create tools in three ways:
+
+1. As a class definition:
+
+```ruby
+class MyTool < MCP::Tool
+  title "My Tool"
+  description "This tool performs specific functionality..."
+  input_schema(
+    properties: {
+      message: { type: "string" },
+    },
+    required: ["message"]
+  )
+  output_schema(
+    properties: {
+      result: { type: "string" },
+      success: { type: "boolean" },
+      timestamp: { type: "string", format: "date-time" }
+    },
+    required: ["result", "success", "timestamp"]
+  )
+  annotations(
+    read_only_hint: true,
+    destructive_hint: false,
+    idempotent_hint: true,
+    open_world_hint: false,
+    title: "My Tool"
+  )
+
+  def self.call(message:, server_context:)
+    MCP::Tool::Response.new([{ type: "text", text: "OK" }])
+  end
+end
+
+tool = MyTool
 ```
 
-You can use Stateless Streamable HTTP, where notifications are not supported and all calls are request/response interactions.
-This mode allows for easy multi-node deployment.
-Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new` (`stateless` defaults to `false`):
+2. By using the `MCP::Tool.define` method with a block:
 
 ```ruby
-# Stateless Streamable HTTP - session-less
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
+tool = MCP::Tool.define(
+  name: "my_tool",
+  title: "My Tool",
+  description: "This tool performs specific functionality...",
+  annotations: {
+    read_only_hint: true,
+    title: "My Tool"
+  }
+) do |args, server_context:|
+  MCP::Tool::Response.new([{ type: "text", text: "OK" }])
+end
 ```
 
-By default, sessions do not expire. To mitigate session hijacking risks, you can set a `session_idle_timeout` (in seconds).
-When configured, sessions that receive no HTTP requests for this duration are automatically expired and cleaned up:
+3. By using the `MCP::Server#define_tool` method with a block:
 
 ```ruby
-# Session timeout of 30 minutes
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
+server = MCP::Server.new
+server.define_tool(
+  name: "my_tool",
+  description: "This tool performs specific functionality...",
+  annotations: {
+    title: "My Tool",
+    read_only_hint: true
+  }
+) do |args, server_context:|
+  Tool::Response.new([{ type: "text", text: "OK" }])
+end
 ```
 
-### Unsupported Features (to be implemented in future versions)
+The server_context parameter is the server_context passed into the server and can be used to pass per request information,
+e.g. around authentication state.
+
+### Tool Annotations
 
-- Resource subscriptions
-- Completions
-- Elicitation
+Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
 
-### Usage
+- `destructive_hint`: Indicates if the tool performs destructive operations. Defaults to true
+- `idempotent_hint`: Indicates if the tool's operations are idempotent. Defaults to false
+- `open_world_hint`: Indicates if the tool operates in an open world context. Defaults to true
+- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state). Defaults to false
+- `title`: A human-readable title for the tool
+
+Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
-#### Rails Controller
+> [!NOTE]
+> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
+
+### Tool Output Schemas
 
-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.
+Tools can optionally define an `output_schema` to specify the expected structure of their results. This works similarly to how `input_schema` is defined and can be used in three ways:
 
-You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
-status codes (e.g., 202 Accepted for notifications).
+1. **Class definition with output_schema:**
 
 ```ruby
-class McpController < ActionController::Base
-  def create
-    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],
-      server_context: { user_id: current_user.id },
-    )
-    transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
-    server.transport = transport
-    status, headers, body = transport.handle_request(request)
+class WeatherTool < MCP::Tool
+  tool_name "get_weather"
+  description "Get current weather for a location"
 
-    render(json: body.first, status: status, headers: headers)
+  input_schema(
+    properties: {
+      location: { type: "string" },
+      units: { type: "string", enum: ["celsius", "fahrenheit"] }
+    },
+    required: ["location"]
+  )
+
+  output_schema(
+    properties: {
+      temperature: { type: "number" },
+      condition: { type: "string" },
+      humidity: { type: "integer" }
+    },
+    required: ["temperature", "condition", "humidity"]
+  )
+
+  def self.call(location:, units: "celsius", server_context:)
+    # Call weather API and structure the response
+    api_response = WeatherAPI.fetch(location, units)
+    weather_data = {
+      temperature: api_response.temp,
+      condition: api_response.description,
+      humidity: api_response.humidity_percent
+    }
+
+    output_schema.validate_result(weather_data)
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: weather_data.to_json
+    }])
   end
 end
 ```
 
-#### Stdio Transport
+2. **Using Tool.define with output_schema:**
+
+```ruby
+tool = MCP::Tool.define(
+  name: "calculate_stats",
+  description: "Calculate statistics for a dataset",
+  input_schema: {
+    properties: {
+      numbers: { type: "array", items: { type: "number" } }
+    },
+    required: ["numbers"]
+  },
+  output_schema: {
+    properties: {
+      mean: { type: "number" },
+      median: { type: "number" },
+      count: { type: "integer" }
+    },
+    required: ["mean", "median", "count"]
+  }
+) do |args, server_context:|
+  # Calculate statistics and validate against schema
+  MCP::Tool::Response.new([{ type: "text", text: "Statistics calculated" }])
+end
+```
+
+3. **Using OutputSchema objects:**
+
+```ruby
+class DataTool < MCP::Tool
+  output_schema MCP::Tool::OutputSchema.new(
+    properties: {
+      success: { type: "boolean" },
+      data: { type: "object" }
+    },
+    required: ["success"]
+  )
+end
+```
+
+Output schema may also describe an array of objects:
+
+```ruby
+class WeatherTool < MCP::Tool
+  output_schema(
+    type: "array",
+    items: {
+      properties: {
+        temperature: { type: "number" },
+        condition: { type: "string" },
+        humidity: { type: "integer" }
+      },
+      required: ["temperature", "condition", "humidity"]
+    }
+  )
+end
+```
+
+Please note: in this case, you must provide `type: "array"`. The default type
+for output schemas is `object`.
+
+MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/latest/server/tools#output-schema) specifies that:
+
+- **Server Validation**: Servers MUST provide structured results that conform to the output schema
+- **Client Validation**: Clients SHOULD validate structured results against the output schema
+- **Better Integration**: Enables strict schema validation, type information, and improved developer experience
+- **Backward Compatibility**: Tools returning structured content SHOULD also include serialized JSON in a TextContent block
+
+The output schema follows standard JSON Schema format and helps ensure consistent data exchange between MCP servers and clients.
+
+### Tool Responses with Structured Content
+
+Tools can return structured data alongside text content using the `structured_content` parameter.
+
+The structured content will be included in the JSON-RPC response as the `structuredContent` field.
+
+```ruby
+class WeatherTool < MCP::Tool
+  description "Get current weather and return structured data"
+
+  def self.call(location:, units: "celsius", server_context:)
+    # Call weather API and structure the response
+    api_response = WeatherAPI.fetch(location, units)
+    weather_data = {
+      temperature: api_response.temp,
+      condition: api_response.description,
+      humidity: api_response.humidity_percent
+    }
+
+    output_schema.validate_result(weather_data)
+
+    MCP::Tool::Response.new(
+      [{
+        type: "text",
+        text: weather_data.to_json
+      }],
+      structured_content: weather_data
+    )
+  end
+end
+```
+
+### Tool Responses with Errors
+
+Tools can return error information alongside text content using the `error` parameter.
+
+The error will be included in the JSON-RPC response as the `isError` field.
+
+```ruby
+class WeatherTool < MCP::Tool
+  description "Get current weather and return structured data"
+
+  def self.call(server_context:)
+    # Do something here
+    content = {}
+
+    MCP::Tool::Response.new(
+      [{
+        type: "text",
+        text: content.to_json
+      }],
+      structured_content: content,
+      error: true
+    )
+  end
+end
+```
+
+### Prompts
+
+MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/latest/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.
+
+The `MCP::Prompt` class provides three ways to create prompts:
+
+1. As a class definition with metadata:
+
+```ruby
+class MyPrompt < MCP::Prompt
+  prompt_name "my_prompt"  # Optional - defaults to underscored class name
+  title "My Prompt"
+  description "This prompt performs specific functionality..."
+  arguments [
+    MCP::Prompt::Argument.new(
+      name: "message",
+      title: "Message Title",
+      description: "Input message",
+      required: true
+    )
+  ]
+  meta({ version: "1.0", category: "example" })
+
+  class << self
+    def template(args, server_context:)
+      MCP::Prompt::Result.new(
+        description: "Response description",
+        messages: [
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Text.new("User message")
+          ),
+          MCP::Prompt::Message.new(
+            role: "assistant",
+            content: MCP::Content::Text.new(args["message"])
+          )
+        ]
+      )
+    end
+  end
+end
+
+prompt = MyPrompt
+```
+
+2. Using the `MCP::Prompt.define` method:
+
+```ruby
+prompt = MCP::Prompt.define(
+  name: "my_prompt",
+  title: "My Prompt",
+  description: "This prompt performs specific functionality...",
+  arguments: [
+    MCP::Prompt::Argument.new(
+      name: "message",
+      title: "Message Title",
+      description: "Input message",
+      required: true
+    )
+  ],
+  meta: { version: "1.0", category: "example" }
+) do |args, server_context:|
+  MCP::Prompt::Result.new(
+    description: "Response description",
+    messages: [
+      MCP::Prompt::Message.new(
+        role: "user",
+        content: MCP::Content::Text.new("User message")
+      ),
+      MCP::Prompt::Message.new(
+        role: "assistant",
+        content: MCP::Content::Text.new(args["message"])
+      )
+    ]
+  )
+end
+```
+
+3. Using the `MCP::Server#define_prompt` method:
+
+```ruby
+server = MCP::Server.new
+server.define_prompt(
+  name: "my_prompt",
+  description: "This prompt performs specific functionality...",
+  arguments: [
+    Prompt::Argument.new(
+      name: "message",
+      title: "Message Title",
+      description: "Input message",
+      required: true
+    )
+  ],
+  meta: { version: "1.0", category: "example" }
+) do |args, server_context:|
+  Prompt::Result.new(
+    description: "Response description",
+    messages: [
+      Prompt::Message.new(
+        role: "user",
+        content: Content::Text.new("User message")
+      ),
+      Prompt::Message.new(
+        role: "assistant",
+        content: Content::Text.new(args["message"])
+      )
+    ]
+  )
+end
+```
+
+The server_context parameter is the server_context passed into the server and can be used to pass per request information,
+e.g. around authentication state or user preferences.
+
+### Key Components
+
+- `MCP::Prompt::Argument` - Defines input parameters for the prompt template with name, title, description, and required flag
+- `MCP::Prompt::Message` - Represents a message in the conversation with a role and content
+- `MCP::Prompt::Result` - The output of a prompt template containing description and messages
+- `MCP::Content::Text` - Text content for messages
+
+### Usage
+
+Register prompts with the MCP server:
+
+```ruby
+server = MCP::Server.new(
+  name: "my_server",
+  prompts: [MyPrompt],
+  server_context: { user_id: current_user.id },
+)
+```
+
+The server will handle prompt listing and execution through the MCP protocol methods:
+
+- `prompts/list` - Lists all registered prompts and their schemas
+- `prompts/get` - Retrieves and executes a specific prompt with arguments
+
+### Resources
+
+MCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).
+
+### Reading Resources
+
+The `MCP::Resource` class provides a way to register resources with the server.
+
+```ruby
+resource = MCP::Resource.new(
+  uri: "https://example.com/my_resource",
+  name: "my-resource",
+  title: "My Resource",
+  description: "Lorem ipsum dolor sit amet",
+  mime_type: "text/html",
+)
+
+server = MCP::Server.new(
+  name: "my_server",
+  resources: [resource],
+)
+```
+
+The server must register a handler for the `resources/read` method to retrieve a resource dynamically.
+
+```ruby
+server.resources_read_handler do |params|
+  [{
+    uri: params[:uri],
+    mimeType: "text/plain",
+    text: "Hello from example resource! URI: #{params[:uri]}"
+  }]
+end
+```
+
+otherwise `resources/read` requests will be a no-op.
+
+### Resource Templates
+
+The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
+
+```ruby
+resource_template = MCP::ResourceTemplate.new(
+  uri_template: "https://example.com/my_resource_template",
+  name: "my-resource-template",
+  title: "My Resource Template",
+  description: "Lorem ipsum dolor sit amet",
+  mime_type: "text/html",
+)
+
+server = MCP::Server.new(
+  name: "my_server",
+  resource_templates: [resource_template],
+)
+```
+
+### Roots
+
+The Model Context Protocol allows servers to request filesystem roots from clients through the `roots/list` method.
+Roots define the boundaries of where a server can operate, providing a list of directories and files the client has made available.
+
+**Key Concepts:**
 
-If you want to build a local command-line application, you can use the stdio transport:
+- **Server-to-Client Request**: Like sampling, roots listing is initiated by the server
+- **Client Capability**: Clients must declare `roots` capability during initialization
+- **Change Notifications**: Clients that support `roots.listChanged` send `notifications/roots/list_changed` when roots change
 
-```ruby
-require "mcp"
+**Using Roots in Tools:**
 
-# Create a simple tool
-class ExampleTool < MCP::Tool
-  description "A simple example tool that echoes back its arguments"
+Tools that accept a `server_context:` parameter can call `list_roots` on it.
+The request is automatically routed to the correct client session:
+
+```ruby
+class FileSearchTool < MCP::Tool
+  description "Search files within the client's project roots"
   input_schema(
     properties: {
-      message: { type: "string" },
+      query: { type: "string" }
     },
-    required: ["message"]
+    required: ["query"]
   )
 
-  class << self
-    def call(message:, server_context:)
-      MCP::Tool::Response.new([{
-        type: "text",
-        text: "Hello from example tool! Message: #{message}",
-      }])
-    end
+  def self.call(query:, server_context:)
+    roots = server_context.list_roots
+    root_uris = roots[:roots].map { |root| root[:uri] }
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: "Searching in roots: #{root_uris.join(", ")}"
+    }])
   end
 end
-
-# Set up the server
-server = MCP::Server.new(
-  name: "example_server",
-  tools: [ExampleTool],
-)
-
-# Create and start the transport
-transport = MCP::Server::Transports::StdioTransport.new(server)
-transport.open
 ```
 
-You can run this script and then type in requests to the server at the command line.
+Result contains an array of root objects:
 
-```console
-$ ruby examples/stdio_server.rb
-{"jsonrpc":"2.0","id":"1","method":"ping"}
-{"jsonrpc":"2.0","id":"2","method":"tools/list"}
-{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}
+```ruby
+{
+  roots: [
+    { uri: "file:///home/user/projects/myproject", name: "My Project" },
+    { uri: "file:///home/user/repos/backend", name: "Backend Repository" }
+  ]
+}
 ```
 
-### Configuration
+**Handling Root Changes:**
 
-The gem can be configured using the `MCP.configure` block:
+Register a callback to be notified when the client's roots change:
 
 ```ruby
-MCP.configure do |config|
-  config.exception_reporter = ->(exception, server_context) {
-    # Your exception reporting logic here
-    # For example with Bugsnag:
-    Bugsnag.notify(exception) do |report|
-      report.add_metadata(:model_context_protocol, server_context)
-    end
-  }
-
-  config.instrumentation_callback = ->(data) {
-    puts "Got instrumentation data #{data.inspect}"
-  }
+server.roots_list_changed_handler do
+  puts "Client's roots have changed, tools will see updated roots on next call."
 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.
-
-```ruby
-configuration = MCP::Configuration.new
-configuration.exception_reporter = ->(exception, server_context) {
-  # Your exception reporting logic here
-  # For example with Bugsnag:
-  Bugsnag.notify(exception) do |report|
-    report.add_metadata(:model_context_protocol, server_context)
-  end
-}
-
-configuration.instrumentation_callback = ->(data) {
-  puts "Got instrumentation data #{data.inspect}"
-}
+**Error Handling:**
 
-server = MCP::Server.new(
-  # ... all other options
-  configuration:,
-)
-```
+- Raises `RuntimeError` if client does not support `roots` capability
+- Raises `StandardError` if client returns an error response
 
-### Server Context and Configuration Block Data
+### Resource Subscriptions
 
-#### `server_context`
+Resource subscriptions allow clients to monitor specific resources for changes.
+When a subscribed resource is updated, the server sends a notification to the client.
 
-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 SDK does not track subscription state internally.
+Server developers register handlers and manage their own subscription state.
+Three methods are provided:
 
-**Type:**
+- `Server#resources_subscribe_handler` - registers a handler for `resources/subscribe` requests
+- `Server#resources_unsubscribe_handler` - registers a handler for `resources/unsubscribe` requests
+- `ServerContext#notify_resources_updated` - sends a `notifications/resources/updated` notification to the subscribing client
 
 ```ruby
-server_context: { [String, Symbol] => Any }
-```
-
-**Example:**
+subscribed_uris = Set.new
 
-```ruby
 server = MCP::Server.new(
   name: "my_server",
-  server_context: { user_id: current_user.id, request_id: request.uuid }
+  resources: [my_resource],
+  capabilities: { resources: { subscribe: true } },
 )
+
+server.resources_subscribe_handler do |params|
+  subscribed_uris.add(params[:uri].to_s)
+end
+
+server.resources_unsubscribe_handler do |params|
+  subscribed_uris.delete(params[:uri].to_s)
+end
+
+server.define_tool(name: "update_resource") do |server_context:, **args|
+  if subscribed_uris.include?("test://my-resource")
+    server_context.notify_resources_updated(uri: "test://my-resource")
+  end
+  MCP::Tool::Response.new([MCP::Content::Text.new("Resource updated").to_h])
+end
 ```
 
-This hash is then passed as the `server_context` argument to tool and prompt calls, and is included in exception and instrumentation callbacks.
+### Sampling
 
-#### Request-specific `_meta` Parameter
+The Model Context Protocol allows servers to request LLM completions from clients through the `sampling/createMessage` method.
+This enables servers to leverage the client's LLM capabilities without needing direct access to AI models.
 
-The MCP protocol supports a special [`_meta` parameter](https://modelcontextprotocol.io/specification/2025-06-18/basic#general-fields) in requests that allows clients to pass request-specific metadata. The server automatically extracts this parameter and makes it available to tools and prompts as a nested field within the `server_context`.
+**Key Concepts:**
 
-**Access Pattern:**
+- **Server-to-Client Request**: Unlike typical MCP methods (client to server), sampling is initiated by the server
+- **Client Capability**: Clients must declare `sampling` capability during initialization
+- **Tool Support**: When using tools in sampling requests, clients must declare `sampling.tools` capability
+- **Human-in-the-Loop**: Clients can implement user approval before forwarding requests to LLMs
 
-When a client includes `_meta` in the request params, it becomes available as `server_context[:_meta]`:
+**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:
 
 ```ruby
-class MyTool < MCP::Tool
-  def self.call(message:, server_context:)
-    # Access provider-specific metadata
-    session_id = server_context.dig(:_meta, :session_id)
-    request_id = server_context.dig(:_meta, :request_id)
+class SummarizeTool < MCP::Tool
+  description "Summarize text using LLM"
+  input_schema(
+    properties: {
+      text: { type: "string" }
+    },
+    required: ["text"]
+  )
 
-    # Access server's original context
-    user_id = server_context.dig(:user_id)
+  def self.call(text:, server_context:)
+    result = server_context.create_sampling_message(
+      messages: [
+        { role: "user", content: { type: "text", text: "Please summarize: #{text}" } }
+      ],
+      max_tokens: 500
+    )
 
     MCP::Tool::Response.new([{
       type: "text",
-      text: "Processing for user #{user_id} in session #{session_id}"
+      text: result[:content][:text]
     }])
   end
 end
+
+server = MCP::Server.new(name: "my_server", tools: [SummarizeTool])
 ```
 
-**Client Request Example:**
+**Parameters:**
 
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "method": "tools/call",
-  "params": {
-    "name": "my_tool",
-    "arguments": { "message": "Hello" },
-    "_meta": {
-      "session_id": "abc123",
-      "request_id": "req_456"
-    }
-  }
-}
-```
+Required:
 
-#### Configuration Block Data
+- `messages:` (Array) - Array of message objects with `role` and `content`
+- `max_tokens:` (Integer) - Maximum tokens in the response
 
-##### Exception Reporter
+Optional:
 
-The exception reporter receives:
+- `system_prompt:` (String) - System prompt for the LLM
+- `model_preferences:` (Hash) - Model selection preferences (e.g., `{ intelligencePriority: 0.8 }`)
+- `include_context:` (String) - Context inclusion: `"none"`, `"thisServer"`, or `"allServers"` (soft-deprecated)
+- `temperature:` (Float) - Sampling temperature
+- `stop_sequences:` (Array) - Sequences that stop generation
+- `metadata:` (Hash) - Additional metadata
+- `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
+- `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
 
-- `exception`: The Ruby exception object that was raised
-- `server_context`: The context hash provided to the server
+**Error Handling:**
 
-**Signature:**
+- 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
 
-```ruby
-exception_reporter = ->(exception, server_context) { ... }
-```
+### Notifications
 
-##### Instrumentation Callback
+The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
 
-The instrumentation callback receives a hash with the following possible keys:
+#### Notification Methods
 
-- `method`: (String) The protocol method called (e.g., "ping", "tools/list")
-- `tool_name`: (String, optional) The name of the tool called
-- `tool_arguments`: (Hash, optional) The arguments passed to the tool
-- `prompt_name`: (String, optional) The name of the prompt called
-- `resource_uri`: (String, optional) The URI of the resource called
-- `error`: (String, optional) Error code if a lookup failed
-- `duration`: (Float) Duration of the call in seconds
-- `client`: (Hash, optional) Client information with `name` and `version` keys, from the initialize request
+The server provides the following notification methods:
+
+- `notify_tools_list_changed` - Send a notification when the tools list changes
+- `notify_prompts_list_changed` - Send a notification when the prompts list changes
+- `notify_resources_list_changed` - Send a notification when the resources list changes
+- `notify_log_message` - Send a structured logging notification message
+
+#### Session Scoping
+
+When using Streamable HTTP transport with multiple clients, each client connection gets its own session. Notifications are scoped as follows:
+
+- **`report_progress`** and **`notify_log_message`** called via `server_context` inside a tool handler are automatically sent only to the requesting client.
+No extra configuration is needed.
+- **`notify_tools_list_changed`**, **`notify_prompts_list_changed`**, and **`notify_resources_list_changed`** are always broadcast to all connected clients,
+as they represent server-wide state changes. These should be called on the `server` instance directly.
+
+#### Notification Format
+
+Notifications follow the JSON-RPC 2.0 specification and use these method names:
+
+- `notifications/tools/list_changed`
+- `notifications/prompts/list_changed`
+- `notifications/resources/list_changed`
+- `notifications/cancelled`
+- `notifications/progress`
+- `notifications/message`
+
+### Cancellation
+
+The MCP Ruby SDK supports server-side handling of the
+[MCP `notifications/cancelled` utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+When a client sends `notifications/cancelled` for an in-flight request, the server stops
+processing cooperatively and suppresses the JSON-RPC response for that request.
+
+Cancellation is cooperative: the SDK does not forcibly terminate tool code. Instead,
+a `MCP::Cancellation` token is threaded through `server_context`, and long-running tools
+poll it to exit early. When a tool returns after cancellation has been observed,
+the server suppresses the JSON-RPC response, matching the spec. The `initialize` request
+is never cancellable per the spec.
 
 > [!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.
+> Client-initiated cancellation (`Client#cancel` equivalent that would also abort
+> the calling thread's wait) is not yet implemented. Sending `notifications/cancelled`
+> from the client side can be done by constructing the notification payload and writing it
+> directly through the transport, but the calling thread does not yet unwind automatically.
+> This is tracked as a follow-up.
 
-**Type:**
+#### Server-Side: Handlers that Check for Cancellation
+
+Any handler that opts in to `server_context:` - tools (`Tool.call`), prompt templates,
+`resources_read_handler`, `completion_handler`, `resources_subscribe_handler`,
+`resources_unsubscribe_handler`, and `define_custom_method` blocks - receives
+an `MCP::ServerContext` wired to the in-flight request's cancellation token.
+Handlers check `cancelled?` in their work loop, or call `raise_if_cancelled!` to raise
+`MCP::CancelledError` at a safe point:
 
 ```ruby
-instrumentation_callback = ->(data) { ... }
-# where data is a Hash with keys as described above
+class LongRunningTool < MCP::Tool
+  description "A tool that supports cancellation"
+  input_schema(properties: { count: { type: "integer" } }, required: ["count"])
+
+  def self.call(count:, server_context:)
+    count.times do |i|
+      # Exit early if the client has sent `notifications/cancelled`.
+      break if server_context.cancelled?
+
+      do_work(i)
+    end
+
+    MCP::Tool::Response.new([{ type: "text", text: "Done" }])
+  end
+end
 ```
 
-**Example:**
+Alternatively, raise at the next safe point with `raise_if_cancelled!`:
 
 ```ruby
-MCP.configure do |config|
-  config.instrumentation_callback = ->(data) {
-    puts "Instrumentation: #{data.inspect}"
-  }
+def self.call(count:, server_context:)
+  count.times do |i|
+    server_context.raise_if_cancelled!
+
+    do_work(i)
+  end
+
+  MCP::Tool::Response.new([{ type: "text", text: "Done" }])
 end
 ```
 
-### Server Protocol Version
+When a handler observes cancellation (either by returning early with `cancelled?` or
+by raising `MCP::CancelledError` via `raise_if_cancelled!`), the server drops the response and
+no JSON-RPC result is sent to the client.
 
-The server's protocol version can be overridden using the `protocol_version` keyword argument:
+The same pattern works for other handler types:
 
 ```ruby
-configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
-MCP::Server.new(name: "test_server", configuration: configuration)
+# resources/read
+server.resources_read_handler do |params, server_context:|
+  server_context.raise_if_cancelled!
+  # read the resource
+end
+
+# completion/complete
+server.completion_handler do |params, server_context:|
+  server_context.raise_if_cancelled!
+  # compute completions
+end
+
+# custom method
+server.define_custom_method(method_name: "custom/slow") do |params, server_context:|
+  server_context.raise_if_cancelled!
+  # do work
+end
+
+# prompts (via Prompt subclass)
+class SlowPrompt < MCP::Prompt
+  prompt_name "slow_prompt"
+
+  def self.template(args, server_context:)
+    server_context.raise_if_cancelled!
+    MCP::Prompt::Result.new(messages: [])
+  end
+end
 ```
 
-If no protocol version is specified, the latest stable version will be applied by default.
-The latest stable version includes new features from the [draft version](https://modelcontextprotocol.io/specification/draft).
+Handlers that do not declare a `server_context:` keyword continue to work unchanged -
+the opt-in detection only wraps the context when the block signature asks for it.
 
-This will make all new server instances use the specified protocol version instead of the default version. The protocol version can be reset to the default by setting it to `nil`:
+#### Nested Server-to-Client Requests Are Cancelled Automatically
+
+When a tool handler is waiting on a nested server-to-client request
+(`server_context.create_sampling_message`, `create_form_elicitation`, or
+`create_url_elicitation`), cancelling the parent tool call automatically raises
+`MCP::CancelledError` from the nested call, so the tool does not need to wrap it
+in its own `cancelled?` checks:
 
 ```ruby
-MCP::Configuration.new(protocol_version: nil)
+def self.call(server_context:)
+  result = server_context.create_sampling_message(messages: messages, max_tokens: 100)
+  # If the parent tools/call is cancelled while waiting above, MCP::CancelledError
+  # is raised here and the tool can let it propagate or clean up as needed.
+  MCP::Tool::Response.new([{ type: "text", text: result[:content][:text] }])
+rescue MCP::CancelledError
+  # Optional: run cleanup. Re-raising (or letting it propagate) is fine; the server
+  # will still suppress the JSON-RPC response per the MCP spec.
+  raise
+end
 ```
 
-If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
+Nested cancellation propagation is supported on `StreamableHTTPTransport` only.
+`StdioTransport` is single-threaded and blocks on `$stdin.gets`, so a nested
+`server_context.create_sampling_message` inside a tool runs to completion even if
+the parent `tools/call` is cancelled. The parent tool itself still observes cancellation
+via `server_context.cancelled?` between nested calls.
 
-Be sure to check the [MCP spec](https://modelcontextprotocol.io/specification/versioning) for the protocol version to understand the supported features for the version being set.
+### Ping
 
-### Exception Reporting
+The MCP Ruby SDK supports the
+[MCP `ping` utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping),
+which allows either side of the connection to verify that the peer is still responsive.
+A `ping` request has no parameters, and the receiver MUST respond promptly with an empty result.
 
-The exception reporter receives two arguments:
+#### Server-Side
 
-- `exception`: The Ruby exception object that was raised
-- `server_context`: A hash containing contextual information about where the error occurred
+Servers respond to incoming `ping` requests automatically - no setup is required.
+Any `MCP::Server` instance replies with an empty result.
 
-The server_context hash includes:
+#### Client-Side
 
-- For tool calls: `{ tool_name: "name", arguments: { ... } }`
-- For general request handling: `{ request: { ... } }`
+`MCP::Client` exposes `ping` to send a ping to the server:
 
-When an exception occurs:
+```ruby
+client = MCP::Client.new(transport: transport)
+client.ping # => {} on success
+```
 
-1. The exception is reported via the configured reporter
-2. For tool calls, a generic error response is returned to the client: `{ error: "Internal error occurred", isError: true }`
-3. For other requests, the exception is re-raised after reporting
+`#ping` raises `MCP::Client::ServerError` when the server returns a JSON-RPC error.
+It raises `MCP::Client::ValidationError` when the response `result` is missing or
+is not a Hash (matching the spec requirement that `result` be an object).
+Transport-level errors (for example, `MCP::Client::Stdio`'s `read_timeout:` firing)
+propagate as exceptions raised by the transport layer.
 
-If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
+### Progress
 
-### Tools
+The MCP Ruby SDK supports progress tracking for long-running tool operations,
+following the [MCP Progress specification](https://modelcontextprotocol.io/specification/latest/server/utilities/progress).
 
-MCP spec includes [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) which provide functionality to LLM apps.
+#### How Progress Works
 
-This gem provides a `MCP::Tool` class that can be used to create tools in three ways:
+1. **Client Request**: The client sends a `progressToken` in the `_meta` field when calling a tool
+2. **Server Notification**: The server sends `notifications/progress` messages back to the client during tool execution
+3. **Tool Integration**: Tools call `server_context.report_progress` to report incremental progress
 
-1. As a class definition:
+#### Server-Side: Tool with Progress
+
+Tools that accept a `server_context:` parameter can call `report_progress` on it.
+The server automatically wraps the context in an `MCP::ServerContext` instance that provides this method:
 
 ```ruby
-class MyTool < MCP::Tool
-  title "My Tool"
-  description "This tool performs specific functionality..."
+class LongRunningTool < MCP::Tool
+  description "A tool that reports progress during execution"
   input_schema(
     properties: {
-      message: { type: "string" },
-    },
-    required: ["message"]
-  )
-  output_schema(
-    properties: {
-      result: { type: "string" },
-      success: { type: "boolean" },
-      timestamp: { type: "string", format: "date-time" }
+      count: { type: "integer" },
     },
-    required: ["result", "success", "timestamp"]
-  )
-  annotations(
-    read_only_hint: true,
-    destructive_hint: false,
-    idempotent_hint: true,
-    open_world_hint: false,
-    title: "My Tool"
+    required: ["count"]
   )
 
-  def self.call(message:, server_context:)
-    MCP::Tool::Response.new([{ type: "text", text: "OK" }])
+  def self.call(count:, server_context:)
+    count.times do |i|
+      # Do work here.
+      server_context.report_progress(i + 1, total: count, message: "Processing item #{i + 1}")
+    end
+
+    MCP::Tool::Response.new([{ type: "text", text: "Done" }])
   end
 end
-
-tool = MyTool
 ```
 
-2. By using the `MCP::Tool.define` method with a block:
+The `server_context.report_progress` method accepts:
 
-```ruby
-tool = MCP::Tool.define(
-  name: "my_tool",
-  title: "My Tool",
-  description: "This tool performs specific functionality...",
-  annotations: {
-    read_only_hint: true,
-    title: "My Tool"
-  }
-) do |args, server_context:|
-  MCP::Tool::Response.new([{ type: "text", text: "OK" }])
-end
-```
+- `progress` (required) — current progress value (numeric)
+- `total:` (optional) — total expected value, so clients can display a percentage
+- `message:` (optional) — human-readable status message
 
-3. By using the `MCP::Server#define_tool` method with a block:
+**Key Features:**
+
+- Tools report progress via `server_context.report_progress`
+- `report_progress` is a no-op when no `progressToken` was provided by the client
+- Supports both numeric and string progress tokens
+
+### Completions
+
+MCP spec includes [Completions](https://modelcontextprotocol.io/specification/latest/server/utilities/completion),
+which enable servers to provide autocompletion suggestions for prompt arguments and resource URIs.
+
+To enable completions, declare the `completions` capability and register a handler:
 
 ```ruby
-server = MCP::Server.new
-server.define_tool(
-  name: "my_tool",
-  description: "This tool performs specific functionality...",
-  annotations: {
-    title: "My Tool",
-    read_only_hint: true
-  }
-) do |args, server_context:|
-  Tool::Response.new([{ type: "text", text: "OK" }])
+server = MCP::Server.new(
+  name: "my_server",
+  prompts: [CodeReviewPrompt],
+  resource_templates: [FileTemplate],
+  capabilities: { completions: {} },
+)
+
+server.completion_handler do |params|
+  ref = params[:ref]
+  argument = params[:argument]
+  value = argument[:value]
+
+  case ref[:type]
+  when "ref/prompt"
+    values = case argument[:name]
+    when "language"
+      ["python", "pytorch", "pyside"].select { |v| v.start_with?(value) }
+    else
+      []
+    end
+    { completion: { values: values, hasMore: false } }
+  when "ref/resource"
+    { completion: { values: [], hasMore: false } }
+  end
 end
 ```
 
-The server_context parameter is the server_context passed into the server and can be used to pass per request information,
-e.g. around authentication state.
+The handler receives a `params` hash with:
 
-### Tool Annotations
+- `ref` - The reference (`{ type: "ref/prompt", name: "..." }` or `{ type: "ref/resource", uri: "..." }`)
+- `argument` - The argument being completed (`{ name: "...", value: "..." }`)
+- `context` (optional) - Previously resolved arguments (`{ arguments: { ... } }`)
 
-Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
+The handler must return a hash with a `completion` key containing `values` (array of strings), and optionally `total` and `hasMore`.
+The SDK automatically enforces the 100-item limit per the MCP specification.
 
-- `destructive_hint`: Indicates if the tool performs destructive operations. Defaults to true
-- `idempotent_hint`: Indicates if the tool's operations are idempotent. Defaults to false
-- `open_world_hint`: Indicates if the tool operates in an open world context. Defaults to true
-- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state). Defaults to false
-- `title`: A human-readable title for the tool
+The server validates that the referenced prompt, resource, or resource template is registered before calling the handler.
+Requests for unknown references return an error.
 
-Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
+### Elicitation
 
-> [!NOTE]
-> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
+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.
 
-### Tool Output Schemas
+Elicitation is a **server-to-client request**. The server sends a request and blocks until the user responds via the client.
 
-Tools can optionally define an `output_schema` to specify the expected structure of their results. This works similarly to how `input_schema` is defined and can be used in three ways:
+#### Capabilities
 
-1. **Class definition with output_schema:**
+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.
 
-```ruby
-class WeatherTool < MCP::Tool
-  tool_name "get_weather"
-  description "Get current weather for a location"
+For URL mode support, the client must also declare `elicitation.url` capability.
 
-  input_schema(
-    properties: {
-      location: { type: "string" },
-      units: { type: "string", enum: ["celsius", "fahrenheit"] }
-    },
-    required: ["location"]
-  )
+#### Using Elicitation in Tools
 
-  output_schema(
-    properties: {
-      temperature: { type: "number" },
-      condition: { type: "string" },
-      humidity: { type: "integer" }
+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"],
     },
-    required: ["temperature", "condition", "humidity"]
   )
 
-  def self.call(location:, units: "celsius", server_context:)
-    # Call weather API and structure the response
-    api_response = WeatherAPI.fetch(location, units)
-    weather_data = {
-      temperature: api_response.temp,
-      condition: api_response.description,
-      humidity: api_response.humidity_percent
-    }
-
-    output_schema.validate_result(weather_data)
-
-    MCP::Tool::Response.new([{
-      type: "text",
-      text: weather_data.to_json
-    }])
-  end
+  MCP::Tool::Response.new([{ type: "text", text: "Hello, #{result[:content][:name]}" }])
 end
 ```
 
-2. **Using Tool.define with output_schema:**
+#### Form Mode
+
+Form mode collects structured data from the user directly through the MCP client:
 
 ```ruby
-tool = MCP::Tool.define(
-  name: "calculate_stats",
-  description: "Calculate statistics for a dataset",
-  input_schema: {
-    properties: {
-      numbers: { type: "array", items: { type: "number" } }
-    },
-    required: ["numbers"]
-  },
-  output_schema: {
-    properties: {
-      mean: { type: "number" },
-      median: { type: "number" },
-      count: { type: "integer" }
+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"],
     },
-    required: ["mean", "median", "count"]
-  }
-) do |args, server_context:|
-  # Calculate statistics and validate against schema
-  MCP::Tool::Response.new([{ type: "text", text: "Statistics calculated" }])
+  )
+
+  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
 ```
 
-3. **Using OutputSchema objects:**
+#### URL Mode
+
+URL mode directs the user to an external URL for out-of-band interactions such as OAuth flows:
 
 ```ruby
-class DataTool < MCP::Tool
-  output_schema MCP::Tool::OutputSchema.new(
-    properties: {
-      success: { type: "boolean" },
-      data: { type: "object" }
-    },
-    required: ["success"]
+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
 ```
 
-Output schema may also describe an array of objects:
+#### 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
-class WeatherTool < MCP::Tool
-  output_schema(
-    type: "array",
-    items: {
-      properties: {
-        temperature: { type: "number" },
-        condition: { type: "string" },
-        humidity: { type: "integer" }
-      },
-      required: ["temperature", "condition", "humidity"]
-    }
-  )
+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
 ```
 
-Please note: in this case, you must provide `type: "array"`. The default type
-for output schemas is `object`.
+### Logging
 
-MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/latest/server/tools#output-schema) specifies that:
+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).
 
-- **Server Validation**: Servers MUST provide structured results that conform to the output schema
-- **Client Validation**: Clients SHOULD validate structured results against the output schema
-- **Better Integration**: Enables strict schema validation, type information, and improved developer experience
-- **Backward Compatibility**: Tools returning structured content SHOULD also include serialized JSON in a TextContent block
+The `notifications/message` notification is used for structured logging between client and server.
 
-The output schema follows standard JSON Schema format and helps ensure consistent data exchange between MCP servers and clients.
+#### Log Levels
 
-### Tool Responses with Structured Content
+The SDK supports 8 log levels with increasing severity:
 
-Tools can return structured data alongside text content using the `structured_content` parameter.
+- `debug` - Detailed debugging information
+- `info` - General informational messages
+- `notice` - Normal but significant events
+- `warning` - Warning conditions
+- `error` - Error conditions
+- `critical` - Critical conditions
+- `alert` - Action must be taken immediately
+- `emergency` - System is unusable
 
-The structured content will be included in the JSON-RPC response as the `structuredContent` field.
+#### How Logging Works
+
+1. **Client Configuration**: The client sends a `logging/setLevel` request to configure the minimum log level
+2. **Server Filtering**: The server only sends log messages at the configured level or higher severity
+3. **Notification Delivery**: Log messages are sent as `notifications/message` to the client
+
+For example, if the client sets the level to `"error"` (severity 4), the server will send messages with levels: `error`, `critical`, `alert`, and `emergency`.
+
+For more details, see the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
+
+**Usage Example:**
 
 ```ruby
-class WeatherTool < MCP::Tool
-  description "Get current weather and return structured data"
+server = MCP::Server.new(name: "my_server")
+transport = MCP::Server::Transports::StdioTransport.new(server)
 
-  def self.call(location:, units: "celsius", server_context:)
-    # Call weather API and structure the response
-    api_response = WeatherAPI.fetch(location, units)
-    weather_data = {
-      temperature: api_response.temp,
-      condition: api_response.description,
-      humidity: api_response.humidity_percent
-    }
+# The client first configures the logging level (on the client side):
+transport.send_request(
+  request: {
+    jsonrpc: "2.0",
+    method: "logging/setLevel",
+    params: { level: "info" },
+    id: session_id # Unique request ID within the session
+  }
+)
 
-    output_schema.validate_result(weather_data)
+# Send log messages at different severity levels
+server.notify_log_message(
+  data: { message: "Application started successfully" },
+  level: "info"
+)
 
-    MCP::Tool::Response.new(
-      [{
-        type: "text",
-        text: weather_data.to_json
-      }],
-      structured_content: weather_data
-    )
-  end
-end
+server.notify_log_message(
+  data: { message: "Configuration file not found, using defaults" },
+  level: "warning"
+)
+
+server.notify_log_message(
+  data: {
+    error: "Database connection failed",
+    details: { host: "localhost", port: 5432 }
+  },
+  level: "error",
+  logger: "DatabaseLogger" # Optional logger name
+)
 ```
 
-### Tool Responses with Errors
+**Key Features:**
+
+- Supports 8 log levels (debug, info, notice, warning, error, critical, alert, emergency) based on https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging#log-levels
+- Server has capability `logging` to send log messages
+- Messages are only sent if a transport is configured
+- Messages are filtered based on the client's configured log level
+- If the log level hasn't been set by the client, no messages will be sent
+
+#### Transport Support
 
-Tools can return error information alongside text content using the `error` parameter.
+- **stdio**: Notifications are sent as JSON-RPC 2.0 messages to stdout
+- **Streamable HTTP**: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE)
 
-The error will be included in the JSON-RPC response as the `isError` field.
+#### Usage Example
 
 ```ruby
-class WeatherTool < MCP::Tool
-  description "Get current weather and return structured data"
+server = MCP::Server.new(name: "my_server")
 
-  def self.call(server_context:)
-    # Do something here
-    content = {}
+# Default Streamable HTTP - session oriented
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
 
-    MCP::Tool::Response.new(
-      [{
-        type: "text",
-        text: content.to_json
-      }],
-      structured_content: content,
-      error: true
-    )
-  end
-end
+# When tools change, notify clients
+server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
+server.notify_tools_list_changed
 ```
 
-### Prompts
-
-MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/latest/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.
-
-The `MCP::Prompt` class provides three ways to create prompts:
-
-1. As a class definition with metadata:
+You can use Stateless Streamable HTTP, where notifications are not supported and all calls are request/response interactions.
+This mode allows for easy multi-node deployment.
+Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new` (`stateless` defaults to `false`):
 
 ```ruby
-class MyPrompt < MCP::Prompt
-  prompt_name "my_prompt"  # Optional - defaults to underscored class name
-  title "My Prompt"
-  description "This prompt performs specific functionality..."
-  arguments [
-    MCP::Prompt::Argument.new(
-      name: "message",
-      title: "Message Title",
-      description: "Input message",
-      required: true
-    )
-  ]
-  meta({ version: "1.0", category: "example" })
-
-  class << self
-    def template(args, server_context:)
-      MCP::Prompt::Result.new(
-        description: "Response description",
-        messages: [
-          MCP::Prompt::Message.new(
-            role: "user",
-            content: MCP::Content::Text.new("User message")
-          ),
-          MCP::Prompt::Message.new(
-            role: "assistant",
-            content: MCP::Content::Text.new(args["message"])
-          )
-        ]
-      )
-    end
-  end
-end
-
-prompt = MyPrompt
+# Stateless Streamable HTTP - session-less
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
 ```
 
-2. Using the `MCP::Prompt.define` method:
+You can enable JSON response mode, where the server returns `application/json` instead of `text/event-stream`.
+Set `enable_json_response: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`:
 
 ```ruby
-prompt = MCP::Prompt.define(
-  name: "my_prompt",
-  title: "My Prompt",
-  description: "This prompt performs specific functionality...",
-  arguments: [
-    MCP::Prompt::Argument.new(
-      name: "message",
-      title: "Message Title",
-      description: "Input message",
-      required: true
-    )
-  ],
-  meta: { version: "1.0", category: "example" }
-) do |args, server_context:|
-  MCP::Prompt::Result.new(
-    description: "Response description",
-    messages: [
-      MCP::Prompt::Message.new(
-        role: "user",
-        content: MCP::Content::Text.new("User message")
-      ),
-      MCP::Prompt::Message.new(
-        role: "assistant",
-        content: MCP::Content::Text.new(args["message"])
-      )
-    ]
-  )
-end
+# JSON response mode
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, enable_json_response: true)
 ```
 
-3. Using the `MCP::Server#define_prompt` method:
+In JSON response mode, the POST response is a single JSON object, so server-to-client messages
+that need to arrive during request processing are not supported:
+request-scoped notifications (`progress`, `log`) are silently dropped, and all server-to-client requests
+(`sampling/createMessage`, `roots/list`, `elicitation/create`) raise an error.
+Session-scoped standalone notifications (`resources/updated`, `elicitation/complete`) and
+broadcast notifications (`tools/list_changed`, etc.) still flow to clients connected to the GET SSE stream.
+This mode is suitable for simple tool servers that do not need server-initiated requests.
+
+By default, sessions do not expire. To mitigate session hijacking risks, you can set a `session_idle_timeout` (in seconds).
+When configured, sessions that receive no HTTP requests for this duration are automatically expired and cleaned up:
 
 ```ruby
-server = MCP::Server.new
-server.define_prompt(
-  name: "my_prompt",
-  description: "This prompt performs specific functionality...",
-  arguments: [
-    Prompt::Argument.new(
-      name: "message",
-      title: "Message Title",
-      description: "Input message",
-      required: true
-    )
-  ],
-  meta: { version: "1.0", category: "example" }
-) do |args, server_context:|
-  Prompt::Result.new(
-    description: "Response description",
-    messages: [
-      Prompt::Message.new(
-        role: "user",
-        content: Content::Text.new("User message")
-      ),
-      Prompt::Message.new(
-        role: "assistant",
-        content: Content::Text.new(args["message"])
-      )
-    ]
-  )
-end
+# Session timeout of 30 minutes
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
 ```
 
-The server_context parameter is the server_context passed into the server and can be used to pass per request information,
-e.g. around authentication state or user preferences.
+### Pagination
 
-### Key Components
+The MCP Ruby SDK supports [pagination](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination)
+for list operations that may return large result sets. Pagination uses string cursor tokens carrying a zero-based offset,
+treated as opaque by clients: the server decides page size, and the client follows `nextCursor` until the server omits it.
 
-- `MCP::Prompt::Argument` - Defines input parameters for the prompt template with name, title, description, and required flag
-- `MCP::Prompt::Message` - Represents a message in the conversation with a role and content
-- `MCP::Prompt::Result` - The output of a prompt template containing description and messages
-- `MCP::Content::Text` - Text content for messages
+Pagination applies to `tools/list`, `prompts/list`, `resources/list`, and `resources/templates/list`.
 
-### Usage
+#### Server-Side: Enabling Pagination
 
-Register prompts with the MCP server:
+Pass `page_size:` to `MCP::Server.new` to split list responses into pages. When `page_size` is omitted (the default),
+list responses contain all items in a single response, preserving the pre-pagination behavior.
 
 ```ruby
 server = MCP::Server.new(
   name: "my_server",
-  prompts: [MyPrompt],
-  server_context: { user_id: current_user.id },
+  tools: tools,
+  page_size: 50,
 )
 ```
 
-The server will handle prompt listing and execution through the MCP protocol methods:
-
-- `prompts/list` - Lists all registered prompts and their schemas
-- `prompts/get` - Retrieves and executes a specific prompt with arguments
+When `page_size` is set, list responses include a `nextCursor` field whenever more pages are available:
 
-### Resources
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "tools": [
+      { "name": "example_tool" }
+    ],
+    "nextCursor": "50"
+  }
+}
+```
 
-MCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).
+Invalid cursors (e.g. non-numeric, negative, or out-of-range) are rejected with JSON-RPC error code `-32602 (Invalid params)` per the MCP specification.
 
-### Reading Resources
+#### Client-Side: Iterating Pages
 
-The `MCP::Resource` class provides a way to register resources with the server.
+`MCP::Client` exposes `list_tools`, `list_prompts`, `list_resources`, and `list_resource_templates`.
+**Each call issues exactly one `*/list` JSON-RPC request and returns exactly one page** — not the full collection.
+The returned result object (`MCP::Client::ListToolsResult` etc.) exposes the page items and the next cursor as method accessors:
 
 ```ruby
-resource = MCP::Resource.new(
-  uri: "https://example.com/my_resource",
-  name: "my-resource",
-  title: "My Resource",
-  description: "Lorem ipsum dolor sit amet",
-  mime_type: "text/html",
-)
+client = MCP::Client.new(transport: transport)
+
+cursor = nil
+loop do
+  page = client.list_tools(cursor: cursor)
+  page.tools.each { |tool| process(tool) }
+  cursor = page.next_cursor
+  break unless cursor
+end
+```
 
-server = MCP::Server.new(
-  name: "my_server",
-  resources: [resource],
-)
+The same pattern applies to `list_prompts` (`page.prompts`), `list_resources` (`page.resources`), and
+`list_resource_templates` (`page.resource_templates`). `next_cursor` is `nil` on the final page.
+
+Because a single call returns a single page, how many items come back depends on the server's `page_size` configuration:
+
+| Server `page_size` | `client.list_tools(cursor: nil)`                                    |
+|--------------------|---------------------------------------------------------------------|
+| Not set (default)  | Returns every item in one response. `next_cursor` is `nil`.         |
+| Set to `N`         | Returns the first `N` items. `next_cursor` is set for continuation. |
+
+If your application needs the complete collection regardless of how the server is configured, either loop on
+`next_cursor` as shown above, or use the whole-collection methods described below.
+
+#### Fetching the Complete Collection
+
+`client.tools`, `client.resources`, `client.resource_templates`, and `client.prompts` auto-iterate
+through all pages and return a plain array of items, guaranteeing the full collection regardless
+of the server's `page_size` setting. When a server paginates, they issue multiple JSON-RPC round
+trips per call and break out of the pagination loop if the server returns the same `nextCursor`
+twice in a row as a safety measure.
+
+```ruby
+tools = client.tools # => Array<MCP::Client::Tool> of every tool on the server.
 ```
 
-The server must register a handler for the `resources/read` method to retrieve a resource dynamically.
+Use these when you want the complete list; use `list_tools(cursor:)` etc. when you need
+fine-grained iteration (e.g. to stream-process pages without loading everything into memory).
+
+### Advanced
+
+#### Custom Methods
+
+The server allows you to define custom JSON-RPC methods beyond the standard MCP protocol methods using the `define_custom_method` method:
 
 ```ruby
-server.resources_read_handler do |params|
-  [{
-    uri: params[:uri],
-    mimeType: "text/plain",
-    text: "Hello from example resource! URI: #{params[:uri]}"
-  }]
+server = MCP::Server.new(name: "my_server")
+
+# Define a custom method that returns a result
+server.define_custom_method(method_name: "add") do |params|
+  params[:a] + params[:b]
+end
+
+# Define a custom notification method (returns nil)
+server.define_custom_method(method_name: "notify") do |params|
+  # Process notification
+  nil
 end
 ```
 
-otherwise `resources/read` requests will be a no-op.
+**Key Features:**
 
-### Resource Templates
+- Accepts any method name as a string
+- Block receives the request parameters as a hash
+- Can handle both regular methods (with responses) and notifications
+- Prevents overriding existing MCP protocol methods
+- Supports instrumentation callbacks for monitoring
 
-The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
+**Usage Example:**
 
 ```ruby
-resource_template = MCP::ResourceTemplate.new(
-  uri_template: "https://example.com/my_resource_template",
-  name: "my-resource-template",
-  title: "My Resource Template",
-  description: "Lorem ipsum dolor sit amet",
-  mime_type: "text/html",
-)
+# Client request
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "add",
+  "params": { "a": 5, "b": 3 }
+}
 
-server = MCP::Server.new(
-  name: "my_server",
-  resource_templates: [resource_template],
-)
+# Server response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": 8
+}
 ```
 
+**Error Handling:**
+
+- Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
+- Supports the same exception reporting and instrumentation as standard methods
+
 ## Building an MCP Client
 
 The `MCP::Client` class provides an interface for interacting with MCP servers.
 
 This class supports:
 
+- Liveness check via the `ping` method (`MCP::Client#ping`)
 - Tool listing via the `tools/list` method (`MCP::Client#tools`)
 - Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)
 - Resource listing via the `resources/list` method (`MCP::Client#resources`)
 - Resource template listing via the `resources/templates/list` method (`MCP::Client#resource_templates`)
-- Resource reading via the `resources/read` method (`MCP::Client#read_resources`)
+- Resource reading via the `resources/read` method (`MCP::Client#read_resource`)
 - Prompt listing via the `prompts/list` method (`MCP::Client#prompts`)
 - Prompt retrieval via the `prompts/get` method (`MCP::Client#get_prompt`)
+- Completion requests via the `completion/complete` method (`MCP::Client#complete`)
 - Automatic JSON-RPC 2.0 message formatting
 - UUID request ID generation
 
@@ -1108,6 +1782,9 @@ stdio_transport = MCP::Client::Stdio.new(
 )
 client = MCP::Client.new(transport: stdio_transport)
 
+# Perform the MCP initialization handshake before sending any requests.
+client.connect
+
 # List available tools.
 tools = client.tools
 tools.each do |tool|
@@ -1134,11 +1811,12 @@ The stdio transport automatically handles:
 
 Use the `MCP::Client::HTTP` transport to interact with MCP servers using simple HTTP requests.
 
-You'll need to add `faraday` as a dependency in order to use the HTTP transport layer:
+You'll need to add `faraday` as a dependency in order to use the HTTP transport layer. Add `event_stream_parser` as well if the server uses SSE (`text/event-stream`) responses:
 
 ```ruby
 gem 'mcp'
 gem 'faraday', '>= 2.0'
+gem 'event_stream_parser', '>= 1.0' # optional, required only for SSE responses
 ```
 
 Example usage:
@@ -1147,6 +1825,9 @@ Example usage:
 http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp")
 client = MCP::Client.new(transport: http_transport)
 
+# Perform the MCP initialization handshake before sending any requests.
+client.connect
+
 # List available tools
 tools = client.tools
 tools.each do |tool|
@@ -1191,6 +1872,18 @@ client.tools # will make the call using Bearer auth
 
 You can add any custom headers needed for your authentication scheme, or for any other purpose. The client will include these headers on every request.
 
+#### Customizing the Faraday Connection
+
+You can pass a block to `MCP::Client::HTTP.new` to customize the underlying Faraday connection.
+The block is called after the default middleware is configured, so you can add middleware or swap the HTTP adapter:
+
+```ruby
+http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp") do |faraday|
+  faraday.use MyApp::Middleware::HttpRecorder
+  faraday.adapter :typhoeus
+end
+```
+
 ### Tool Objects
 
 The client provides a wrapper class for tools returned by the server: