mcp 0.11.0 → 0.12.0

data/README.md

@@ -54,1208 +54,1204 @@ It implements the Model Context Protocol specification, handling model context r
 - `completion/complete` - Returns autocompletion suggestions for prompt arguments and resource URIs
 - `sampling/createMessage` - Requests LLM completion 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
-```
-
-**Key Features:**
 
-- 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
+# Set up the server
+server = MCP::Server.new(
+  name: "example_server",
+  tools: [ExampleTool],
+)
 
-**Usage Example:**
+# Create and start the transport
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open
+```
 
-```ruby
-# Client request
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "method": "add",
-  "params": { "a": 5, "b": 3 }
-}
+You can run this script and then type in requests to the server at the command line.
 
-# Server response
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "result": 8
-}
+```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"}}}
 ```
 
-**Error Handling:**
+#### Rails Controller
 
-- Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
-- Supports the same exception reporting and instrumentation as standard methods
+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.
 
-### Sampling
+You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
+status codes (e.g., 202 Accepted for notifications).
 
-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.
+```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)
 
-**Key Concepts:**
+    render(json: body.first, status: status, headers: headers)
+  end
+end
+```
 
-- **Server-to-Client Request**: Unlike typical MCP methods (client→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
+> [!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.
 
-**Usage Example (Stdio transport):**
+### Configuration
 
-`Server#create_sampling_message` is for single-client transports (e.g., `StdioTransport`).
-For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools instead,
-which routes the request to the correct client session.
+The gem can be configured using the `MCP.configure` block:
 
 ```ruby
-server = MCP::Server.new(name: "my_server")
-transport = MCP::Server::Transports::StdioTransport.new(server)
-server.transport = transport
+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}"
+  }
+end
 ```
 
-Client must declare sampling capability during initialization.
-This happens automatically when the client connects.
+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
-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
+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}"
+}
+
+server = MCP::Server.new(
+  # ... all other options
+  configuration:,
 )
 ```
 
-Result contains the LLM response:
+### Server Context and Configuration Block Data
+
+#### `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.
+
+**Type:**
 
 ```ruby
-{
-  role: "assistant",
-  content: { type: "text", text: "The capital of France is Paris." },
-  model: "claude-3-sonnet-20240307",
-  stopReason: "endTurn"
-}
+server_context: { [String, Symbol] => Any }
 ```
 
-**Parameters:**
+**Example:**
 
-Required:
+```ruby
+server = MCP::Server.new(
+  name: "my_server",
+  server_context: { user_id: current_user.id, request_id: request.uuid }
+)
+```
 
-- `messages:` (Array) - Array of message objects with `role` and `content`
-- `max_tokens:` (Integer) - Maximum tokens in the response
+This hash is then passed as the `server_context` argument to tool and prompt calls, and is included in exception and instrumentation callbacks.
 
-Optional:
+#### Request-specific `_meta` Parameter
 
-- `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" }`)
+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`.
 
-**Using Sampling in Tools (works with both Stdio and HTTP transports):**
+**Access Pattern:**
 
-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:
+When a client includes `_meta` in the request params, it becomes available as `server_context[:_meta]`:
 
 ```ruby
-class SummarizeTool < MCP::Tool
-  description "Summarize text using LLM"
-  input_schema(
-    properties: {
-      text: { type: "string" }
-    },
-    required: ["text"]
-  )
+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)
 
-  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
-    )
+    # Access server's original context
+    user_id = server_context.dig(:user_id)
 
     MCP::Tool::Response.new([{
       type: "text",
-      text: result[:content][:text]
+      text: "Processing for user #{user_id} in session #{session_id}"
     }])
   end
 end
+```
 
-server = MCP::Server.new(name: "my_server", tools: [SummarizeTool])
-server.server_context = server
+**Client Request Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "my_tool",
+    "arguments": { "message": "Hello" },
+    "_meta": {
+      "session_id": "abc123",
+      "request_id": "req_456"
+    }
+  }
+}
 ```
 
-**Tool Use in Sampling:**
+#### Configuration Block Data
 
-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:
+##### Exception Reporter
+
+The exception reporter receives:
+
+- `exception`: The Ruby exception object that was raised
+- `server_context`: The context hash provided to the server
+
+**Signature:**
 
 ```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" }
-)
+exception_reporter = ->(exception, server_context) { ... }
+```
 
-if result[:stopReason] == "toolUse"
-  tool_results = result[:content].map do |tool_use|
-    weather_data = get_weather(tool_use[:input][:city])
+##### Instrumentation Callback
 
-    {
-      type: "tool_result",
-      toolUseId: tool_use[:id],
-      content: [{ type: "text", text: weather_data.to_json }]
-    }
-  end
+The instrumentation callback receives a hash with the following possible keys:
 
-  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: [...]
-  )
+- `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
+
+> [!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:**
+
+```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
 ```
 
-**Error Handling:**
+### Server Protocol Version
 
-- 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
+The server's protocol version can be overridden using the `protocol_version` keyword argument:
 
-### Notifications
+```ruby
+configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
+MCP::Server.new(name: "test_server", configuration: configuration)
+```
 
-The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
+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).
 
-#### Notification Methods
+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`:
 
-The server provides the following notification methods:
+```ruby
+MCP::Configuration.new(protocol_version: nil)
+```
 
-- `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
+If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
 
-#### Session Scoping
+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 using Streamable HTTP transport with multiple clients, each client connection gets its own session. Notifications are scoped as follows:
+### Exception Reporting
 
-- **`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.
+The exception reporter receives two arguments:
 
-#### Notification Format
+- `exception`: The Ruby exception object that was raised
+- `server_context`: A hash containing contextual information about where the error occurred
 
-Notifications follow the JSON-RPC 2.0 specification and use these method names:
+The server_context hash includes:
 
-- `notifications/tools/list_changed`
-- `notifications/prompts/list_changed`
-- `notifications/resources/list_changed`
-- `notifications/progress`
-- `notifications/message`
+- For tool calls: `{ tool_name: "name", arguments: { ... } }`
+- For general request handling: `{ request: { ... } }`
 
-### Progress
+When an exception occurs:
 
-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).
+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
 
-#### How Progress Works
+If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
 
-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
+### Tools
 
-#### Server-Side: Tool with Progress
+MCP spec includes [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) which provide functionality to LLM apps.
 
-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:
+This gem provides a `MCP::Tool` class that can be used to create tools in three ways:
+
+1. As a class definition:
 
 ```ruby
-class LongRunningTool < MCP::Tool
-  description "A tool that reports progress during execution"
+class MyTool < MCP::Tool
+  title "My Tool"
+  description "This tool performs specific functionality..."
   input_schema(
     properties: {
-      count: { type: "integer" },
+      message: { type: "string" },
     },
-    required: ["count"]
+    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(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" }])
+  def self.call(message:, server_context:)
+    MCP::Tool::Response.new([{ type: "text", text: "OK" }])
   end
 end
-```
-
-The `server_context.report_progress` method accepts:
-
-- `progress` (required) — current progress value (numeric)
-- `total:` (optional) — total expected value, so clients can display a percentage
-- `message:` (optional) — human-readable status message
-
-**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.
+tool = MyTool
+```
 
-To enable completions, declare the `completions` capability and register a handler:
+2. By using the `MCP::Tool.define` method with a block:
 
 ```ruby
-server = MCP::Server.new(
-  name: "my_server",
-  prompts: [CodeReviewPrompt],
-  resource_templates: [FileTemplate],
-  capabilities: { completions: {} },
-)
+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
+```
 
-server.completion_handler do |params|
-  ref = params[:ref]
-  argument = params[:argument]
-  value = argument[:value]
+3. By using the `MCP::Server#define_tool` method with a block:
 
-  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
+```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" }])
 end
 ```
 
-The handler receives a `params` hash with:
+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.
 
-- `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: { ... } }`)
+### Tool Annotations
 
-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.
+Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
 
-The server validates that the referenced prompt, resource, or resource template is registered before calling the handler.
-Requests for unknown references return an error.
+- `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
 
-### Logging
+Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
-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).
+> [!NOTE]
+> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
 
-The `notifications/message` notification is used for structured logging between client and server.
+### Tool Output Schemas
 
-#### Log Levels
+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:
 
-The SDK supports 8 log levels with increasing severity:
-
-- `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
-
-#### 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:**
+1. **Class definition with output_schema:**
 
 ```ruby
-server = MCP::Server.new(name: "my_server")
-transport = MCP::Server::Transports::StdioTransport.new(server)
-server.transport = transport
-
-# 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
-  }
-)
-
-# Send log messages at different severity levels
-server.notify_log_message(
-  data: { message: "Application started successfully" },
-  level: "info"
-)
-
-server.notify_log_message(
-  data: { message: "Configuration file not found, using defaults" },
-  level: "warning"
-)
+class WeatherTool < MCP::Tool
+  tool_name "get_weather"
+  description "Get current weather for a location"
 
-server.notify_log_message(
-  data: {
-    error: "Database connection failed",
-    details: { host: "localhost", port: 5432 }
-  },
-  level: "error",
-  logger: "DatabaseLogger" # Optional logger name
-)
-```
+  input_schema(
+    properties: {
+      location: { type: "string" },
+      units: { type: "string", enum: ["celsius", "fahrenheit"] }
+    },
+    required: ["location"]
+  )
 
-**Key Features:**
+  output_schema(
+    properties: {
+      temperature: { type: "number" },
+      condition: { type: "string" },
+      humidity: { type: "integer" }
+    },
+    required: ["temperature", "condition", "humidity"]
+  )
 
-- 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
+  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
+    }
 
-#### Transport Support
+    output_schema.validate_result(weather_data)
 
-- **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)
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: weather_data.to_json
+    }])
+  end
+end
+```
 
-#### Usage Example
+2. **Using Tool.define with output_schema:**
 
 ```ruby
-server = MCP::Server.new(name: "my_server")
-
-# Default Streamable HTTP - session oriented
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
-
-server.transport = transport
-
-# When tools change, notify clients
-server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
-server.notify_tools_list_changed
+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
 ```
 
-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`):
+3. **Using OutputSchema objects:**
 
 ```ruby
-# Stateless Streamable HTTP - session-less
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
+class DataTool < MCP::Tool
+  output_schema MCP::Tool::OutputSchema.new(
+    properties: {
+      success: { type: "boolean" },
+      data: { type: "object" }
+    },
+    required: ["success"]
+  )
+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:
+Output schema may also describe an array of objects:
 
 ```ruby
-# Session timeout of 30 minutes
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
+class WeatherTool < MCP::Tool
+  output_schema(
+    type: "array",
+    items: {
+      properties: {
+        temperature: { type: "number" },
+        condition: { type: "string" },
+        humidity: { type: "integer" }
+      },
+      required: ["temperature", "condition", "humidity"]
+    }
+  )
+end
 ```
 
-### Unsupported Features (to be implemented in future versions)
+Please note: in this case, you must provide `type: "array"`. The default type
+for output schemas is `object`.
 
-- Resource subscriptions
-- Elicitation
+MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/latest/server/tools#output-schema) specifies that:
 
-### Usage
+- **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
 
-> [!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.
-> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
+The output schema follows standard JSON Schema format and helps ensure consistent data exchange between MCP servers and clients.
 
-#### Rails Controller
+### Tool Responses with Structured Content
 
-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 return structured data alongside text content using the `structured_content` parameter.
 
-You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
-status codes (e.g., 202 Accepted for notifications).
+The structured content will be included in the JSON-RPC response as the `structuredContent` field.
 
 ```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
+  description "Get current weather and return structured data"
 
-    render(json: body.first, status: status, headers: headers)
+  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
 ```
 
-#### Stdio Transport
+### Tool Responses with Errors
 
-If you want to build a local command-line application, you can use the stdio transport:
+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
-require "mcp"
+class WeatherTool < MCP::Tool
+  description "Get current weather and return structured data"
 
-# 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"]
-  )
+  def self.call(server_context:)
+    # Do something here
+    content = {}
 
-  class << self
-    def call(message:, server_context:)
-      MCP::Tool::Response.new([{
+    MCP::Tool::Response.new(
+      [{
         type: "text",
-        text: "Hello from example tool! Message: #{message}",
-      }])
-    end
+        text: content.to_json
+      }],
+      structured_content: content,
+      error: true
+    )
   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.
+### Prompts
 
-```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"}}}
-```
+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.
 
-### Configuration
+The `MCP::Prompt` class provides three ways to create prompts:
 
-The gem can be configured using the `MCP.configure` block:
+1. As a class definition with metadata:
 
 ```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)
+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
 
-  config.instrumentation_callback = ->(data) {
-    puts "Got instrumentation data #{data.inspect}"
-  }
+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
 ```
 
-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.
+3. Using the `MCP::Server#define_prompt` method:
 
 ```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
-}
+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
+```
 
-configuration.instrumentation_callback = ->(data) {
-  puts "Got instrumentation data #{data.inspect}"
-}
+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(
-  # ... all other options
-  configuration:,
+  name: "my_server",
+  prompts: [MyPrompt],
+  server_context: { user_id: current_user.id },
 )
 ```
 
-### Server Context and Configuration Block Data
+The server will handle prompt listing and execution through the MCP protocol methods:
 
-#### `server_context`
+- `prompts/list` - Lists all registered prompts and their schemas
+- `prompts/get` - Retrieves and executes a specific prompt with arguments
 
-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.
+### Resources
 
-**Type:**
+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
-server_context: { [String, Symbol] => Any }
+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],
+)
 ```
 
-**Example:**
+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",
-  server_context: { user_id: current_user.id, request_id: request.uuid }
+  resource_templates: [resource_template],
 )
 ```
 
-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.
+Set `server.server_context = server` so that `server_context.create_sampling_message` delegates to the server:
 
 ```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])
+server.server_context = server
 ```
 
-**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
+**Direct Usage:**
 
-**Signature:**
+`Server#create_sampling_message` can also be called directly outside of tools:
 
 ```ruby
-exception_reporter = ->(exception, server_context) { ... }
+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
+)
 ```
 
-##### Instrumentation Callback
-
-The instrumentation callback 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
-- `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
-
-> [!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:**
+Result contains the LLM response:
 
 ```ruby
-instrumentation_callback = ->(data) { ... }
-# where data is a Hash with keys as described above
+{
+  role: "assistant",
+  content: { type: "text", text: "The capital of France is Paris." },
+  model: "claude-3-sonnet-20240307",
+  stopReason: "endTurn"
+}
 ```
 
-**Example:**
-
-```ruby
-MCP.configure do |config|
-  config.instrumentation_callback = ->(data) {
-    puts "Instrumentation: #{data.inspect}"
-  }
-end
-```
+For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools
+to route the request to the correct client session.
 
-### Server Protocol Version
+**Tool Use in Sampling:**
 
-The server's protocol version can be overridden using the `protocol_version` keyword argument:
+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
-configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
-MCP::Server.new(name: "test_server", configuration: configuration)
-```
+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 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).
+if result[:stopReason] == "toolUse"
+  tool_results = result[:content].map do |tool_use|
+    weather_data = get_weather(tool_use[:input][:city])
 
-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`:
+    {
+      type: "tool_result",
+      toolUseId: tool_use[:id],
+      content: [{ type: "text", text: weather_data.to_json }]
+    }
+  end
 
-```ruby
-MCP::Configuration.new(protocol_version: nil)
+  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
 ```
 
-If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
-
-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.
+**Error Handling:**
 
-### Exception Reporting
+- 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
 
-The exception reporter receives two arguments:
+### Notifications
 
-- `exception`: The Ruby exception object that was raised
-- `server_context`: A hash containing contextual information about where the error occurred
+The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
 
-The server_context hash includes:
+#### Notification Methods
 
-- For tool calls: `{ tool_name: "name", arguments: { ... } }`
-- For general request handling: `{ request: { ... } }`
+The server provides the following notification methods:
 
-When an exception occurs:
+- `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
 
-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
+#### Session Scoping
 
-If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
+When using Streamable HTTP transport with multiple clients, each client connection gets its own session. Notifications are scoped as follows:
 
-### Tools
+- **`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.
 
-MCP spec includes [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) which provide functionality to LLM apps.
+#### Notification Format
 
-This gem provides a `MCP::Tool` class that can be used to create tools in three ways:
+Notifications follow the JSON-RPC 2.0 specification and use these method names:
 
-1. As a class definition:
+- `notifications/tools/list_changed`
+- `notifications/prompts/list_changed`
+- `notifications/resources/list_changed`
+- `notifications/progress`
+- `notifications/message`
 
-```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"
-  )
+### Progress
 
-  def self.call(message:, server_context:)
-    MCP::Tool::Response.new([{ type: "text", text: "OK" }])
-  end
-end
+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).
 
-tool = MyTool
-```
+#### How Progress Works
 
-2. By using the `MCP::Tool.define` method with a block:
+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
 
-```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
-```
+#### Server-Side: Tool with Progress
 
-3. By using the `MCP::Server#define_tool` method with a block:
+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
-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
-```
-
-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
-
-Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
-
-- `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.
-
-> [!NOTE]
-> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
-
-### Tool Output Schemas
-
-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:
-
-1. **Class definition with output_schema:**
-
-```ruby
-class WeatherTool < MCP::Tool
-  tool_name "get_weather"
-  description "Get current weather for a location"
-
+class LongRunningTool < MCP::Tool
+  description "A tool that reports progress during execution"
   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
-```
-
-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"])
-      )
-    ]
+    properties: {
+      count: { type: "integer" },
+    },
+    required: ["count"]
   )
+
+  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
 ```
 
-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.
+The `server_context.report_progress` method accepts:
 
-### Key Components
+- `progress` (required) — current progress value (numeric)
+- `total:` (optional) — total expected value, so clients can display a percentage
+- `message:` (optional) — human-readable status message
 
-- `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
+**Key Features:**
 
-### Usage
+- 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
 
-Register prompts with the MCP server:
+### 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(
   name: "my_server",
-  prompts: [MyPrompt],
-  server_context: { user_id: current_user.id },
+  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 will handle prompt listing and execution through the MCP protocol methods:
+The handler receives a `params` hash with:
 
-- `prompts/list` - Lists all registered prompts and their schemas
-- `prompts/get` - Retrieves and executes a specific prompt with arguments
+- `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: { ... } }`)
 
-### Resources
+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.
 
-MCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).
+The server validates that the referenced prompt, resource, or resource template is registered before calling the handler.
+Requests for unknown references return an error.
 
-### Reading Resources
+### Logging
 
-The `MCP::Resource` class provides a way to register resources with the server.
+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).
+
+The `notifications/message` notification is used for structured logging between client and server.
+
+#### Log Levels
+
+The SDK supports 8 log levels with increasing severity:
+
+- `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
+
+#### 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
-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")
+transport = MCP::Server::Transports::StdioTransport.new(server)
+
+# 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
+  }
 )
 
-server = MCP::Server.new(
-  name: "my_server",
-  resources: [resource],
+# Send log messages at different severity levels
+server.notify_log_message(
+  data: { message: "Application started successfully" },
+  level: "info"
+)
+
+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
 )
 ```
 
-The server must register a handler for the `resources/read` method to retrieve a resource dynamically.
+**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
+
+- **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)
+
+#### Usage Example
 
 ```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")
+
+# Default Streamable HTTP - session oriented
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+
+# When tools change, notify clients
+server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
+server.notify_tools_list_changed
+```
+
+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
+# Stateless Streamable HTTP - session-less
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
+```
+
+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
+# Session timeout of 30 minutes
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
+```
+
+### 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 = 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
+
+### Unsupported Features (to be implemented in future versions)
+
+- Resource subscriptions
+- Elicitation
+
 ## Building an MCP Client
 
 The `MCP::Client` class provides an interface for interacting with MCP servers.
@@ -1405,6 +1401,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: