mcp 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e47e8d36e628ba2779956d3a876b466f00eb80b92e29f43f5b8135c1698eadb
-  data.tar.gz: 71ea590aed7b14098c6d1707347be1d7d1ffc9b8e321ec8784bb62e364daa095
+  metadata.gz: 69ef263cadd9221259fedfea19655d64cdecd7175deca3139439577b48fb10b2
+  data.tar.gz: 4580aafd0866efce3f102a701d244dd67af7b8881b19306d4b81ab2701a7350a
 SHA512:
-  metadata.gz: eac238d515948c47a61d3ce4f584f83c0f8cf7282e52fab1aecd0080f895fb4674a38d5fcb21382d4bd12ec72e8223467c7ad8680a76cb4d85c72448ec5875a6
-  data.tar.gz: c0fbf1ee2021aa4634c80f49731987e40f1fcf72a7c84bd4be74e685fa821b069d17dbe90f848c0a2909cfa30c6fcce49034acf985b55f6434f88d6a26caa3ff
+  metadata.gz: a5aae701572da5725edf8e02ba8da55debfc702183b123813aba22ca005bf3ee1e61193543975c111065b49e5eddac520600fc775a026fc04d5b28050d22313b
+  data.tar.gz: bd8a9bce3c67b2f4db31bd0bb58b85e9417c997be075f07a9e597a2819facc922c8cea9796fe9ed543b498ec9e3d080fa24b9ce0246e660d5dc875c94b995c0e

data/README.md

@@ -46,8 +46,38 @@ It implements the Model Context Protocol specification, handling model context r
 ### Supported Methods
 
 - `initialize` - Initializes the protocol and returns server capabilities
-- `server/discover` - Sessionless capability discovery (MCP 2026-07-28 draft, SEP-2575): returns `supportedVersions`, `capabilities`, `serverInfo`,
-  and `instructions`, and responds before `initialize` and without an `Mcp-Session-Id`
+- `server/discover` - Sessionless capability discovery (MCP 2026-07-28, SEP-2575): returns the modern `supportedVersions`,
+  `capabilities`, `instructions`, the required `ttlMs`/`cacheScope` cache hints, and the server identity as the optional
+  `io.modelcontextprotocol/serverInfo` stamp in the result `_meta`, and responds before `initialize`
+  and without an `Mcp-Session-Id`. The server also serves the full stateless modern lifecycle: requests carrying the SEP-2575 `_meta` envelope
+  (`io.modelcontextprotocol/protocolVersion`, `clientInfo`, and `clientCapabilities`) are validated per request,
+  and the Streamable HTTP transport serves them on a sessionless single-exchange path. On the client, `MCP::Client#connect` negotiates
+  the lifecycle automatically by default (probe `server/discover`, fall back to the `initialize` handshake), `connect(mode: :modern)` skips
+  the handshake entirely, `connect(mode: :legacy)` forces the classic handshake, and `MCP::Client#discover` exposes the raw discovery result
+- `subscriptions/listen` - Long-lived notification subscription stream (MCP 2026-07-28, SEP-2575), replacing the legacy HTTP GET listening stream:
+  the client opts in via the `notifications` filter (`toolsListChanged` / `promptsListChanged` / `resourcesListChanged` / `resourceSubscriptions`),
+  the server acknowledges the honored subset with `notifications/subscriptions/acknowledged` as the first stream message,
+  and every delivered notification carries the correlating `io.modelcontextprotocol/subscriptionId` in `_meta`. Served on the Streamable HTTP modern path;
+  stdio answers `-32601`. Concurrent streams are capped by `max_listen_subscriptions:` (default 1000), and each stream receives an SSE keepalive
+  comment frame every `listen_keepalive_interval:` seconds (default 15) so a dropped connection frees its slot; pass `listen_keepalive_interval: nil`
+  when an upstream proxy already keeps the stream alive
+- Multi round-trip `input_required` results (MCP 2026-07-28, SEP-2322): a `tools/call`, `prompts/get`, or `resources/read` handler that
+  opts in to `server_context:` may return `MCP::Server::InputRequiredResult.new(input_requests:, request_state:)` to ask the client for
+  additional input (`elicitation/create`, `sampling/createMessage`, or `roots/list` shapes) instead of performing a server-initiated request,
+  which the modern lifecycle forbids. On the retried request the handler re-runs from the start and reads the answers via
+  `server_context.input_responses` / `server_context.input_response(key)` and the echoed opaque `server_context.request_state`
+  (deterministic replay; the server holds no memory between rounds). The SDK rejects issuance on legacy requests and returns `-32021`
+  when an embedded request needs a client capability the request did not declare. The echoed `requestState` arrives as
+  client-controlled input: pass `MCP::Server::RequestStateSecurity.new(key:)` (a 32-byte key) via `Server.new(request_state_security:)` to
+  have it sealed with AES-256-GCM and bound to a TTL plus the originating method, target, and arguments, all transparently to handlers.
+  Multi-process deployments must share the key across workers; without `request_state_security:` the state crosses the wire exactly as
+  the handler wrote it and protecting it is the handler author's responsibility. On the client, register handlers with
+  `on_elicitation` / `on_sampling` / `on_roots` - the same registrations that answer a real server-to-client request - and
+  declare the matching capabilities on `connect` (a server embeds only the request kinds the client declared);
+  `call_tool` / `get_prompt` / `read_resource` then resume `input_required` results automatically: each embedded request is fulfilled by
+  the matching handler and the original request is re-issued with `inputResponses` plus the echoed `requestState`
+  (with exponential backoff for `requestState`-only load-shedding legs). Without a matching handler they raise `MCP::Client::InputRequiredError`,
+  and the `input_responses:` / `request_state:` keyword arguments support manual driving
 - `ping` - Simple health check
 - `logging/setLevel` - Configures the minimum log level for the server
 - `tools/list` - Lists all registered tools and their schemas
@@ -346,7 +376,8 @@ server = MCP::Server.new(
 ```
 
 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.
+Note that the exception reporter does not receive this user-defined hash, and instrumentation
+callbacks omit it unless you opt in with `instrument_server_context`.
 See the relevant sections below for the arguments they receive.
 
 #### Request-specific `_meta` Parameter
@@ -460,10 +491,31 @@ around_request = ->(data, &request_handler) { request_handler.call }
 
 **`data` availability by timing:**
 
-- Before `request_handler.call`: `method`
+- Before `request_handler.call`: `method`, and `server_context` when `instrument_server_context` is enabled
 - 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)
 
+**Exposing the user-defined `server_context` (opt in):**
+
+`data` omits the user-defined `server_context` by default, because that hash is
+application-supplied and may hold values a tracing backend should not receive.
+Enable it when you need to tag spans with the request's subject:
+
+```ruby
+MCP.configure do |config|
+  config.instrument_server_context = true
+
+  config.around_request = ->(data, &request_handler) {
+    Sentry.set_user(id: data.dig(:server_context, :user_id))
+    request_handler.call
+  }
+end
+```
+
+`data[:server_context]` is the hash passed to `Server.new` — `nil` when the host
+set none. It is not the exception reporter's context argument, which describes
+where a failure occurred rather than who made the request.
+
 > [!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
@@ -515,6 +567,8 @@ It receives a hash with the following possible keys:
 - `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
+- `server_context`: (Any, optional) The user-defined hash passed to `Server.new`, present only when
+  `instrument_server_context` is enabled
 
 **Signature:**
 
@@ -531,8 +585,7 @@ configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
 MCP::Server.new(name: "test_server", configuration: configuration)
 ```
 
-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 no protocol version is specified, the latest handshake version (`2025-11-25`) is applied by default.
 
 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`:
 
@@ -542,6 +595,11 @@ MCP::Configuration.new(protocol_version: nil)
 
 If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
 
+The pin scopes the `initialize` handshake, so it accepts handshake versions (`2025-11-25` and earlier) only. Per the SEP-2575 era model,
+`2026-07-28` carries its version on every request and has no handshake at all, so there is nothing for a pin to configure there and setting it raises `ArgumentError`;
+a client asking `initialize` for a modern version is counter-offered the pinned version (or the latest handshake version), matching the TypeScript and Python SDKs.
+Clients reach `2026-07-28` through `server/discover` and the per-request `_meta` envelope, which the bundled transports serve alongside the handshake with no configuration needed.
+
 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.
 
 ### Exception Reporting
@@ -872,6 +930,53 @@ class WeatherTool < MCP::Tool
 end
 ```
 
+### Tool Responses with Image, Audio, and Embedded Resources
+
+Tool responses are not limited to text. The `MCP::Content` module provides `Image`, `Audio`, and `EmbeddedResource` content types,
+which serialize to the `image`, `audio`, and `resource` content blocks defined by the MCP spec. Image and audio data is passed as
+a base64-encoded string together with its MIME type:
+
+```ruby
+class ChartTool < MCP::Tool
+  description "Render a chart as a PNG image"
+
+  def self.call(server_context:)
+    MCP::Tool::Response.new([
+      MCP::Content::Text.new("Here is the rendered chart:").to_h,
+      MCP::Content::Image.new(Base64.strict_encode64(render_chart_png), "image/png").to_h,
+    ])
+  end
+end
+
+class SpeechTool < MCP::Tool
+  description "Synthesize speech audio"
+
+  def self.call(server_context:)
+    MCP::Tool::Response.new([
+      MCP::Content::Audio.new(Base64.strict_encode64(synthesize_wav), "audio/wav").to_h,
+    ])
+  end
+end
+```
+
+An embedded resource wraps `MCP::Resource::TextContents` or `MCP::Resource::BlobContents`, allowing a tool to return resource contents inline:
+
+```ruby
+class ReportTool < MCP::Tool
+  description "Return a report as an embedded resource"
+
+  def self.call(server_context:)
+    contents = MCP::Resource::TextContents.new(
+      uri: "report://monthly",
+      mime_type: "application/json",
+      text: { total: 42 }.to_json,
+    )
+
+    MCP::Tool::Response.new([MCP::Content::EmbeddedResource.new(contents).to_h])
+  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.
@@ -1010,6 +1115,49 @@ The server will handle prompt listing and execution through the MCP protocol met
 - `prompts/list` - Lists all registered prompts and their schemas
 - `prompts/get` - Retrieves and executes a specific prompt with arguments
 
+### Prompts with Image and Embedded Resource Content
+
+Prompt messages are not limited to text. The same `MCP::Content` types used in tool responses can be used as message content,
+letting a prompt template include images or inline resource contents. Unlike tool responses, the content object is passed directly rather than as a hash;
+`MCP::Prompt::Message` serializes it when the prompt result is returned:
+
+```ruby
+class CodeReviewPrompt < MCP::Prompt
+  prompt_name "code_review"
+  description "Review a source file with an accompanying diagram"
+  arguments [
+    MCP::Prompt::Argument.new(name: "file_uri", description: "URI of the file to review", required: true),
+  ]
+
+  class << self
+    def template(args, server_context:)
+      MCP::Prompt::Result.new(
+        messages: [
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::EmbeddedResource.new(
+              MCP::Resource::TextContents.new(
+                uri: args["file_uri"],
+                mime_type: "text/x-ruby",
+                text: read_source(args["file_uri"]),
+              ),
+            ),
+          ),
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Image.new(architecture_diagram_base64, "image/png"),
+          ),
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Text.new("Please review the code above, using the diagram for context."),
+          ),
+        ],
+      )
+    end
+  end
+end
+```
+
 ### Resources
 
 MCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).
@@ -1126,6 +1274,34 @@ server.resources_read_handler do |params|
 end
 ```
 
+### Reading Binary Resources
+
+For binary resources, respond with a base64-encoded `blob` field instead of `text`.
+The `MCP::Resource::TextContents` and `MCP::Resource::BlobContents` classes build the two contents shapes defined by the spec:
+
+```ruby
+server.resources_read_handler do |params|
+  case params[:uri]
+  when "file:///logo.png"
+    [
+      MCP::Resource::BlobContents.new(
+        uri: params[:uri],
+        mime_type: "image/png",
+        data: Base64.strict_encode64(File.binread("logo.png")),
+      ).to_h,
+    ]
+  else
+    [
+      MCP::Resource::TextContents.new(
+        uri: params[:uri],
+        mime_type: "text/plain",
+        text: "Hello from example resource!",
+      ).to_h,
+    ]
+  end
+end
+```
+
 ### Resource Templates
 
 Resource templates follow the same pattern. Class-based templates declare a `uri_template` and
@@ -1201,6 +1377,31 @@ server = MCP::Server.new(
 )
 ```
 
+Registered templates are listed through the `resources/templates/list` protocol method.
+To serve reads for URIs that match a template, extract the variable parts of the URI in your `resources_read_handler`:
+
+```ruby
+resource_template = MCP::ResourceTemplate.new(
+  uri_template: "file:///items/{item_id}",
+  name: "item",
+  mime_type: "application/json",
+)
+
+server = MCP::Server.new(name: "my_server", resource_templates: [resource_template])
+
+server.resources_read_handler do |params|
+  if (match = params[:uri].match(%r{\Afile:///items/(?<item_id>[^/]+)\z}))
+    [{
+      uri: params[:uri],
+      mimeType: "application/json",
+      text: { id: match[:item_id] }.to_json,
+    }]
+  else
+    raise MCP::Server::ResourceNotFoundError.new(params[:uri], params)
+  end
+end
+```
+
 ### Roots
 
 The Model Context Protocol allows servers to request filesystem roots from clients through the `roots/list` method.
@@ -1218,6 +1419,22 @@ Roots define the boundaries of where a server can operate, providing a list of d
 > automatically and routes the request onto the originating POST stream on the Streamable HTTP transport. Calling the corresponding
 > `ServerSession` methods without `related_request_id:` still works but emits a deprecation warning.
 
+**Timeouts:** every server-to-client request is bounded, so a client that never answers cannot park the handler's thread indefinitely.
+`MCP::Server::Transports::StreamableHTTPTransport` waits `server_to_client_request_timeout:` seconds (600 by default), then tells
+the client the request was abandoned and raises `MCP::Server::RequestTimeoutError`. Individual calls override the deadline with `timeout:`,
+which is the knob to reach for when a prompt legitimately waits on a person:
+
+```ruby
+server_context.create_form_elicitation(
+  message: "Approve this deployment?",
+  requested_schema: { type: "object", properties: { approved: { type: "boolean" } } },
+  timeout: 3600, # This one waits up to an hour.
+)
+```
+
+`StdioTransport` is not bounded and ignores `timeout:`: it owns the client process, so a client that stops answering
+surfaces as end-of-file rather than as a wait that never ends.
+
 **Using Roots in Tools:**
 
 Tools that accept a `server_context:` parameter can call `list_roots` on it.
@@ -1793,6 +2010,98 @@ server.define_tool(name: "collect_contact", description: "Collect contact info")
 end
 ```
 
+The `requested_schema` must be a flat object schema: a top-level `type: "object"` whose `properties` are limited to
+primitive types (`string`, `number`, `integer`, `boolean`). Nested objects and arrays are not allowed, which keeps
+the schema simple enough for clients to render as a form. Per the MCP specification, the client validates
+the user's input against this schema before returning it, so the `content` of an `accept` response matches the requested shape.
+
+#### Default Values and Enums
+
+Properties may declare a `default` value (SEP-1034), which clients use to pre-fill the form.
+String properties may declare `enum` values, optionally with human-readable `enumNames` (SEP-1330), which clients render as a choice list:
+
+```ruby
+server.define_tool(name: "configure_deploy", description: "Configure a deployment") do |server_context:|
+  result = server_context.create_form_elicitation(
+    message: "Configure the deployment",
+    requested_schema: {
+      type: "object",
+      properties: {
+        replicas: { type: "integer", default: 3 },
+        verbose: { type: "boolean", default: false },
+        environment: {
+          type: "string",
+          enum: ["dev", "staging", "prod"],
+          enumNames: ["Development", "Staging", "Production"],
+          default: "dev",
+        },
+      },
+      required: ["environment"],
+    },
+  )
+
+  MCP::Tool::Response.new([{ type: "text", text: "Deploying to #{result[:content][:environment]}" }])
+end
+```
+
+#### Enum Schemas
+
+For enumerated choices, use `MCP::Elicitation::EnumSchema` to construct the canonical schema shapes per
+[SEP-1330](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1330) instead of building
+the underlying Hash by hand. The five class methods cover titled and untitled, single-select and multi-select,
+plus the legacy `enumNames` form retained for backward compatibility:
+
+```ruby
+size_schema = MCP::Elicitation::EnumSchema.titled_single_select(
+  options: [
+    { value: "s", title: "Small" },
+    { value: "m", title: "Medium" },
+    { value: "l", title: "Large" },
+  ],
+  default: "m",
+)
+
+tags_schema = MCP::Elicitation::EnumSchema.untitled_multi_select(
+  values: ["urgent", "billing", "feedback"],
+)
+
+result = server_context.create_form_elicitation(
+  message: "Tell us about your order",
+  requested_schema: {
+    type: "object",
+    properties: {
+      size: size_schema.to_h,
+      tags: tags_schema.to_h,
+    },
+    required: ["size"],
+  },
+)
+```
+
+The available builders are `untitled_single_select`, `titled_single_select`, `untitled_multi_select`, `titled_multi_select`,
+and `legacy_titled`. Each accepts optional `default:`, `title:`, and `description:`.
+
+The same builders produce the `requestedSchema` of an `elicitation/create` request embedded in a SEP-2322 `input_required` result,
+which is how elicitation reaches clients on the stateless 2026-07-28 lifecycle:
+
+```ruby
+MCP::Server::InputRequiredResult.new(
+  input_requests: {
+    "size" => {
+      method: "elicitation/create",
+      params: {
+        message: "Pick a size",
+        requestedSchema: {
+          type: "object",
+          properties: { size: size_schema.to_h },
+          required: ["size"],
+        },
+      },
+    },
+  },
+)
+```
+
 #### URL Mode
 
 URL mode directs the user to an external URL for out-of-band interactions such as OAuth flows:
@@ -1921,6 +2230,18 @@ 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
+
+# When prompts change, notify clients
+server.define_prompt(name: "new_prompt") do |args, server_context:|
+  MCP::Prompt::Result.new(messages: [])
+end
+server.notify_prompts_list_changed
+
+# When resources change, notify clients
+server.define_resource(uri: "resource://new", name: "new_resource", mime_type: "text/plain") do
+  [MCP::Resource::TextContents.new(uri: "resource://new", mime_type: "text/plain", text: "contents")]
+end
+server.notify_resources_list_changed
 ```
 
 You can use Stateless Streamable HTTP, where notifications are not supported and all calls are request/response interactions.
@@ -2081,13 +2402,18 @@ If your application needs the complete collection regardless of how the server i
 `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.
+trips per call. Two guards keep that loop finite: it stops when the server returns a `nextCursor`
+it has already sent, and it stops after `max_pages` pages.
 
 ```ruby
 tools = client.tools # => Array<MCP::Client::Tool> of every tool on the server.
 ```
 
+`MCP::Client.new` accepts an optional `max_pages:` keyword that caps how many pages these methods
+will walk. It defaults to `1_000`; a server that keeps offering a fresh `nextCursor` past that
+point raises `MCP::Client::PaginationLimitError` rather than being followed indefinitely. Raise it
+if you legitimately expect more pages than that.
+
 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).
 
@@ -2097,8 +2423,11 @@ Per SEP-2549, list and read results can carry cache hints telling clients how lo
 `0` means do not cache) and whether shared intermediaries may cache it (`cacheScope`: `"public"` or `"private"`).
 
 Emission is opt-in: pass `ttl_ms:` and/or `cache_scope:` to `MCP::Server.new` and both fields are added to `tools/list`, `prompts/list`, `resources/list`,
-`resources/templates/list`, and `resources/read` results (a missing field is filled with the defaults `ttlMs: 0` / `cacheScope: "public"`).
+`resources/templates/list`, and `resources/read` results (a missing field is filled with the defaults `ttlMs: 0` / `cacheScope: "private"`,
+the scope that keeps a potentially user-dependent result out of shared caches).
 When neither is set, responses are serialized exactly as before.
+The 2026-07-28 revision makes both hints required on these results, so on requests carrying the modern `_meta` envelope
+the server always emits them, filling unset values with the same defaults; stable protocol versions keep the opt-in behavior.
 
 ```ruby
 server = MCP::Server.new(
@@ -2199,6 +2528,55 @@ This class supports:
 Clients are initialized with a transport layer instance that handles the low-level communication mechanics.
 Authorization is handled by the transport layer.
 
+### Lifecycle Negotiation (SEP-2575)
+
+`MCP::Client#connect` selects the protocol lifecycle automatically by default: on the bundled
+`MCP::Client::HTTP` and `MCP::Client::Stdio` transports it probes `server/discover` first and adopts
+the stateless modern lifecycle (MCP 2026-07-28) when the server serves it, falling back to
+the classic `initialize` handshake otherwise. Custom transports whose `connect` does not declare
+a `mode:` keyword always receive the classic call shape, unchanged.
+
+```ruby
+client.connect                                 # negotiate automatically (default)
+client.connect(mode: :legacy)                  # force the classic initialize handshake
+client.connect(mode: :modern)                  # require the modern lifecycle; fails on legacy-only servers
+client.connect(protocol_version: "2025-11-25") # an explicit legacy version pins the handshake, no probe
+```
+
+Prefer `mode: :legacy` for spawn-per-invocation CLI tools (the probe adds a round trip per process)
+and when using server-initiated requests (`on_elicitation` / `on_sampling`), which exist only on
+the legacy lifecycle.
+
+Because the raw `connect` return value and `MCP::Client#server_info` mirror the wire result,
+their shape depends on the negotiated lifecycle: `InitializeResult` (`protocolVersion`,
+top-level `serverInfo`) on legacy, `DiscoverResult` (`supportedVersions`, `ttlMs`/`cacheScope`)
+on modern. Code that should work against both lifecycles can use the era-independent readers instead:
+
+```ruby
+client.protocol_version      # negotiated or adopted version, either lifecycle
+client.server_capabilities   # capabilities Hash, either lifecycle
+client.instructions          # instructions text, either lifecycle
+client.server_implementation # server name/version; nil when a modern server does not identify itself
+```
+
+Troubleshooting: if `server_info["protocolVersion"]` starts returning `nil` after a server you connect to was upgraded,
+the server now serves the modern lifecycle and the automatic negotiation adopted it.
+Pass `mode: :legacy` for an immediate return to the previous behavior, or switch to the readers above for a permanent fix.
+
+### Custom Headers from Tool Parameters (SEP-2243)
+
+On a modern `MCP::Client::HTTP` connection, `tools/call` mirrors arguments whose `inputSchema` property carries
+an `x-mcp-header` annotation into `Mcp-Param-{Name}` request headers, so intermediaries can route
+on the values without parsing bodies. The declarations are learned from `tools/list` responses:
+list the tools before calling one to enable the mirroring. Values that cannot ride as plain ASCII header values
+(non-ASCII, control characters, edge whitespace, empty strings) are wrapped as `=?base64?...?=`,
+and a `null` or absent argument omits its header.
+
+Per the specification, a tool definition whose `x-mcp-header` annotations are invalid (empty or non-token names,
+duplicate names, non-primitive properties, annotations outside a chain of `properties` keys) is excluded from
+`tools/list` results on modern connections, with a warning naming the tool.
+Legacy connections are unaffected: nothing is learned, mirrored, or excluded.
+
 ## Transport Layer Interface
 
 If the transport layer you need is not included in the gem, you can build and pass your own instances so long as they conform to the following interface:
@@ -2322,6 +2700,13 @@ The server will send `notifications/progress` back to the client during executio
 an SSE event or a JSON response body. A message that reaches this limit before completing is rejected as a transport error, preventing unbounded memory growth from
 a server that never terminates an SSE event. It defaults to `4 * 1024 * 1024` (4 MiB); raise it if your server returns larger responses.
 
+`MCP::Client::HTTP.new` also accepts `max_reconnection_wait:`, a budget in seconds for resuming a closed SSE stream. It gates every wait between reconnection attempts,
+and what is left of it becomes the read timeout of each resumed stream. The server chooses that wait through the SSE `retry:` field, and resuming happens on the calling thread,
+so without a budget a server answering with a large `retry:` parks a thread of your application for as long as it likes. It defaults to `300` (5 minutes).
+The server's `retry:` is never shortened: when honoring it would run past the budget, the client stops trying to resume and raises instead,
+the same thing it already does once the reconnection attempts are used up. A floor of 100ms applies to each wait, so a `retry: 0` cannot spin
+the listening stream's reconnect loop; waiting longer than the server asked for is explicitly allowed by the SSE reconnection algorithm the spec points at.
+
 #### Server-to-Client Requests (Elicitation)
 
 Servers can send requests back to the client while one of the client's own requests is in flight - for example,
@@ -2595,6 +2980,28 @@ whether the swap was triggered by
 `instance_variable_set(:@url, ...)`, by a Faraday customizer rewriting `url_prefix`, or by a custom middleware rewriting `env.url` (including just `env.url.query`) at request time,
 and whether the new URL is `http://` *or* `https://` to a different host or tenant.
 
+##### Discovery URL Destinations
+
+The scheme rules above say how a URL is contacted, not where it points. Discovery URLs arrive from the network, so the SDK also constrains their destinations.
+Both checks run before the request is sent, and neither is configurable.
+
+- The `resource_metadata` URL in a `WWW-Authenticate` challenge must be on the MCP server's own origin. Protected Resource Metadata describes that server,
+  so a real deployment publishes it there; requiring it means a `401` cannot aim the first request of the flow at an unrelated host. This is stricter than RFC 9728,
+  which does not require it.
+- The PRM `authorization_servers` entry and the `authorization_endpoint`, `token_endpoint`, and `registration_endpoint` from Authorization Server metadata must not be
+  IP literals in a private, loopback, link-local, or unique-local range, per the SSRF precaution in [RFC 9728 Section 7.7](https://www.rfc-editor.org/rfc/rfc9728#section-7.7).
+  The blocked ranges are `0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10`, `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.168.0.0/16`, `::/96`, `fc00::/7`,
+  and `fe80::/10`, along with the IPv4-mapped IPv6 spellings of each and the `localhost` name.
+- That range check is skipped when the MCP server URL you configured is itself on such an address. Pointing the client at a private network is a deliberate act,
+  and the authorization server for it usually lives on the same network, so `http://localhost` development and deployments that never leave a corporate network keep working.
+
+The range check compares IP literals and does not resolve hostnames, so it cannot recognize an internal service that is named rather than addressed,
+such as `https://vault.corp.internal/`. Resolving names here would not close that gap either, because the address the SDK looked up need not be the one
+the HTTP client connects to a moment later. The same-origin rule is what protects the `resource_metadata` URL, which is the only one of these a server supplies directly.
+
+If you replace the OAuth HTTP client through `MCP::Client::OAuth::Flow.new(http_client_factory:)`, do not add redirect-following middleware. Every check above runs against
+the URL as written, so a connection that follows a `3xx` on its own would reach hosts these rules just refused.
+
 #### Customizing the Faraday Connection
 
 You can pass a block to `MCP::Client::HTTP.new` to customize the underlying Faraday connection.
@@ -2625,6 +3032,18 @@ The Ruby client recognizes such results and raises `MCP::Client::InputRequiredEr
 and the raw `result`; automatic resumption is not implemented yet, so callers respond manually if they opt into the draft flow. `MCP::ResultType::COMPLETE` and `MCP::ResultType::INPUT_REQUIRED`
 are provided for forward compatibility. Servers on stable protocol versions never send `resultType`, so existing behavior is unchanged.
 
+SEP-2322 also makes `resultType` a required member of every result a 2026-07-28 server returns. The server stamps `resultType: "complete"` on all results of requests carrying
+the modern `_meta` envelope (and on `server/discover` results), while results that already carry a discriminator (`"input_required"`, the tasks extension's `"task"`) keep it.
+Legacy results stay unstamped, and clients treat an absent `resultType` as `"complete"` per the spec.
+
+#### Dual-era authoring (legacy fulfilment shim)
+
+Handlers written in the 2026 style serve pre-2026 clients too: when a `tools/call`, `prompts/get`, or `resources/read` handler returns an `InputRequiredResult` on the legacy wire,
+the server fulfills it in place of the client's driver. Each `inputRequests` entry is sent as the equivalent real server-to-client request
+(`elicitation/create`, `sampling/createMessage`, `roots/list`), associated with the originating request per SEP-2260; the answers are collected under the same keys,
+and the handler re-runs with `server_context.input_responses` populated and the raw `requestState` echoed, the same deterministic replay contract the modern client driver follows.
+The shim is on by default (matching the TypeScript SDK) and capped at 8 rounds; `MCP::Server.new(input_required_legacy_shim: false)` restores the strict rejection of `input_required` results on legacy requests.
+
 ## Conformance Testing
 
 The `conformance/` directory contains a test server and runner that validate the SDK against the MCP specification using [`@modelcontextprotocol/conformance`](https://github.com/modelcontextprotocol/conformance).

data/lib/json_rpc_handler.rb

@@ -135,11 +135,12 @@ module JsonRpcHandler
       success_response(id: id, result: result)
     rescue MCP::Server::RequestHandlerError => e
       handle_request_error(e, id, id_validation_pattern)
-    rescue StandardError => e
+    rescue StandardError
+      # The exception message is deliberately not echoed into `data`: it can carry
+      # internals that must not reach untrusted clients (CWE-209).
       error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
         code: ErrorCode::INTERNAL_ERROR,
         message: "Internal error",
-        data: e.message,
       })
     end
   end