Merge pull request #563 from koic/validate_icon_src_and_sizes

Validate the src and sizes of an icon against the specification

.github/workflows/conformance.yml

@@ -26,4 +26,4 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: '24' # Specify the latest Node.js version.
-      - run: bundle exec rake conformance
+      - run: bundle exec rake conformance:test

.gitignore

@@ -9,3 +9,7 @@
 /spec/reports/
 /tmp/
 Gemfile.lock
+docs/_site/
+docs/.jekyll-cache/
+docs/.jekyll-metadata
+docs/_data/versions.yml

AGENTS.md

@@ -15,8 +15,9 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
 - `bundle install` - Install dependencies
 - `rake test` - Run all tests
 - `rake rubocop` - Run linter
-- `rake` - Run tests and linting (default task)
+- `rake` - Run linting, tests, and the conformance suite (default task)
-- `bundle exec rake conformance` - Run the MCP conformance suite (see conformance/README.md)
+- `bundle exec rake conformance:test` - Run the MCP conformance suite (see conformance/README.md)
+- `bundle exec rake docs:preview` - Serve the documentation site locally at http://localhost:4000 (PORT to override)
 - `ruby -I lib -I test test/path/to/specific_test.rb` - Run single test file
 - `gem build mcp.gemspec` - Build the gem
 

CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-09-09
+
+This release keeps the HTTP client working with json 3.0. That release accepts the options of `JSON.parse`
+as keywords only, and Faraday's JSON response middleware, through 2.14.3, passes them as a positional Hash,
+which Ruby 3 no longer converts, so every JSON body the client received failed as an internal error.
+The client now parses response bodies itself, the way it already handled streamed ones, and no longer
+registers the middleware. A malformed JSON body delivered whole by an adapter without streaming support
+now raises `RequestHandlerError` with `error_type: :parse_error`, as the streamed path already did.
+
+### Fixed
+
+- Parse HTTP client response bodies without Faraday's JSON middleware, which json 3.0 breaks (#546)
+
+## [1.5.0] - 2026-09-05
+
+This release makes the client answer a server's `ping` with the empty result the specification requires.
+Earlier clients replied with Method not found over Streamable HTTP and stayed silent over stdio,
+so a server that checks liveness dropped their long-lived sessions. On the OAuth side,
+the embedding application can refuse an authorization request through `authorization_request_validator`,
+and stored tokens are refreshed only against the authorization server that issued them:
+when the server named for a session differs, the client reauthorizes instead of refreshing,
+and the validator sees the newly named server. Tokens stored by earlier releases carry no issuer and keep refreshing.
+
+### Added
+
+- Add `authorization_request_validator` to let the embedding application refuse an authorization request (#539)
+
+### Fixed
+
+- Answer server-to-client pings in the client (#541)
+
+## [1.4.0] - 2026-08-28
+
+This release repairs the `subscriptions/listen` stream. A host that buffers its responses,
+the documented Rails controller pattern among them, can decline the method with
+`serve_subscriptions_listen: false` instead of answering a modern client with a streaming body
+it cannot render, and the stream's ordering guarantees are enforced: no notification reaches
+a client before the acknowledgement, and none follows the graceful closing result.
+
+### Added
+
+- Add `serve_subscriptions_listen:` for hosts that cannot hold an SSE stream open (#533)
+
+### Fixed
+
+- Deliver `subscriptions/listen` notifications only after the acknowledgement (#532)
+- Serialize `subscriptions/listen` writes so the graceful result is the final message (#535)
+
 ## [1.3.0] - 2026-08-22
 
 User-facing documentation now lives on the documentation site at https://ruby.sdk.modelcontextprotocol.io,

README.md

@@ -9,7 +9,7 @@ Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.
 - Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host
 - Build [MCP clients](https://ruby.sdk.modelcontextprotocol.io/client/) that connect to any MCP server, with automatic lifecycle negotiation and OAuth 2.1 authorization
 - Speak every standard transport: stdio and Streamable HTTP (including SSE), with a Rails integration
-- Cover the full protocol surface: server-to-client requests, multi round-trip results, notifications, progress, logging, cancellation, completions, and pagination
+- Cover the full protocol surface: server-to-client requests, multi round-trip requests, notifications, progress, logging, cancellation, completions, and pagination
 
 ## Installation
 

ROADMAP.md

@@ -19,11 +19,15 @@ which also defines the Semantic Versioning scheme and breaking-change policy.
 ## Deprecated Features
 
 The 2026-07-28 spec revision deprecates Roots, Sampling, and Logging (SEP-2577).
-These features remain fully supported throughout 1.x, and the SDK emits deprecation warnings when they are used
+These features remain supported throughout 1.x: on the legacy lifecycle they work unchanged
-with protocol version 2026-07-28 or newer.
+(the deprecations do not apply there), and the 2026-07-28 lifecycle carries them through its own mechanisms:
-Under Semantic Versioning their removal requires a major release, but no removal is scheduled yet:
+roots-shaped and sampling-shaped input requests embedded in `InputRequiredResult` responses
-whether 2.0.0 removes them depends on how future MCP spec revisions treat these features
+(the SEP-2322 multi round-trip requests pattern) and per-request log delivery through the envelope's `logLevel`.
-and on adoption of their replacements.
+The replacements SEP-2577 names live outside the protocol: tool parameters or configuration for roots,
+direct LLM provider APIs for sampling, and stderr or OpenTelemetry for logging.
+The client emits a deprecation warning when a modern connect declares the deprecated Roots or Sampling capabilities.
+Under Semantic Versioning their removal requires a major release, but no removal is scheduled yet: whether 2.0.0 removes
+them depends on how future MCP spec revisions treat these features and on adoption of their replacements.
 
 ## Conformance
 

Rakefile

@@ -14,10 +14,11 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: [:rubocop, :test, :conformance]
+task default: [:rubocop, :test, "conformance:test"]
 
-desc "Run MCP conformance tests (PORT, SCENARIO, SPEC_VERSION, VERBOSE)"
+namespace :conformance do
-task :conformance do |t|
+  desc "Run MCP conformance tests (PORT, SCENARIO, SPEC_VERSION, VERBOSE)"
+  task :test do |t|
     next unless npx_available?(t.name)
 
     require_relative "conformance/server_runner"
@@ -31,24 +32,67 @@ task :conformance do |t|
 
     Conformance::ServerRunner.new(**options).run
     Conformance::ClientRunner.new(**options.reject { |key, _value| key == :port }).run
-end
+  end
 
-desc "List available conformance scenarios"
+  desc "List available conformance scenarios"
-task :conformance_list do |t|
+  task :list do |t|
     next unless npx_available?(t.name)
 
     system("npx", "--yes", "@modelcontextprotocol/conformance", "list", "--server")
     system("npx", "--yes", "@modelcontextprotocol/conformance", "list", "--client")
-end
+  end
 
-desc "Start the conformance server (PORT)"
+  desc "Start the conformance server (PORT)"
-task :conformance_server do
+  task :server do
     require_relative "conformance/server"
 
     options = {}
     options[:port] = Integer(ENV["PORT"]) if ENV["PORT"]
 
     Conformance::Server.new(**options).start
+  end
+end
+
+# The other two former names now fail with a "Did you mean?" suggestion, but a bare `conformance`
+# would match the `conformance/` directory: Rake synthesizes a file task for it and exits 0 without
+# running anything. This keeps the name pointing at the suite instead of at that silent no-op.
+desc "Alias for conformance:test"
+task conformance: "conformance:test"
+
+namespace :docs do
+  desc "Serve the documentation site locally at http://localhost:4000 (PORT)"
+  task :preview do
+    docs_dir = File.expand_path("docs", __dir__)
+    generate_docs_versions_data(docs_dir)
+
+    env = {
+      "BUNDLE_GEMFILE" => File.join(docs_dir, "Gemfile"),
+      "RUBYOPT" => "-r#{File.join(docs_dir, "_preview", "taint_shim.rb")}",
+    }
+    port = ENV.fetch("PORT", "4000")
+
+    Bundler.with_unbundled_env do
+      system(env, "bundle", "install", "--quiet", chdir: docs_dir, exception: true)
+      system(env, "bundle", "exec", "jekyll", "serve", "--port", port, chdir: docs_dir, exception: true)
+    rescue Interrupt
+      # Ctrl-C is the way to stop the preview, not an error.
+    end
+  end
+end
+
+# Mirrors bin/generate-gh-pages.sh: the released site receives `_data/versions.yml` from
+# the version tags at deploy time, and the preview generates the same data so the nav footer
+# shows the released-gem version line.
+def generate_docs_versions_data(docs_dir)
+  versions = %x(git tag --list).split("\n").filter_map { |tag|
+    tag[/\A[^0-9]*(\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?)\z/, 1]
+  }.sort_by { |version|
+    Gem::Version.new(version)
+  }.reverse
+  return if versions.empty?
+
+  mkdir_p(File.join(docs_dir, "_data"))
+  File.write(File.join(docs_dir, "_data", "versions.yml"), versions.map { |version| "- #{version}\n" }.join)
 end
 
 def npx_available?(task_name)

conformance/README.md

@@ -12,7 +12,7 @@ Validates the Ruby SDK's conformance to the MCP specification using [`@modelcont
 ### Run all scenarios
 
 ```bash
-bundle exec rake conformance
+bundle exec rake conformance:test
 ```
 
 Runs both server and client conformance tests in sequence. Server conformance starts the
@@ -31,20 +31,20 @@ are allowed to fail without affecting the exit code.
 
 ```bash
 # Run a single server scenario
-bundle exec rake conformance SCENARIO=ping
+bundle exec rake conformance:test SCENARIO=ping
 
 # Use a different port with verbose output
-bundle exec rake conformance PORT=3000 VERBOSE=1
+bundle exec rake conformance:test PORT=3000 VERBOSE=1
 
 # Start the server on a specific port
-bundle exec rake conformance_server PORT=3000
+bundle exec rake conformance:server PORT=3000
 ```
 
 ### Start the server and test separately
 
 ```bash
 # Terminal 1: start the server
-bundle exec rake conformance_server
+bundle exec rake conformance:server
 
 # Terminal 2: run all scenarios
 npx @modelcontextprotocol/conformance@alpha server --url http://localhost:9292/mcp
@@ -59,7 +59,7 @@ on a single scenario. Stop the server with Ctrl+C when done.
 ### List available scenarios
 
 ```bash
-bundle exec rake conformance_list
+bundle exec rake conformance:list
 ```
 
 Prints all scenario names that can be passed to `SCENARIO`.
@@ -76,7 +76,7 @@ repository with the conformance server running:
 
 ```bash
 # Terminal 1 (this repository): start the conformance server
-bundle exec rake conformance_server
+bundle exec rake conformance:server
 
 # Terminal 2 (conformance repository): run the tier audit skill as a slash command in Claude Code
 /mcp-sdk-tier-audit /path/to/modelcontextprotocol/ruby-sdk http://localhost:9292/mcp
@@ -102,4 +102,4 @@ conformance/
 
 Known-failing scenarios are registered in `conformance/expected_failures.yml`. They are allowed to
 fail without affecting the exit code and are tracked to catch regressions.
-These are shown in the output of `bundle exec rake conformance`.
+These are shown in the output of `bundle exec rake conformance:test`.

docs/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Dependencies for the local docs preview (`rake docs:preview`), kept out of the gem's own Gemfile:
+# github-pages mirrors the GitHub Pages runtime that builds the released site
+# (jekyll-remote-theme, jekyll-redirect-from, and the Jekyll version Pages actually runs).
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
+gem "webrick"
+
+# Former default gems that the Jekyll version pinned by github-pages still requires on Ruby 4.0.
+gem "base64"
+gem "bigdecimal"
+gem "csv"
+gem "logger"

docs/_client/authorization.md

@@ -37,9 +37,13 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
 - On a `401 Unauthorized`, parse the `WWW-Authenticate` header, discover the authorization server (Protected Resource Metadata + RFC 8414 Authorization Server Metadata),
   perform Dynamic Client Registration if needed, run the OAuth 2.1 Authorization Code flow with PKCE (S256), and retry the failed request with the acquired token.
 - Fall back to the legacy 2025-03-26 discovery when the server publishes no Protected Resource Metadata, matching the TypeScript and Python SDKs: the MCP server's origin acts
-  as the authorization base URL, its metadata is fetched from `<origin>/.well-known/oauth-authorization-server` without the RFC 8414 issuer byte-match (which the legacy spec predates),
+  as the authorization base URL, its metadata is fetched from `<origin>/.well-known/oauth-authorization-server` and must name that origin as its `issuer` (RFC 8414 Section 3.3),
   and when even that is absent the spec's default endpoints `/authorize`, `/token`, and `/register` at the origin are used with PKCE S256 assumed.
+  When no Protected Resource Metadata candidate serves a JSON object, a request that could not reach the server, or that returned a `5xx` or `429`,
+  raises `Flow::MetadataUnreachableError` instead of triggering that fallback, and a body over the response cap is refused outright.
 - On subsequent 401s with a saved `refresh_token`, exchange it at the token endpoint before falling back to the full interactive flow (RFC 6749 Section 6).
+  `ClientCredentialsProvider` and `CrossAppAccessProvider` refresh the same way and fall back to their own grant instead;
+  their refresh also requires the `issuer` the SDK records on the tokens, so tokens stored without it run the grant again.
 - On a `403 Forbidden` whose `WWW-Authenticate` header carries `error="insufficient_scope"` (OAuth 2.0 step-up, RFC 6750 Section 3.1 and the MCP scope-selection-strategy),
   run a fresh authorization request for the union of the currently granted scope and the scope named in the challenge, then retry the failed request once.
   The refresh path is bypassed because refreshing would re-issue the same scope set the server just rejected. A `403` without that challenge is surfaced unchanged.
@@ -93,10 +97,16 @@ Required keyword arguments to `Provider.new`:
 Optional keyword arguments:
 
 - `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
+- `authorization_request_validator`: Callable invoked with an `MCP::Client::OAuth::AuthorizationRequest` before any authorization request is built.
+  Returning a falsy value abandons the flow with `Flow::AuthorizationRefusedError`. See [Reviewing the authorization request](#reviewing-the-authorization-request).
+- `http_client_customizer`: Callable invoked with the Faraday connection the SDK builds for the OAuth flow's own requests, after its defaults and before its origin guard.
+  See [Customizing the OAuth HTTP Client](#customizing-the-oauth-http-client).
 - `storage`: Object responding to `tokens`, `save_tokens(t)`, `client_information`, `save_client_information(info)`. Defaults to `MCP::Client::OAuth::InMemoryStorage`,
   which keeps credentials in process memory only. Persisted `client_information` is stamped with an `"issuer"` member binding it to the authorization server that
   issued it (SEP-2352): when the server's authorization server changes, the SDK discards the stale registration and its tokens and re-registers automatically
-  (portable CIMD `client_id`s are kept). Treat the hash as opaque and persist it as-is.
+  (portable CIMD `client_id`s are kept). Saved `tokens` carry an `"issuer"` member of their own, recording the authorization server that minted them, which is what
+  lets a later refresh refuse a server the MCP server has since renamed. Treat both hashes as opaque and persist them as-is; a storage that writes out selected members
+  instead drops these bindings with no error.
 - `client_id_metadata_document_url`: URL where you publish a Client ID Metadata Document
   (`draft-ietf-oauth-client-id-metadata-document` and the MCP authorization specification).
   When the authorization server advertises `client_id_metadata_document_supported: true`,
@@ -108,6 +118,14 @@ Optional keyword arguments:
   served at the URL is a separate JSON artifact from the `client_metadata` keyword above:
   the DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include
   `client_id` set to the document URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
+- `token_request_params`: Hash of String keys and values added to every token request the provider makes,
+  for parameters the authorization server requires beyond the grant itself, such as Auth0's `audience`.
+  Defaults to `nil`, which adds nothing. The authorization request is not affected.
+  A key the SDK sets itself (listed in `Flow::RESERVED_TOKEN_REQUEST_PARAMS`), a Hash that compares keys by identity,
+  or a value that is not a Hash of Strings is refused with `Flow::InvalidTokenRequestParamsError`, a subclass of `ArgumentError`,
+  when the provider is built, and the accepted Hash is copied and frozen.
+  Any provider that defines a `token_request_params` method gets the same treatment on every token request it makes;
+  the flow checks the returned value by the same rules and raises the same error before the token request is sent.
 
 {: .warning }
 > The OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591) is deprecated as a client registration mechanism as of MCP 2026-07-28 in favor of Client ID Metadata Documents,
@@ -155,11 +173,33 @@ provider = MCP::Client::OAuth::Provider.new(
 )
 ```
 
+### Token Endpoint Errors
+
+When a token exchange or refresh fails, `MCP::Client::OAuth::Flow::AuthorizationError` includes the HTTP status and
+the authorization server's `error` and `error_description` from [RFC 6749 Section 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2).
+For example:
+
+```text
+Token endpoint returned status 400. invalid_request: Client must not use multiple authentication methods
+```
+
+The exception exposes `http_status`, `error`, and `error_description` readers for structured diagnostics. Missing or non-string
+diagnostic fields are `nil`; non-JSON responses retain the status-only message. Other authorization failures have `nil` readers.
+An `invalid_grant` response still raises `Flow::InvalidGrantError`, a subclass of `Flow::AuthorizationError`, so refresh-token
+recovery behavior is unchanged.
+
+Diagnostic fields are limited to 128 characters for `error` and 512 for `error_description`, including a trailing `...` when
+truncated. Characters outside the RFC's printable ASCII set are replaced with spaces, and surrounding whitespace is removed.
+The SDK excludes all other response fields, including `error_uri`, and does not include the raw response body in these errors.
+Descriptions are provider-controlled text, not guaranteed to be free of sensitive information; apply your application's logging
+and redaction policy before persisting them or displaying them to users.
+
 ### Client Credentials Grant
 
 For a confidential machine-to-machine client (no user, no browser redirect), use `MCP::Client::OAuth::ClientCredentialsProvider` instead of `Provider`.
 The transport discovers the authorization server the same way, then exchanges the OAuth 2.1 `client_credentials` grant (RFC 6749 Section 4.4) at
-the token endpoint. There is no authorization request, PKCE, or `offline_access`, because the grant does not issue a refresh token.
+the token endpoint. There is no authorization request, PKCE, or `offline_access`, because the grant is not expected to issue a refresh token (RFC 6749 Section 4.4.3);
+a refresh token the authorization server issues anyway is used on the next `401`.
 
 ```ruby
 provider = MCP::Client::OAuth::ClientCredentialsProvider.new(
@@ -167,6 +207,7 @@ provider = MCP::Client::OAuth::ClientCredentialsProvider.new(
   client_secret: ENV.fetch("MCP_CLIENT_SECRET"),
   # token_endpoint_auth_method: "client_secret_basic" (default), "client_secret_post", or "private_key_jwt"
   # scope: "mcp:read mcp:write" (optional; used when the server does not advertise scopes)
+  # token_request_params: { "audience" => "https://api.example.com" } (optional; parameters the authorization server requires)
 )
 
 transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp", oauth: provider)
@@ -182,13 +223,15 @@ Keyword arguments:
 - `private_key`, `signing_algorithm`: Required with `private_key_jwt` - the key (a PEM string
   or `OpenSSL::PKey::PKey`, never written to `storage`) signs the client assertion with `"ES256"`
   or `"RS256"`; `client_secret` must not be set, because the private key is the credential.
-- `scope`, `storage`: Optional, same meaning as on `Provider`.
+- `scope`, `storage`, `authorization_request_validator`, `token_request_params`, `http_client_customizer`: Optional, same meaning as on `Provider`.
+  Use `token_request_params` for a parameter the authorization server requires on the `client_credentials` grant, such as Auth0's `audience`.
 
 ### Cross-App Access (JWT Bearer) Grant
 
 For enterprise MCP deployments where an identity provider (IdP) governs authorization (SEP-990), use `MCP::Client::OAuth::CrossAppAccessProvider` instead of `Provider`.
 The client exchanges an IdP-issued ID token for an Identity Assertion Authorization Grant (ID-JAG) at the IdP via RFC 8693 token exchange, then presents the ID-JAG
 to the MCP authorization server with the RFC 7523 `jwt-bearer` grant, authenticating with `client_secret_basic`. There is no authorization request, PKCE, DCR, or `offline_access`.
+A refresh token the authorization server issues is exchanged on the next `401` with the stored client secret, without calling `assertion_provider` again.
 Mirrors `CrossAppAccessProvider` and `requestJwtAuthorizationGrant` in the TypeScript SDK.
 
 `MCP::Client::OAuth::IDJAGTokenExchange.request` performs the RFC 8693 exchange at the IdP token endpoint. Wrap it in a callable so the same provider can plug into
@@ -219,7 +262,39 @@ Keyword arguments:
 - `assertion_provider`: Required. Callable invoked as `call(audience:, resource:)` and returning the ID-JAG assertion.
   `audience` is the MCP authorization server's validated issuer identifier; `resource` is the canonical MCP server URL (RFC 8707).
   Passing both through to `IDJAGTokenExchange.request` covers the common case.
-- `scope`, `storage`: Optional, same meaning as on `Provider`.
+- `scope`, `storage`, `authorization_request_validator`, `token_request_params`, `http_client_customizer`: Optional, same meaning as on `Provider`.
+
+### Customizing the OAuth HTTP Client
+
+The requests the OAuth flow makes (Protected Resource Metadata discovery on the MCP server's origin, authorization server metadata discovery,
+dynamic client registration, and every token request the flow sends, whether the first exchange, a refresh, or a step-up) go over a Faraday connection of their own,
+not over the transport's connection: the transport's is bound to the MCP server URL and carries the `headers:` and the customizer block meant for that server.
+To add middleware to the OAuth flow's connection, or to swap its adapter, pass `http_client_customizer:` to the provider:
+
+```ruby
+provider = MCP::Client::OAuth::ClientCredentialsProvider.new(
+  client_id: "my-service",
+  client_secret: ENV.fetch("MCP_CLIENT_SECRET"),
+  http_client_customizer: ->(faraday) { faraday.use MyApp::Middleware::HttpRecorder },
+)
+```
+
+The callable receives the `Faraday::Connection` after the SDK has applied its defaults and registered the middleware that records the requested URL,
+and before the SDK registers its origin guard, the same position the transport's customizer block has on the MCP server connection.
+It may be invoked more than once, and from more than one thread at a time, so keep it free of side effects and safe to run concurrently;
+today it runs once per authorization attempt, but that is not a promise.
+A few constraints follow from the checks described below:
+
+- Do not add redirect-following middleware. Every destination check runs against the URL as written, so a request that middleware added by the customizer would send
+  to a different origin after the SDK has recorded the requested URL, whether by following a `3xx` or by rewriting the URL, is refused with `Flow::DestinationMismatchError`
+  before it reaches the adapter, as is a request that reaches the guard without that record. Middleware inserted ahead of the record with `builder.insert(0, ...)`
+  that rewrites the URL first or rebuilds the environment is outside the guard, as is following done inside an adapter, so leave both off.
+- Leave `Accept-Encoding` unset. The response cap below is measured on decoded bytes, and claiming the header turns Net::HTTP's decoding off.
+- Do not add Faraday's `raise_error` middleware. The flow reads statuses itself, both to tell an absent metadata document from a failed request
+  and to turn a token endpoint error into `Flow::InvalidGrantError`.
+- With an adapter that does not stream through `on_data`, the response cap is applied once the body has been buffered rather than as it arrives.
+- A middleware that records requests sees the client credentials on token requests (`Authorization: Basic`, `client_secret`, `client_assertion`), refresh tokens,
+  and the access tokens in token responses; redact them before they reach a log.
 
 ### Communication Security
 
@@ -251,10 +326,80 @@ The range check compares IP literals and does not resolve hostnames, so it canno
 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
+On the connection the SDK builds, a middleware that would send a request to a different origin, by following a `3xx` or by rewriting the URL, is refused before the request
-the URL as written, so a connection that follows a `3xx` on its own would reach hosts these rules just refused.
+goes out (see [Customizing the OAuth HTTP Client](#customizing-the-oauth-http-client)). A connection supplied through `MCP::Client::OAuth::Flow.new(http_client_factory:)`
+replaces that one, the provider's `http_client_customizer` and the guard included, so do not add redirect-following middleware to it: every check above runs against
+the URL as written, and a connection that follows a `3xx` on its own would reach hosts these rules just refused.
+A factory that wants to keep them can return `MCP::Client::OAuth::Flow.build_http_client(customizer)`, the connection the SDK builds for itself.
 
 The SDK also bounds what those endpoints may return. A discovery, dynamic client registration, token, or token exchange response is refused once it passes 4 MiB,
 measured as the body arrives rather than after it has been buffered, so a compressed body that expands past the limit is refused partway through the expansion.
 Unlike the transport's `max_message_bytes:`, this limit is not configurable: these documents run to kilobytes in normal operation, and a connection supplied through
 `http_client_factory:` is bounded as well, so there is no way to opt out of it.
+
+### Reviewing the authorization request
+
+The checks above constrain where the SDK will send a request. What they cannot decide is whether the authorization server an MCP server names is one you want
+your users signing in to. That choice belongs to the MCP server: it publishes `authorization_servers` in its Protected Resource Metadata and states the scopes
+it wants in `scopes_supported` or in the `WWW-Authenticate` challenge. An authorization server is legitimately a different origin from the resource it protects,
+so no origin rule can settle the question, and validating that a token was issued for the intended audience is a responsibility the specification places on
+MCP servers rather than on clients.
+
+`authorization_request_validator` is where an application that *does* know which providers its users deal with can say so:
+
+```ruby
+ALLOWED_ISSUERS = ["https://login.example.com", "https://accounts.google.com"]
+
+provider = MCP::Client::OAuth::Provider.new(
+  # client_metadata:, redirect_uri:, redirect_handler:, and callback_handler: as in the first example.
+  authorization_request_validator: ->(request) {
+    ALLOWED_ISSUERS.include?(request.authorization_server)
+  },
+)
+```
+
+The argument is an `MCP::Client::OAuth::AuthorizationRequest` carrying `authorization_server` (the selected issuer), `scopes` (an Array, empty when neither
+the challenge nor the metadata named any), `server_url`, and `resource`. It is one object rather than keyword arguments so that later revisions of the specification
+can add to it without changing the shape you wrote. Only the named readers are the contract. The positional access a `Struct` also happens to provide
+(`request[0]`, `to_a`, `each`) is not, and can break when the representation changes.
+
+`server_url` is the URL the transport was configured with, verbatim; `resource` is the value actually sent as the RFC 8707 `resource`, which is that URL canonicalized
+(fragment and userinfo dropped, scheme and host lowercased, a default port removed) or, when the Protected Resource Metadata advertises one,
+the canonicalized value from there. That advertised value may name a parent path, so a server at `https://api.example.com/mcp` can legitimately produce
+a `resource` of `https://api.example.com`. Match on `server_url` when you mean the server you configured.
+
+Compare the issuer as a whole string, the way the SDK compares it everywhere else, rather than picking its host out: multi-tenant providers tell tenants apart by path,
+and a legacy authorization server whose metadata never named an issuer arrives as `nil`, which an exact comparison refuses instead of raising.
+
+The provider is only half of the decision. The MCP server chose the scopes too, so a request naming a provider you allow can still ask for more than that server has
+any business asking for. `scopes` rides on the request so that a host with a policy per server can apply it:
+
+```ruby
+ALLOWED_SCOPES = { "https://api.example.com/mcp" => ["mcp:read", "mcp:write"] }
+
+provider = MCP::Client::OAuth::Provider.new(
+  # client_metadata:, redirect_uri:, redirect_handler:, and callback_handler: as in the first example.
+  authorization_request_validator: ->(request) {
+    ALLOWED_ISSUERS.include?(request.authorization_server) && request.scopes.all? { |scope| ALLOWED_SCOPES.fetch(request.server_url, []).include?(scope) }
+  },
+)
+```
+
+A host with a user to ask can put the decision to them instead. The request carries what such a prompt has to name: the provider, the scopes, and the server that asked for them.
+
+It runs on all three grants, after that server's metadata has been fetched (which is where the validated issuer comes from) and before any registration, credential,
+or user reaches it: on the authorization-code grant before dynamic client registration and before any browser is opened,
+and on the JWT bearer grant before `assertion_provider` is invoked, since obtaining an ID-JAG tells your identity provider which authorization server
+the assertion is for. Refusing therefore leaves nothing registered at, and no assertion minted for, the authorization server you rejected.
+Returning a falsy value raises `Flow::AuthorizationRefusedError`. It subclasses `Flow::AuthorizationError`, so a rescue written for that still catches it,
+while rescuing the narrower class tells a refusal by your own policy apart from a network or metadata failure.
+
+The hook decides whether to proceed, not what to ask for: the scopes are passed to the authorization server unchanged either way, because the specification
+requires a client to treat the scopes in the challenge as authoritative for the operation. Leaving it unset authorizes whatever the server asked for,
+which is what every MCP SDK does today.
+
+It is asked when a new grant is requested, not on every token refresh, which happens unattended and against an authorization server you already answered for.
+An authorization server that changes between authorization and refresh is caught instead: the SDK records which one issued the tokens, and `refresh!` refuses to
+present a refresh token to a different one, even when the client identity is portable across authorization servers as a Client ID Metadata Document URL is.
+The transport answers that refusal by running a full authorization, which brings the new authorization server back here for you to accept or refuse.
+Tokens stored before this behavior shipped carry no issuer and keep refreshing; the binding applies from their next authorization.

docs/_client/index.md

@@ -17,7 +17,8 @@ This class supports:
 - Lifecycle negotiation and connection via `MCP::Client#connect`, adopting the modern lifecycle
   when the server serves it; see [Lifecycle](/client/lifecycle/)
 - Server discovery via the `server/discover` method (`MCP::Client#discover`); see [Explicit Discovery](/client/lifecycle/#explicit-discovery)
-- Liveness check via the `ping` method (`MCP::Client#ping`)
+- Liveness check via the `ping` method (`MCP::Client#ping`), and automatic answers to server pings;
+  see [Answering Server Pings](/client/ping/#answering-server-pings)
 - Tool listing via the `tools/list` method (`MCP::Client#tools`)
 - Tool invocation via the `tools/call` method (`MCP::Client#call_tool`)
 - Resource listing via the `resources/list` method (`MCP::Client#resources`)
@@ -25,9 +26,9 @@ This class supports:
 - Resource reading via the `resources/read` method (`MCP::Client#read_resource`)
 - Prompt listing via the `prompts/list` method (`MCP::Client#prompts`)
 - Prompt retrieval via the `prompts/get` method (`MCP::Client#get_prompt`)
-- Completion requests via the `completion/complete` method (`MCP::Client#complete`); see [Completions](/server/completions/)
+- Completion requests via the `completion/complete` method (`MCP::Client#complete`); see [Completion](/server/completion/)
 - Automatic driving of multi round-trip `input_required` results once `on_elicitation`, `on_sampling`,
-  or `on_roots` handlers are registered; see [Multi-Round-Trip Results](/client/multi-round-trip-results/)
+  or `on_roots` handlers are registered; see [Multi Round-Trip Requests](/client/mrtr/)
 - Cancellation of in-flight requests via the `cancellation:` keyword; see [Cancellation](/client/cancellation/)
 - Cursor-based page iteration on the `list_*` methods and whole-collection fetching with
   the `max_pages` guard; see [Pagination](/client/pagination/)

docs/_client/lifecycle.md

@@ -32,7 +32,7 @@ only when the server does not serve the modern lifecycle, or when `mode: :legacy
 ## Lifecycle Negotiation
 
 `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`](/server/discovery/) first and adopts
+`MCP::Client::HTTP` and `MCP::Client::Stdio` transports it probes [`server/discover`](/server/discover/) first and adopts
 the stateless modern lifecycle (MCP 2026-07-28, SEP-2575) 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.
@@ -69,7 +69,7 @@ Pass `mode: :legacy` for an immediate return to the previous behavior, or switch
 `MCP::Client#discover` sends `server/discover` directly: sessionless capability discovery
 that works before (or instead of) `connect`. It returns an `MCP::Client::DiscoverResult` struct
 exposing `supported_versions`, `capabilities`, `server_info`, `instructions`, and
-the `ttl_ms` / `cache_scope` cache hints; see the server [Discovery](/server/discovery/) page
+the `ttl_ms` / `cache_scope` cache hints; see the server [Discovery](/server/discover/) page
 for the wire shapes.
 
 ```ruby

docs/_client/mrtr.md

@@ -0,0 +1,62 @@
+---
+layout: default
+title: Multi Round-Trip Requests
+nav_order: 4
+redirect_from:
+  - /client/multi-round-trip-results/
+---
+
+# Multi Round-Trip Requests
+
+MCP 2026-07-28 replaces in-flight server-to-client requests with Multi Round-Trip Requests (SEP-2322): instead of issuing `sampling/createMessage`, `roots/list`,
+or `elicitation/create` while a request is being processed, a server may answer with a result whose `resultType` is `"input_required"`, carrying an `inputRequests` map
+and an opaque `requestState`; the client fulfills the requests and re-issues the original request with `inputResponses` and the echoed `requestState`.
+
+## Automatic Driving
+
+The Ruby client drives such results automatically: once a handler is registered through `on_elicitation`, `on_sampling`, or `on_roots`, the `call_tool`, `get_prompt`,
+and `read_resource` methods fulfill the embedded requests and re-issue the original request with `inputResponses` plus the echoed `requestState`, capped at `input_required_max_rounds`
+(10 by default, matching the TypeScript and Python SDKs).
+
+```ruby
+client = MCP::Client.new(transport: transport)
+client.connect(capabilities: { elicitation: { form: {} } })
+
+client.on_elicitation do |params|
+  { action: "accept", content: { name: "Alice" } }
+end
+
+# The input_required round trips are driven automatically; this returns the final result.
+response = client.call_tool(name: "collect_name", arguments: {})
+```
+
+Declare the capabilities matching the registered handlers on `connect`: a server embeds only the request kinds
+the client declared.
+
+## Manual Driving
+
+Without a matching handler, `MCP::Client::InputRequiredError` is raised instead of returning the result as if it were final;
+the error exposes `input_requests`, `request_state`, and the raw `result` for manual driving via the `input_responses:` and `request_state:` keywords:
+
+```ruby
+begin
+  client.call_tool(name: "collect_name", arguments: {})
+rescue MCP::Client::InputRequiredError => error
+  answers = error.input_requests.transform_values { |request| answer_for(request) }
+
+  client.call_tool(
+    name: "collect_name",
+    arguments: {},
+    input_responses: answers,
+    request_state: error.request_state,
+  )
+end
+```
+
+`MCP::ResultType::COMPLETE` and `MCP::ResultType::INPUT_REQUIRED` are provided for forward compatibility.
+Servers on legacy protocol versions never send `resultType`, so existing behavior is unchanged.
+
+## Server Side
+
+Authoring `input_required` results with `InputRequiredResult`, securing `requestState`, `resultType` stamping, and the legacy fulfillment
+shim that serves pre-2026 clients are documented on the server [Multi Round-Trip Requests](/server/mrtr/) page.

docs/_client/ping.md

@@ -29,6 +29,20 @@ is not a Hash (matching the spec requirement that `result` be an object).
 Transport-level errors (for example, `MCP::Client::Stdio`'s `read_timeout:` firing)
 propagate as exceptions raised by the transport layer.
 
+## Answering Server Pings
+
+On handshake-lifecycle connections a server may ping the client the same way, and the client answers automatically with
+the empty result - no handler is needed. Over HTTP a ping reaches the client only on a stream that is already open
+(the SSE response of an in-flight POST, or the GET listening stream); the client never opens a stream just to receive pings.
+Over stdio, a ping that arrives while a response is awaited is answered inline; between requests it is answered when
+the next request starts reading. The answer is best effort: a pong that cannot be written (for example, over a broken pipe) is
+dropped rather than failing the request whose response is being read. Independently of pings, consider setting `read_timeout:`
+on `MCP::Client::Stdio`, since a server that never answers otherwise holds the read until the process exits.
+
+To answer pings yourself, register `transport.on_server_request("ping")` on `MCP::Client::HTTP`; it replaces
+the automatic answer and, like any handler registered there, opens the standalone GET listening stream on `connect`,
+as described on the [Transports](/client/transports/#server-to-client-requests-elicitation) page.
+
 ## Server Side
 
 How servers answer `ping` requests and ping the client themselves is documented on

docs/_client/transports.md

@@ -59,12 +59,27 @@ The stdio transport automatically handles:
 - Spawning the server process with `Open3.popen3`
 - MCP protocol initialization handshake (`initialize` request + `notifications/initialized`)
 - JSON-RPC 2.0 message framing over newline-delimited JSON
+- Answering server `ping` requests; see [Answering Server Pings](/client/ping/#answering-server-pings)
+
+{: .note }
+> `ping` is the only server-to-client request answered over stdio. A wire-level `elicitation/create`
+> or `sampling/createMessage` is ignored on this transport, so a server that sends one waits for an answer
+> that never comes; use Streamable HTTP for those, as described below. The SEP-2322 `input_required` route,
+> which is how the modern lifecycle asks for the same input, works on every transport, so `on_elicitation`
+> and `on_sampling` handlers still fire over stdio; see [Multi Round-Trip Requests](/client/mrtr/).
 
 ## HTTP Transport Layer
 
 Use the `MCP::Client::HTTP` transport to interact with MCP servers using simple HTTP requests.
 
-You'll need to add `faraday` as a dependency in order to use the HTTP transport layer. Add `event_stream_parser` as well if the server uses SSE (`text/event-stream`) responses:
+You'll need to add `faraday` as a dependency in order to use the HTTP transport layer, and `event_stream_parser`
+to read SSE (`text/event-stream`) responses.
+Whether a response is JSON or SSE is the server's choice, made for each response, and a client must accept both,
+so a client written for arbitrary servers needs both gems. This SDK's own server picks SSE by default and always
+does on the modern lifecycle, and the listening stream that `on_elicitation` and `on_sampling` open is SSE as well.
+`event_stream_parser` is loaded on the first SSE response, so it can be left out only against a server known to
+answer with JSON alone, such as this SDK's server in [JSON response mode](/server/transports/#json-response-mode)
+serving handshake-lifecycle clients, and only while no listening stream is opened:
 
 ```ruby
 gem "mcp"
@@ -166,7 +181,7 @@ a JSON-RPC `-32601` (method not found) error. To handle methods other than `elic
 
 On a [modern](/client/lifecycle/) connection servers cannot send requests at all; the same
 registered handlers instead drive the requests embedded in `input_required` results,
-as documented on [Multi-Round-Trip Results](/client/multi-round-trip-results/).
+as documented on [Multi Round-Trip Requests](/client/mrtr/).
 
 ### Server-to-Client Requests (Sampling)
 
@@ -233,6 +248,15 @@ http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp") do |f
 end
 ```
 
+The block customizes only the connection to the MCP server. The connection the OAuth flow uses for its own requests is customized through
+the provider's `http_client_customizer:` keyword instead; see [Customizing the OAuth HTTP Client](/client/authorization/#customizing-the-oauth-http-client).
+
+{: .note }
+> Answers to server-to-client requests (a pong, an elicitation result) are POSTed from inside
+> the SSE streaming callback of another response, re-entering the connection on the same thread.
+> The default Net::HTTP adapter opens a connection per request, which makes this safe; an adapter
+> with persistent connections must tolerate that re-entry.
+
 ## Custom Transports
 
 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:

docs/_extensions/capability-extensions.md

@@ -23,7 +23,7 @@ server = MCP::Server.new(name: "my_server", capabilities: capabilities)
 The declared extensions appear in the `initialize` result's `capabilities.extensions`. Extensions the client declared during `initialize` are
 readable via `server.client_capabilities[:extensions]` (or `session.client_capabilities[:extensions]` for per-session transports).
 
-On the [modern lifecycle](/server/discovery/#the-stateless-modern-lifecycle), the same declarations appear in the `server/discover` result,
+On the [modern lifecycle](/server/discover/#the-stateless-modern-lifecycle), the same declarations appear in the `server/discover` result,
 and the client's extensions ride each request's `_meta` envelope instead of an `initialize` handshake.
 Inside a handler, `server_context.client_capabilities[:extensions]` reads the current request's declarations
 with envelope-first resolution, on either lifecycle.

docs/_includes/nav_footer_custom.html

@@ -0,0 +1,14 @@
+{%- comment -%}
+  Replaces the theme's "This site uses Just the Docs" attribution, shown at
+  the bottom of the sidebar on desktop and in the page footer on mobile.
+  _data/versions.yml exists only on the deployed gh-pages tree, where
+  bin/generate-gh-pages.sh generates it; without it (local previews of
+  the docs/ source) only the license sentence renders.
+{%- endcomment -%}
+{% if site.data.versions %}
+Documentation for <a href="https://rubygems.org/gems/mcp/versions/{{ site.data.versions | first }}">mcp {{ site.data.versions | first }}</a>,
+licensed <a href="https://creativecommons.org/licenses/by/4.0/">CC-BY-4.0</a>.
+{% else %}
+Documentation licensed <a href="https://creativecommons.org/licenses/by/4.0/">CC-BY-4.0</a>.
+{% endif %}
+See <a href="https://github.com/modelcontextprotocol/ruby-sdk/blob/main/LICENSE">LICENSE</a> for the code.

docs/_preview/taint_shim.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Liquid 4.0.3 (pinned by github-pages) still calls the taint API that Ruby 3.2 removed.
+# Restore it as a no-op for the local docs preview only; `rake docs:preview` loads
+# this file via `RUBYOPT`, so nothing outside the preview process is affected.
+class Object
+  def tainted?
+    false
+  end
+
+  def taint
+    self
+  end
+
+  def untaint
+    self
+  end
+end

docs/_server/cancellation.md

@@ -20,7 +20,7 @@ is never cancellable per the spec.
 {: .note }
 > Cancellation by notification belongs to the handshake lifecycle, where the session correlates
 > `notifications/cancelled` with the in-flight request it targets. Requests of the
-> [modern lifecycle](/server/discovery/#the-stateless-modern-lifecycle) are sessionless single POST exchanges, so a separately
+> [modern lifecycle](/server/discover/#the-stateless-modern-lifecycle) are sessionless single POST exchanges, so a separately
 > POSTed cancel notification cannot reach them; a modern client abandons a request by closing
 > the connection instead.
 

docs/_server/completion.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Completion
+nav_order: 16
+redirect_from:
+  - /server/completions/
+---
+
+# Completion
+
+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: [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 handler receives a `params` hash with:
+
+- `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: { ... } }`)
+
+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.
+
+The server validates that the referenced prompt, resource, or resource template is registered before calling the handler.
+Requests for unknown references return an error.