223 changed files with 3053 additions and 52610 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@ -4,12 +4,10 @@ on: [push, pull_request]
 jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    strategy:
      matrix:
        entry:
-          - { ruby: '2.7.0', allowed-failure: false } # Minimum supported Ruby version.
+          - { ruby: '2.7', allowed-failure: false }
          - { ruby: '3.0', allowed-failure: false }
          - { ruby: '3.1', allowed-failure: false }
          - { ruby: '3.2', allowed-failure: false }
@ -19,7 +17,7 @@ jobs:
          - { ruby: 'head', allowed-failure: true }
    name: Test Ruby ${{ matrix.entry.ruby }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: ${{ matrix.entry.ruby }}
@ -29,11 +27,9 @@ jobs:
  rubocop:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    name: RuboCop
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 4.0 # Specify the latest supported Ruby version.
@ -42,11 +38,9 @@ jobs:
  yard:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    name: YARD Documentation
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 4.0 # Specify the latest supported Ruby version.
--- a/.github/workflows/conformance.yml
+++ b/.github/workflows/conformance.yml
@ -1,29 +0,0 @@
 name: Conformance Tests
 on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
 concurrency:
  group: conformance-${{ github.ref }}-${{ github.event_name == 'push' && github.sha || '' }}
  cancel-in-progress: true
 permissions:
  contents: read
 jobs:
  server-conformance:
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - uses: actions/checkout@v7
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '4.0' # Specify the latest supported Ruby version.
          bundler-cache: true
      - uses: actions/setup-node@v7
        with:
          node-version: '24' # Specify the latest Node.js version.
      - run: bundle exec rake conformance:test
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@ -16,7 +16,7 @@ jobs:
      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
      contents: write # IMPORTANT: this permission is required for `rake release` to push the release tag
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
@ -34,7 +34,7 @@ jobs:
      contents: write
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Fetch all history for all branches and tags
--- a/.gitignore
+++ b/.gitignore
@ -1,5 +1,4 @@
 .ruby-version
 /*.gem
 /.bundle/
 /.yardoc
 /_yardoc/
@ -9,7 +8,3 @@
 /spec/reports/
 /tmp/
 Gemfile.lock
 docs/_site/
 docs/.jekyll-cache/
 docs/.jekyll-metadata
 docs/_data/versions.yml
--- a/.rubocop.yml
+++ b/.rubocop.yml
@ -7,17 +7,9 @@ plugins:
 AllCops:
  TargetRubyVersion: 2.7
  SuggestExtensions: false
 Gemspec/DevelopmentDependencies:
  Enabled: true
 Lint/IncompatibleIoSelectWithFiberScheduler:
  Enabled: true
 Minitest/LiteralAsActualArgument:
  Enabled: true
 Naming/MethodName:
  AllowedPatterns:
    - '\Atest_'
--- a/AGENTS.md
+++ b/AGENTS.md
@ -15,9 +15,7 @@ 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 linting, tests, and the conformance suite (default task)
+- `rake` - Run tests and linting (default task)
 - `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
@ -34,15 +32,6 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
 - Use frozen string literals
 - Follow Ruby community conventions
 - Keep dependencies minimal
 - Use lowercase HTTP response header names (e.g. `mcp-session-id`); the Rack 3 SPEC requires this, and the MCP spec's `Mcp-Session-Id` casing is prose convention only
 ## Documentation
 - User-facing documentation lives in `docs/`, one page per topic, published at https://ruby.sdk.modelcontextprotocol.io (deploys only when a release is published)
 - Pages live in the `docs/_server/`, `docs/_client/`, and `docs/_extensions/` collections
 - Keep README.md slim: quick start and pointers only; document features on the relevant docs page
 - Internal links are absolute and extensionless (e.g. `/server/tools/`); front matter is followed by a blank line before the h1
 - Callout tiers: `.note` (supplementary), `.important` (spec constraints), `.warning` (deprecated features)
 ## Commit message conventions
@ -67,18 +56,12 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
 **MCP::Server** (`lib/mcp/server.rb`):
- Main server class handling JSON-RPC requests and holding shared configuration (tools, prompts, resources, handlers, capabilities)
+- Main server class handling JSON-RPC requests
 - Implements MCP protocol methods: initialize, ping, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read
 - Supports custom method registration via `define_custom_method`
 - Handles instrumentation, exception reporting, and notifications
 - Uses JsonRpcHandler for request processing
 **MCP::ServerSession** (`lib/mcp/server_session.rb`):
 - Per-connection state: client info, logging level
 - Created by the transport layer for each client connection
 - Delegates request handling to the shared `Server`
 **MCP::Client** (`lib/mcp/client.rb`):
 - Client interface for communicating with MCP servers
@ -112,14 +95,6 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
 - Protocol version 2025-03-26+ supports tool annotations (destructive_hint, idempotent_hint, etc.)
 - Validation is configurable via `configuration.validate_tool_call_arguments`
 **Session Architecture**:
 - `Server` holds shared configuration (tools, prompts, resources, handlers)
 - `ServerSession` holds per-connection state (client info, logging level)
 - Both `StdioTransport` and `StreamableHTTPTransport` create a `ServerSession` per connection, making the session model transparent across transports
 - Session-scoped notifications (`notify_progress`, `notify_log_message`) are sent only to the originating client via `ServerSession`
 - Server-wide notifications (`notify_tools_list_changed`, etc.) broadcast to all sessions via `Server`
 **Context Passing**:
 - `server_context` hash passed through tool/prompt calls for request-specific data
@ -127,6 +102,6 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
 ### Integration patterns
- **Rails/Rack apps**: Mount `StreamableHTTPTransport` as a Rack app (e.g., `mount transport => "/mcp"`)
+- **Rails controllers**: Use `server.handle_json(request.body.read)` for HTTP endpoints
 - **Command-line tools**: Use `StdioTransport.new(server).open` for CLI applications
- **HTTP services**: Use `StreamableHTTPTransport` for web-based servers
+- **HTTP services**: Use `StreamableHttpTransport` for web-based servers
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -7,475 +7,6 @@ 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,
 and README.md keeps the quick start. Two entries under "Changed" reject traffic that earlier releases accepted
 and ship in a minor release under the exceptions described in [VERSIONING.md](VERSIONING.md).
 ### Added
 - Add a `resources_list_handler` for context-dependent resource lists (#509)
 - Pass a handler-returned `_meta` through the subscribe result (#510)
 ### Changed
 - Bound OAuth response bodies in the client (#520)
 - Reject duplicate in-flight JSON-RPC request ids (#521)
 - Move the documentation from README.md to the documentation site (#523)
 ## [1.2.0] - 2026-08-15
 This release completes the SEP-2575 stateless lifecycle of the 2026-07-28 specification, together with
 the SEP-2322, SEP-2549, and SEP-2243 features that revision builds on. Several entries under "Changed"
 are incompatible with 1.1.0 and ship in a minor release under the spec-conformance and security exceptions
 described in [VERSIONING.md](VERSIONING.md).
 ### Added
 - Handle the SEP-2575 modern request envelope in the server core (#475)
 - Serve both lifecycle eras over stdio with an era lock per SEP-2575 (#478)
 - Serve the sessionless modern path over Streamable HTTP per SEP-2575 (#479)
 - Finalize `server/discover` and add client modern lifecycle support per SEP-2575 (#480)
 - Let handlers return multi round-trip `input_required` results per SEP-2322 (#481)
 - Add `MCP::Elicitation::EnumSchema` builders per SEP-1330 (#482)
 - Stamp the required `resultType` on modern results per SEP-2322 (#487)
 - Enforce the modern lifecycle admission rules per SEP-2575 (#489)
 - Stream modern request notifications and honor the envelope `logLevel` per SEP-2575 (#490)
 - Expose the user-defined `server_context` in instrumentation data (#493)
 - Serve the `subscriptions/listen` notification stream per SEP-2575 (#495)
 - Add opt-in `requestState` sealing via `MCP::Server::RequestStateSecurity` (#496)
 - Mirror `x-mcp-header` tool parameters into `Mcp-Param-*` headers per SEP-2243 (#498)
 - Stamp the required cache hints on modern cacheable results per SEP-2549 (#499)
 - Drive multi round-trip `input_required` results on the client per SEP-2322 (#500)
 - Fulfill `input_required` results on the legacy wire per SEP-2322 (#501)
 ### Changed
 - Align modern envelope validation with the finalized specification (#491)
 - Require the `Mcp-Method` header on the modern path (#492)
 - Bound server-to-client requests with a timeout (#502)
 - Refuse server-to-client requests in the modern lifecycle per SEP-2575 (#503)
 - Bound the total wait across SSE reconnection attempts (#504)
 - Bound automatic pagination in the MCP client (#505)
 - Reject modern-removed methods before the connection era locks (#511)
 - Stop negotiating modern protocol versions through the `initialize` handshake (#516)
 ### Deprecated
 - Warn on modern client connects that declare the Roots or Sampling capabilities deprecated per SEP-2577 (#406, #516)
 ### Fixed
 - Stop leaking exception messages to clients via JSON-RPC error data (#486)
 - Return Invalid Params for unknown prompts and missing prompt arguments (#517)
 - Restrict OAuth discovery to same-origin metadata URLs and refuse private-network destinations
 ## [1.1.0] - 2026-08-01
 ### Added
 - Support 2026-07-28 as the Latest Protocol Version (#476)
 - Expose server tool annotations on MCP::Client::Tool (#445)
 ### Fixed
 - Preserve explicit tool response content (#469)
 ## [1.0.0] - 2026-07-24
 First stable release. The public API is now stable: breaking changes ship only in major releases,
 apart from the narrow exceptions documented in [VERSIONING.md](VERSIONING.md).
 ### Added
 - Add `ROADMAP.md` outlining the path toward SEP-1730 (#465)
 - Add `VERSIONING.md` documenting the versioning and breaking-change policy (#466)
 ## [0.25.0] - 2026-07-18
 ### Added
 - Support SEP-990 Cross-App Access via ID-JAG and the `jwt-bearer` grant (#454)
 - Support client-side sampling via `MCP::Client#on_sampling` (#458)
 ### Fixed
 - Reject notifications carrying an unknown or expired session (#455)
 - Handle an `initialize` request sent without an ID (#456)
 - Bound client-side message buffering in the HTTP transport (#459)
 - Lowercase response header names in `StreamableHTTPTransport` (#460)
 ## [0.24.0] - 2026-07-12
 ### Added
 - Support SSE reconnection per SEP-1699 in the HTTP client transport (#426)
 - Validate the RFC 9207 `iss` authorization response parameter per SEP-2468 (#431)
 - Support `private_key_jwt` client authentication for the `client_credentials` grant (#432)
 - Recognize multi round-trip `input_required` results per SEP-2322 (#433)
 - Add opt-in `ttlMs` / `cacheScope` cache hints to List and Read results per SEP-2549 (#436)
 - Add `server/discover` and stateless lifecycle error codes per SEP-2575 (#438)
 - Associate server-to-client requests with the originating client request per SEP-2260 (#440)
 - Add server-side MCP Apps helpers per SEP-1865 (#441)
 - Support client-side elicitation with SEP-1034 schema defaults (#443)
 - Support class-based Resource and ResourceTemplate definitions (#447)
 ### Changed
 - Bind stored client credentials to the authorization server issuer per SEP-2352 (#439)
 ### Fixed
 - Handle non-object JSON-RPC messages without raising (#448)
 - Perform SSE stream writes outside the session mutex (#449)
 - Validate required params for `initialize` and `resources/subscribe` (#451)
 ## [0.23.0] - 2026-07-07
 ### Added
 - Add a session-ownership hook to `StreamableHTTPTransport`
 ### Changed
 - Require calling `MCP::Client#connect` before sending requests on stdio transport (#427)
 ### Deprecated
 - Annotate Roots, Sampling, and Logging APIs as deprecated per SEP-2577 (#429)
 ### Fixed
 - Fix an incorrect `result: null` response to an id-bearing notification message (#435)
 - Validate `Host` and `Origin` headers to prevent DNS rebinding per MCP 2025-11-25
 - Bound stateful session retention to prevent an initialize-flood DoS
 - Bound stdio frame reads with `max_line_bytes`
 - Bound request body and frame reads to prevent memory-exhaustion DoS
 ## [0.22.0] - 2026-06-27
 ### Added
 - Add `audience` role validation for `MCP::Annotations` per MCP specification (#422)
 - Send SEP-2243 `Mcp-Method` and `Mcp-Name` headers per MCP specification (#423)
 - Support client-side `notifications/cancelled` per MCP specification (#425)
 ### Changed
 - Conform Tool Schemas to JSON Schema 2020-12 per SEP-2106 (#417)
 ### Fixed
 - Fix a `SyntaxError` on Ruby 2.7.0 caused by arguments forwarding syntax (#419)
 ## [0.21.0] - 2026-06-20
 ### Added
 - Support capability extensions per SEP-2133 (#405)
 - Add range validation for `MCP::Annotations#priority` per MCP specification (#410)
 - Isolate stateless requests in ephemeral sessions per SEP-2567 (#415)
 ### Changed
 - Set OIDC `application_type` on Dynamic Client Registration per SEP-837 (#408)
 - Fall back to legacy 2025-03-26 OAuth discovery for servers without PRM (#414)
 ## [0.20.0] - 2026-06-14
 ### Added
 - Support W3C Trace Context Propagation via `_meta` per SEP-414 (#397)
 - Support OAuth `client_credentials` grant in OAuth client (#399)
 - Add `annotations` field to `MCP::Resource` and `MCP::ResourceTemplate` per MCP specification (#403)
 ### Changed
 - Re-run OAuth flow on 403 `insufficient_scope` (step-up) (#368)
 - Speed up `Tool::Schema` validation by 5x to 100x (#369)
 - Use JSON-RPC error envelope for `StreamableHTTPTransport` errors (#371)
 - Pin RFC 8414 default well-known suffix per SEP-2351 (#395)
 - Default missing `MCP-Protocol-Version` to `2025-03-26` in `StreamableHTTPTransport` (#392)
 ### Fixed
 - Preserve the request ID in invalid request error responses (#400)
 - Standardize Resource Not Found errors on -32602 with URI data per SEP-2164 (#402)
 ## [0.19.0] - 2026-06-13
 ### Added
 - Support Client ID Metadata Documents in OAuth client (#361)
 - Request `offline_access` scope when supported (#365)
 - Add `size` field to `MCP::Resource` per MCP specification (#393)
 ## [0.18.0] - 2026-05-30
 ### Added
 - Support server-to-client `ping` per MCP specification (#358)
 ### Changed
 - Warn on implicit stdio initialization (#338)
 - Cache `Tool::Schema` validation to avoid re-validating identical schemas (#363)
 ### Fixed
 - Fix case-sensitive `Accept` header comparison (#359)
 ## [0.17.0] - 2026-05-19
 ### Added
 - Add OAuth 2.1 client support for MCP authorization flow (#353)
 ### Fixed
 - Validate `MCP-Protocol-Version` header in `StreamableHTTPTransport` (#347)
 - Reject duplicate `initialize` requests (#350)
 - Reject non-Hash JSON-RPC bodies in `StreamableHTTPTransport` (#354)
 ## [0.16.0] - 2026-05-14
 ### Added
 - Add opt-in tool output validation (#344)
 ### Changed
 - Advertise JSON Schema 2020-12 dialect on emitted tool schemas (#342)
 ### Fixed
 - Preserve client tool output schemas (#343)
 - Fix missing `output_schema` argument in `define_tool` API (#301)
 ## [0.15.0] - 2026-05-05
 ### Added
 - Support `notifications/cancelled` per MCP specification (#332)
 - Add client-level `connect` for initialize handshake (#327)
 - Add client-level `connect` handshake to stdio transport (#336)
 ### Changed
 - Return tool argument validation failures as tool execution errors (#333)
 ### Removed
 - Remove obsolete `MCP::Transports` module (#331)
 ## [0.14.0] - 2026-04-24
 ### Added
 - Support pagination per MCP specification (#320)
 - Support resource subscriptions per MCP specification (#313)
 - Add `roots/list` and `notifications/roots/list_changed` support (#315)
 - Support JSON response mode for `StreamableHTTPTransport` (#328)
 - Add HTTP client close for explicit session termination (#326)
 - Track `Mcp-Session-Id` and protocol version in HTTP client (#325)
 - Support `ping` client API per MCP specification (#324)
 ### Fixed
 - Handle 202 Accepted response in HTTP client (#323)
 ### Changed
 - Parse SSE responses in HTTP client via `event_stream_parser` (#322)
 ## [0.13.0] - 2026-04-16
 ### Added
 - Make `StreamableHTTPTransport` a Rack application (#263)
 - Support `elicitation/create` per MCP specification (#312)
 - Add `around_request` hook for request instrumentation (#309)
 - Add `_meta` field to resource, content, and result classes (#310)
 ### Removed
 - Remove `Server#create_sampling_message` direct call (#311)
 ## [0.12.0] - 2026-04-11
 ### Added
 - Support customizing the Faraday client in `MCP::Client::HTTP` (#306)
 ### Changed
 - Auto-set `server.transport` in `Transport#initialize` (#305)
 ### Fixed
 - Validate Content-Type on POST requests (#304)
 ## [0.11.0] - 2026-04-06
 ### Added
 - Support `sampling/createMessage` per MCP specification (#282)
 - Support `completion/complete` per MCP specification (#289)
 ### Fixed
 - Support POST response SSE streams for server-to-client messages (#294)
 - Return protocol errors for invalid arguments and server errors (#285)
 - Fix client methods silently swallowing JSON-RPC error responses (#281)
 - Close streams outside mutex in session cleanup (#291)
 ## [0.10.0] - 2026-03-30
 ### Added
 - Session expiry controls for `StreamableHTTPTransport` via `session_idle_timeout:` option (#268)
 ### Changed
 - `ServerSession` for per-connection state (#275)
 ### Removed
 - Remove `Server#notify_progress` broadcast API (#276)
 - Remove undocumented handler override methods (#270)
 ### Fixed
 - Reject POST requests without session ID in stateful mode (#274)
 ## [0.9.2] - 2026-03-27
 ### Fixed
 - Use accessor method in `server_context_with_meta` instead of ivar (#273)
 - Reject duplicate SSE connections with 409 to prevent stream hijacking
 ## [0.9.1] - 2026-03-23
 ### Added
 - Allow `Client#call_tool` to accept a tool name (#266)
 ### Fixed
 - Return 404 for invalid session ID in `handle_delete` (#261)
 ## [0.9.0] - 2026-03-20
 ### Added
 - `MCP::Client::Stdio` transport (#262)
 - Progress notifications per MCP specification (#254)
 - Automatic `_meta` parameter extraction support (#172)
 - CORS and Accept wildcard support for browser-based MCP clients (#253)
 ### Changed
 - Use `autoload` to defer loading of unused subsystems (#255)
 - Reduce release package size (#239)
 ### Fixed
 - Return 404 for invalid session ID in `handle_regular_request` (#257)
 - Use mutex-protected `session_exists?` in `handle_regular_request` (#258)
 ## [0.8.0] - 2026-03-03
 ### Added
 - `Content::EmbeddedResource` class for embedded resource content type (#244)
 - `Content::Audio` class for audio content type (#243)
 - `$ref` support in `Tool::Schema` for protocol version 2025-11-25 (#242)
 - MCP conformance test suite (#248)
 ### Fixed
 - Handle `Errno::ECONNRESET` in SSE stream operations (#249)
 - Fix default handler return values to comply with MCP spec (#247)
 - Fix `Prompt#validate_arguments!` crash when arguments are `nil` (#246)
 - Return 202 Accepted for SSE responses per MCP spec (#245)
 - Fix `Content::Image#to_h` to return `mimeType` (camelCase) per MCP spec (#241)
 ## [0.7.1] - 2026-02-21
 ### Fixed
 - Fix `Resource::Contents#to_h` to use correct property names per MCP spec (#235)
 - Return JSON-RPC protocol errors for unknown tool calls (#231)
 - Fix `logging/setLevel` to return empty hash per MCP specification (#230)
 ## [0.7.0] - 2026-02-14
 ### Added
 - `logging` support (#103)
 - Protocol version negotiation to server initialization (#223)
 - Tool arguments to instrumentation data (#218)
 - Client info to instrumentation callback (#221)
 - `resource_templates` to `MCP::Client` (#225)
 ### Changed
 - Extract `MCP::Annotations` into a dedicated file (#224)
 ### Fixed
 - `Resource::Embedded` not setting `@resource` in `initialize` (#220)
 ## [0.6.0] - 2026-01-16
 ### Changed
@ -591,4 +122,4 @@ apart from the narrow exceptions documented in [VERSIONING.md](VERSIONING.md).
 ## [0.1.0] - 2025-05-30
-Initial release in collaboration with Shopify
+Initial release
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -1 +0,0 @@
@AGENTS.md
--- a/6
+++ b/6
@ -6,26 +6,22 @@ source "https://rubygems.org"
 gemspec
 # Specify development dependencies below
-gem "rubocop-minitest", ">= 0.39.0", require: false
+gem "rubocop-minitest", require: false
 gem "rubocop-rake", require: false
 gem "rubocop-shopify", ">= 2.18", require: false if RUBY_VERSION >= "3.1"
 gem "puma", ">= 5.0.0"
 gem "rack-cors"
 gem "rackup", ">= 2.1.0"
 gem "activesupport"
 # Fix io-console install error when Ruby 3.0.
 gem "debug" if RUBY_VERSION >= "3.1"
 # Avoid i18n 1.15.0, which breaks on Ruby 3.1 (ruby-i18n/i18n#735).
 gem "i18n", "!= 1.15.0"
 gem "rake", "~> 13.0"
 gem "sorbet-static-and-runtime" if RUBY_VERSION >= "3.0"
 gem "yard", "~> 0.9"
 gem "yard-sorbet", "~> 0.9" if RUBY_VERSION >= "3.1"
 group :test do
  gem "event_stream_parser", ">= 1.0"
  gem "faraday", ">= 2.0"
  gem "minitest", "~> 5.1", require: false
  gem "mocha"
--- a/README.md
+++ b/README.md
@ -2,21 +2,12 @@
 The official Ruby SDK for Model Context Protocol servers and clients.
 Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.
 ## Features
 - 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 requests, notifications, progress, logging, cancellation, completions, and pagination
 ## Installation
 Add this line to your application's Gemfile:
 ```ruby
-gem "mcp"
+gem 'mcp'
 ```
 And then execute:
@ -33,14 +24,170 @@ $ gem install mcp
 You may need to add additional dependencies depending on which features you wish to access.
-## Quick Start
+## Building an MCP Server
-The following minimal programs show both sides of the protocol: a server that exposes a single tool,
+The `MCP::Server` class is the core component that handles JSON-RPC requests and responses.
-and a client that spawns such a server and drives it over stdio.
+It implements the Model Context Protocol specification, handling model context requests and responses.
-### MCP Server
+### Key Features
-A minimal server defines a tool and serves it over the stdio transport:
+- Implements JSON-RPC 2.0 message handling
 - Supports protocol initialization and capability negotiation
 - Manages tool registration and invocation
 - Supports prompt registration and execution
 - Supports resource registration and retrieval
 - Supports stdio & Streamable HTTP (including SSE) transports
 - Supports notifications for list changes (tools, prompts, resources)
 ### Supported Methods
 - `initialize` - Initializes the protocol and returns server capabilities
 - `ping` - Simple health check
 - `tools/list` - Lists all registered tools and their schemas
 - `tools/call` - Invokes a specific tool with provided arguments
 - `prompts/list` - Lists all registered prompts and their schemas
 - `prompts/get` - Retrieves a specific prompt by name
 - `resources/list` - Lists all registered resources and their schemas
 - `resources/read` - Retrieves a specific resource by name
 - `resources/templates/list` - Lists all registered resource templates and their schemas
 ### 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
 ```
 **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
 **Usage Example:**
 ```ruby
 # Client request
 {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "add",
  "params": { "a": 5, "b": 3 }
 }
 # 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
 ### Notifications
 The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
 #### Notification Methods
 The server provides three notification methods:
 - `notify_tools_list_changed` - Send a notification when the tools list changes
 - `notify_prompts_list_changed` - Send a notification when the prompts list changes
 - `notify_resources_list_changed` - Send a notification when the resources list changes
 #### Notification Format
 Notifications follow the JSON-RPC 2.0 specification and use these method names:
 - `notifications/tools/list_changed`
 - `notifications/prompts/list_changed`
 - `notifications/resources/list_changed`
 #### 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 = 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
 ```
 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)
 ```
 ### Unsupported Features (to be implemented in future versions)
 - Log Level
 - Resource subscriptions
 - Completions
 - Elicitation
 ### Usage
 #### Rails Controller
 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.
 You can use the `Server#handle_json` method to handle requests.
 ```ruby
 class ApplicationController < ActionController::Base
  def index
    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 },
    )
    render(json: server.handle_json(request.body.read))
  end
 end
 ```
 #### Stdio Transport
 If you want to build a local command-line application, you can use the stdio transport:
 ```ruby
 require "mcp"
@ -76,64 +223,752 @@ transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open
 ```
-Save the script as `server.rb`, run it, and send JSON-RPC requests via stdin:
+You can run this script and then type in requests to the server at the command line.
 ```console
-$ ruby server.rb
+$ 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"}}}
 ```
-The same server can also run over Streamable HTTP, including mounted inside a Rails application;
+### Configuration
 see [Server Transports](https://ruby.sdk.modelcontextprotocol.io/server/transports/).
-### MCP Client
+The gem can be configured using the `MCP.configure` block:
 A minimal client spawns a stdio server as a subprocess, connects, and lists and calls its tools:
 ```ruby
-stdio_transport = MCP::Client::Stdio.new(
+MCP.configure do |config|
-  command: "bundle",
+  config.exception_reporter = ->(exception, server_context) {
-  args: ["exec", "ruby", "path/to/server.rb"],
+    # Your exception reporting logic here
-  env: { "API_KEY" => "my_secret_key" },
+    # For example with Bugsnag:
-  read_timeout: 30
+    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
 ```
 or by creating an explicit configuration and passing it into the server.
 This is useful for systems where an application hosts more than one MCP server but
 they might require different instrumentation callbacks.
 ```ruby
 configuration = MCP::Configuration.new
 configuration.exception_reporter = ->(exception, server_context) {
  # Your exception reporting logic here
  # For example with Bugsnag:
  Bugsnag.notify(exception) do |report|
    report.add_metadata(:model_context_protocol, server_context)
  end
 }
 configuration.instrumentation_callback = ->(data) {
  puts "Got instrumentation data #{data.inspect}"
 }
 server = MCP::Server.new(
  # ... all other options
  configuration:,
 )
-client = MCP::Client.new(transport: stdio_transport)
+```
-# Perform the MCP initialization handshake before sending any requests.
+### Server Context and Configuration Block Data
 client.connect
-# List available tools.
+#### `server_context`
-tools = client.tools
+
-tools.each do |tool|
+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.
-  puts "Tool: #{tool.name} - #{tool.description}"
+
 **Type:**
 ```ruby
 server_context: { [String, Symbol] => Any }
 ```
 **Example:**
 ```ruby
 server = MCP::Server.new(
  name: "my_server",
  server_context: { user_id: current_user.id, request_id: request.uuid }
 )
 ```
 This hash is then passed as the `server_context` argument to tool and prompt calls, and is included in exception and instrumentation callbacks.
 #### Configuration Block Data
 ##### 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
 exception_reporter = ->(exception, server_context) { ... }
 ```
 ##### 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
 - `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
 **Type:**
 ```ruby
 instrumentation_callback = ->(data) { ... }
 # where data is a Hash with keys as described above
 ```
 **Example:**
 ```ruby
 config.instrumentation_callback = ->(data) {
  puts "Instrumentation: #{data.inspect}"
 }
 ```
 ### Server Protocol Version
 The server's protocol version can be overridden using the `protocol_version` keyword argument:
 ```ruby
 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).
 This will make all new server instances use the specified protocol version instead of the default version. The protocol version can be reset to the default by setting it to `nil`:
 ```ruby
 MCP::Configuration.new(protocol_version: nil)
 ```
 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.
 ### Exception Reporting
 The exception reporter receives two arguments:
 - `exception`: The Ruby exception object that was raised
 - `server_context`: A hash containing contextual information about where the error occurred
 The server_context hash includes:
 - For tool calls: `{ tool_name: "name", arguments: { ... } }`
 - For general request handling: `{ request: { ... } }`
 When an exception occurs:
 1. The exception is reported via the configured reporter
 2. For tool calls, a generic error response is returned to the client: `{ error: "Internal error occurred", isError: true }`
 3. For other requests, the exception is re-raised after reporting
 If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
 ### Tools
 MCP spec includes [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) which provide functionality to LLM apps.
 This gem provides a `MCP::Tool` class that can be used to create tools in three ways:
 1. As a class definition:
 ```ruby
 class MyTool < MCP::Tool
  title "My Tool"
  description "This tool performs specific functionality..."
  input_schema(
    properties: {
      message: { type: "string" },
    },
    required: ["message"]
  )
  output_schema(
    properties: {
      result: { type: "string" },
      success: { type: "boolean" },
      timestamp: { type: "string", format: "date-time" }
    },
    required: ["result", "success", "timestamp"]
  )
  annotations(
    read_only_hint: true,
    destructive_hint: false,
    idempotent_hint: true,
    open_world_hint: false,
    title: "My Tool"
  )
  def self.call(message:, server_context:)
    MCP::Tool::Response.new([{ type: "text", text: "OK" }])
  end
 end
-# Call a specific tool.
+tool = MyTool
 ```
 2. By using the `MCP::Tool.define` method with a block:
 ```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
 ```
 3. By using the `MCP::Server#define_tool` method with a block:
 ```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"
  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"])
      )
    ]
  )
 end
 ```
 The server_context parameter is the server_context passed into the server and can be used to pass per request information,
 e.g. around authentication state or user preferences.
 ### Key Components
 - `MCP::Prompt::Argument` - Defines input parameters for the prompt template with name, title, description, and required flag
 - `MCP::Prompt::Message` - Represents a message in the conversation with a role and content
 - `MCP::Prompt::Result` - The output of a prompt template containing description and messages
 - `MCP::Content::Text` - Text content for messages
 ### Usage
 Register prompts with the MCP server:
 ```ruby
 server = MCP::Server.new(
  name: "my_server",
  prompts: [MyPrompt],
  server_context: { user_id: current_user.id },
 )
 ```
 The server will handle prompt listing and execution through the MCP protocol methods:
 - `prompts/list` - Lists all registered prompts and their schemas
 - `prompts/get` - Retrieves and executes a specific prompt with arguments
 ### Instrumentation
 The server allows registering a callback to receive information about instrumentation.
 To register a handler pass a proc/lambda to as `instrumentation_callback` into the server constructor.
 ```ruby
 MCP.configure do |config|
  config.instrumentation_callback = ->(data) {
    puts "Got instrumentation data #{data.inspect}"
  }
 end
 ```
 The data contains the following keys:
 - `method`: the method called, e.g. `ping`, `tools/list`, `tools/call` etc
 - `tool_name`: the name of the tool called
 - `prompt_name`: the name of the prompt called
 - `resource_uri`: the uri of the resource called
 - `error`: if looking up tools/prompts etc failed, e.g. `tool_not_found`
 - `duration`: the duration of the call in seconds
 `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
 ### Resources
 MCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).
 ### Reading Resources
 The `MCP::Resource` class provides a way to register resources with the server.
 ```ruby
 resource = MCP::Resource.new(
  uri: "https://example.com/my_resource",
  name: "my-resource",
  title: "My Resource",
  description: "Lorem ipsum dolor sit amet",
  mime_type: "text/html",
 )
 server = MCP::Server.new(
  name: "my_server",
  resources: [resource],
 )
 ```
 The server must register a handler for the `resources/read` method to retrieve a resource dynamically.
 ```ruby
 server.resources_read_handler do |params|
  [{
    uri: params[:uri],
    mimeType: "text/plain",
    text: "Hello from example resource! URI: #{params[:uri]}"
  }]
 end
 ```
 otherwise `resources/read` requests will be a no-op.
 ### Resource Templates
 The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
 ```ruby
 resource_template = MCP::ResourceTemplate.new(
  uri_template: "https://example.com/my_resource_template",
  name: "my-resource-template",
  title: "My Resource Template",
  description: "Lorem ipsum dolor sit amet",
  mime_type: "text/html",
 )
 server = MCP::Server.new(
  name: "my_server",
  resource_templates: [resource_template],
 )
 ```
 ## Building an MCP Client
 The `MCP::Client` class provides an interface for interacting with MCP servers.
 This class supports:
 - Tool listing via the `tools/list` method (`MCP::Client#tools`)
 - Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)
 - Resource listing via the `resources/list` method (`MCP::Client#resources`)
 - Resource reading via the `resources/read` method (`MCP::Client#read_resources`)
 - Prompt listing via the `prompts/list` method (`MCP::Client#prompts`)
 - Prompt retrieval via the `prompts/get` method (`MCP::Client#get_prompt`)
 - Automatic JSON-RPC 2.0 message formatting
 - UUID request ID generation
 Clients are initialized with a transport layer instance that handles the low-level communication mechanics.
 Authorization is handled by the transport layer.
 ## 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:
 ```ruby
 class CustomTransport
  # Sends a JSON-RPC request to the server and returns the raw response.
  #
  # @param request [Hash] A complete JSON-RPC request object.
  #     https://www.jsonrpc.org/specification#request_object
  # @return [Hash] A hash modeling a JSON-RPC response object.
  #     https://www.jsonrpc.org/specification#response_object
  def send_request(request:)
    # Your transport-specific logic here
    # - HTTP: POST to endpoint with JSON body
    # - WebSocket: Send message over WebSocket
    # - stdio: Write to stdout, read from stdin
    # - etc.
  end
 end
 ```
 ### 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:
 ```ruby
 gem 'mcp'
 gem 'faraday', '>= 2.0'
 ```
 Example usage:
 ```ruby
 http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp")
 client = MCP::Client.new(transport: http_transport)
 # List available tools
 tools = client.tools
 tools.each do |tool|
  puts <<~TOOL_INFORMATION
    Tool: #{tool.name}
    Description: #{tool.description}
    Input Schema: #{tool.input_schema}
  TOOL_INFORMATION
 end
 # Call a specific tool
 response = client.call_tool(
  tool: tools.first,
  arguments: { message: "Hello, world!" }
 )
 # Close the transport when done.
 stdio_transport.close
 ```
-The same client can connect to Streamable HTTP servers with `MCP::Client::HTTP`;
+#### HTTP Authorization
 see [Client Transports](https://ruby.sdk.modelcontextprotocol.io/client/transports/).
-## Examples
+By default, the HTTP transport layer provides no authentication to the server, but you can provide custom headers if you need authentication. For example, to use Bearer token authentication:
-Runnable examples are available in [`examples/`](https://github.com/modelcontextprotocol/ruby-sdk/tree/main/examples),
+```ruby
-including a complete Rails application in [`examples/rails`](https://github.com/modelcontextprotocol/ruby-sdk/tree/main/examples/rails).
+http_transport = MCP::Client::HTTP.new(
  url: "https://api.example.com/mcp",
  headers: {
    "Authorization" => "Bearer my_token"
  }
 )
 client = MCP::Client.new(transport: http_transport)
 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.
 ### Tool Objects
 The client provides a wrapper class for tools returned by the server:
 - `MCP::Client::Tool` - Represents a single tool with its metadata
 This class provides easy access to tool properties like name, description, input schema, and output schema.
 ## Documentation
 - [SDK guides](https://ruby.sdk.modelcontextprotocol.io)
 - [SDK API documentation](https://rubydoc.info/gems/mcp)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 ## License
 This project is licensed under the Apache License 2.0 for new contributions, with existing code under MIT. See the [LICENSE](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/LICENSE) file for details.
--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -1,51 +0,0 @@
 # Roadmap
 This roadmap outlines the MCP Ruby SDK's path toward SEP-1730 Tier 1.
 It is a living document and will evolve as the SDK matures.
 ## Current Status
 The SDK implements the 2025-06-18, 2025-11-25, and 2026-07-28 spec revisions, and passes all scored server
 and client conformance scenarios for each revision's requirement set.
 Optional protocol extensions (such as DPoP, workload identity federation, and the tasks extension)
 are not yet implemented; SEP-1730 does not require extensions for any tier.
 ## API Stability
 The 1.0.0 release marked the public API as stable: breaking changes ship only in major releases,
 apart from the narrow exceptions documented in [VERSIONING.md](VERSIONING.md),
 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 supported throughout 1.x: on the legacy lifecycle they work unchanged
 (the deprecations do not apply there), and the 2026-07-28 lifecycle carries them through its own mechanisms:
 roots-shaped and sampling-shaped input requests embedded in `InputRequiredResult` responses
 (the SEP-2322 multi round-trip requests pattern) and per-request log delivery through the envelope's `logLevel`.
 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
 The SDK maintains a 100% conformance pass rate as new scenarios are added to the conformance suite.
 Legacy SSE transport (2024-11-05) is intentionally out of scope; the SDK provides modern Streamable HTTP only.
 ## Documentation
 Reference documentation covers all non-experimental features with examples.
 ## Tracking New Spec Revisions
 The SDK aims to support each new MCP specification revision, with the implementation timeline agreed per
 release based on feature complexity.
 The 2026-07-28 revision shipped during 1.x: the server serves both lifecycle eras side by side,
 so the SEP-2575 stateless lifecycle (including `server/discover` and `subscriptions/listen`),
 SEP-2322 multi round-trip requests, SEP-2549 cache hints, and SEP-2243 custom headers are available alongside
 the legacy handshake. The few incompatible adjustments the revision required shipped in
 a minor release under the spec-conformance and security exceptions described in [VERSIONING.md](VERSIONING.md).
 Removing legacy-era support is reserved for a future major release.
 The tasks extension (SEP-2663) remains planned ([#391](https://github.com/modelcontextprotocol/ruby-sdk/issues/391)).
--- a/88
+++ b/88
@ -14,90 +14,4 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
-task default: [:rubocop, :test, "conformance:test"]
+task default: [:test, :rubocop]
 namespace :conformance do
  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"
    require_relative "conformance/client_runner"
    options = {}
    options[:port] = Integer(ENV["PORT"]) if ENV["PORT"]
    options[:scenario] = ENV["SCENARIO"] if ENV["SCENARIO"]
    options[:spec_version] = ENV["SPEC_VERSION"] if ENV["SPEC_VERSION"]
    options[:verbose] = true if ENV["VERBOSE"]
    Conformance::ServerRunner.new(**options).run
    Conformance::ClientRunner.new(**options.reject { |key, _value| key == :port }).run
  end
  desc "List available conformance scenarios"
  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
  desc "Start the conformance server (PORT)"
  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)
  return true if system("which", "npx", out: File::NULL, err: File::NULL)
  warn("Skipping #{task_name}: npx is not installed. Install Node.js to run this task: https://nodejs.org/")
  false
 end
--- a/SECURITY.md
+++ b/SECURITY.md
@ -1,21 +0,0 @@
 # Security Policy
 Thank you for helping keep the Model Context Protocol and its ecosystem secure.
 ## Reporting Security Issues
 If you discover a security vulnerability in this repository, please report it through
 the [GitHub Security Advisory process](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
 for this repository.
 Please **do not** report security vulnerabilities through public GitHub issues, discussions,
 or pull requests.
 ## What to Include
 To help us triage and respond quickly, please include:
 - A description of the vulnerability
 - Steps to reproduce the issue
 - The potential impact
 - Any suggested fixes (optional)
--- a/VERSIONING.md
+++ b/VERSIONING.md
@ -1,56 +0,0 @@
 # Versioning Policy
 The MCP Ruby SDK follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 This document describes what each version component means for users of the `mcp` gem,
 what counts as a breaking change, and how breaking changes are communicated.
 ## Version Scheme
 Given a version number `MAJOR.MINOR.PATCH`:
 - **MAJOR** is incremented for incompatible changes to the public API.
 - **MINOR** is incremented for backwards-compatible new functionality.
 - **PATCH** is incremented for backwards-compatible bug fixes.
 ### Current 0.x Phase
 While the SDK is at version 0.x, the public API is not yet considered stable.
 Following SemVer conventions for initial development, minor releases (0.x -> 0.y) may contain breaking changes.
 All breaking changes are recorded in [CHANGELOG.md](CHANGELOG.md).
 ### After 1.0.0
 Once 1.0.0 is released, breaking changes will only ship in major releases, with the exceptions described below.
 ## What Counts as a Breaking Change
 A breaking change is any change that requires users to modify their code when upgrading, including:
 - Removing or renaming a public class, module, method, or constant
 - Changing a public method's signature in a way that rejects previously valid arguments
 - Changing documented behavior that users can reasonably depend on
 New functionality that is purely additive (new classes, new methods, new optional keyword arguments)
 is not a breaking change.
 ## Exceptions: Spec Compliance, Security, and Clear Defects
 Minor releases avoid incompatible changes as much as possible. However, the SDK's primary contract is
 conformance to the [MCP specification](https://modelcontextprotocol.io/specification/).
 Behavior that deviates from the specification is treated as a bug, even when users may have come to rely on it.
 Therefore, incompatible changes may be shipped in a minor release when they are required to:
 - Fix incorrect conformance to the MCP specification
 - Address a security vulnerability
 - Fix a clear defect, such as behavior that contradicts the documentation, a crash,
  or data corruption, where compatibility would mean preserving the defect
 When such a change ships, the release notes and CHANGELOG entry explicitly call out the incompatibility
 and describe how to migrate.
 ## How Breaking Changes Are Communicated
 - [CHANGELOG.md](CHANGELOG.md) records every release in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format;
  breaking changes appear under the "Changed" or "Removed" headings
 - [GitHub Releases](https://github.com/modelcontextprotocol/ruby-sdk/releases) mirror the changelog for each release
 - Where practical, deprecation warnings are added at least one minor release before removal
--- a/conformance/README.md
+++ b/conformance/README.md
@ -1,105 +0,0 @@
 # MCP Conformance Tests
 Validates the Ruby SDK's conformance to the MCP specification using [`@modelcontextprotocol/conformance`](https://github.com/modelcontextprotocol/conformance).
 ## Prerequisites
 - Node.js (for `npx`)
 - `bundle install` completed
 ## Running the Tests
 ### Run all scenarios
 ```bash
 bundle exec rake conformance:test
 ```
 Runs both server and client conformance tests in sequence. Server conformance starts the
 conformance server and tests it. Client conformance spawns test servers for each scenario
 and invokes `conformance/client.rb` against them. Scenarios listed in `expected_failures.yml`
 are allowed to fail without affecting the exit code.
 ### Environment variables
 | Variable       | Description                           | Default |
 |----------------|---------------------------------------|---------|
 | `PORT`         | Server port (server conformance only) | `9292`  |
 | `SCENARIO`     | Run a single scenario by name         | (all)   |
 | `SPEC_VERSION` | Filter scenarios by spec version      | (all)   |
 | `VERBOSE`      | Show raw JSON output when set         | (off)   |
 ```bash
 # Run a single server scenario
 bundle exec rake conformance:test SCENARIO=ping
 # Use a different port with verbose output
 bundle exec rake conformance:test PORT=3000 VERBOSE=1
 # Start the server on a specific port
 bundle exec rake conformance:server PORT=3000
 ```
 ### Start the server and test separately
 ```bash
 # Terminal 1: start the server
 bundle exec rake conformance:server
 # Terminal 2: run all scenarios
 npx @modelcontextprotocol/conformance@alpha server --url http://localhost:9292/mcp
 # Terminal 2: run a single scenario
 npx @modelcontextprotocol/conformance@alpha server --url http://localhost:9292/mcp --scenario ping
 ```
 Keeps the server alive between test runs, which avoids the startup overhead when iterating
 on a single scenario. Stop the server with Ctrl+C when done.
 ### List available scenarios
 ```bash
 bundle exec rake conformance:list
 ```
 Prints all scenario names that can be passed to `SCENARIO`.
 ## SDK Tier Report
 The [MCP SDK Tier system](https://modelcontextprotocol.io/community/sdk-tiers) requires SDK
 maintainers to self-assess and report results to the SDK Working Group via
 [modelcontextprotocol/modelcontextprotocol issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues).
 To generate a full tier assessment report, use the `/mcp-sdk-tier-audit` slash command from
 the [modelcontextprotocol/conformance](https://github.com/modelcontextprotocol/conformance)
 repository with the conformance server running:
 ```bash
 # Terminal 1 (this repository): start the 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
 ```
 The skill evaluates conformance pass rate, issue label taxonomy, triage metrics, documentation
 coverage, and policy compliance, then produces a markdown report suitable for tier advancement
 submissions.
 ## File Structure
 ```
 conformance/
  server.rb              # Conformance server (Rack + Puma, default port 9292)
  server_runner.rb       # Starts the server, runs npx conformance server, exits with result code
  client.rb              # Conformance client (invoked by npx conformance client)
  client_runner.rb       # Runs npx conformance client, exits with result code
  expected_failures.yml  # Baseline of known-failing scenarios (server and client)
  README.md              # This file
 ```
 ## Known Limitations
 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:test`.
--- a/conformance/client.rb
+++ b/conformance/client.rb
@ -1,306 +0,0 @@
 # frozen_string_literal: true
 # Conformance test client for the MCP Ruby SDK.
 # Invoked by the conformance runner:
 #   MCP_CONFORMANCE_SCENARIO=<scenario> bundle exec ruby conformance/client.rb <server-url>
 #
 # The server URL is passed as the last positional argument.
 # The scenario name is read from the MCP_CONFORMANCE_SCENARIO environment variable,
 # which is set automatically by the conformance test runner.
 require "faraday"
 require "json"
 require_relative "../lib/mcp"
 scenario = ENV["MCP_CONFORMANCE_SCENARIO"]
 server_url = ARGV.last
 unless scenario && server_url
  abort("Usage: MCP_CONFORMANCE_SCENARIO=<scenario> ruby conformance/client.rb <server-url>")
 end
 # URL the conformance harness expects to see as the OAuth `client_id` for the `auth/basic-cimd` scenario
 # when the AS advertises `client_id_metadata_document_supported`. The harness does not fetch the document,
 # only matches the value, so the URL does not need to resolve.
 CONFORMANCE_CIMD_URL = "https://conformance-test.local/client-metadata.json"
 # The conformance harness optionally injects scenario-specific data via
 # the `MCP_CONFORMANCE_CONTEXT` environment variable as a JSON document. The shape is
 # defined by the harness, not the MCP spec, and has varied between versions:
 #
 # - Newer (`@modelcontextprotocol/conformance` >= 0.x): scenario fields are
 #   spread at the top level alongside `name`, e.g.
 #   `{"name":"auth/pre-registration","client_id":"...","client_secret":"..."}`.
 # - Older: a nested `context` object: `{"name":"...","context":{...}}`.
 #
 # Both shapes are accepted so the client conforms to whichever harness version
 # the developer has on hand.
 def conformance_context
  raw = ENV["MCP_CONFORMANCE_CONTEXT"]
  return {} if raw.nil? || raw.empty?
  parsed = JSON.parse(raw)
  return {} unless parsed.is_a?(Hash)
  if parsed["context"].is_a?(Hash)
    parsed["context"]
  else
    parsed.reject { |key, _| key == "name" }
  end
 rescue JSON::ParserError
  {}
 end
 # Saves the pre-registered `client_id` / `client_secret` the harness injects
 # via context (used by pre-registration and client_credentials scenarios).
 def storage_for(context)
  storage = MCP::Client::OAuth::InMemoryStorage.new
  if context["client_id"]
    storage.save_client_information(
      "client_id" => context["client_id"],
      "client_secret" => context["client_secret"],
      "token_endpoint_auth_method" => context["token_endpoint_auth_method"] || "client_secret_basic",
    )
  end
  storage
 end
 # Builds a `client_credentials`-only provider (machine-to-machine, no redirect).
 # The pre-registered credentials are injected by the harness via context:
 # a shared secret for the basic scenario, or a PEM private key plus signing algorithm
 # (default ES256, matching the TypeScript and Python conformance clients)
 # for the `private_key_jwt` scenario.
 def build_client_credentials_provider(context)
  if context["private_key_pem"]
    MCP::Client::OAuth::ClientCredentialsProvider.new(
      client_id: context["client_id"],
      token_endpoint_auth_method: "private_key_jwt",
      private_key: context["private_key_pem"],
      signing_algorithm: context["signing_algorithm"] || "ES256",
    )
  else
    MCP::Client::OAuth::ClientCredentialsProvider.new(
      client_id: context["client_id"],
      client_secret: context["client_secret"],
      token_endpoint_auth_method: context["token_endpoint_auth_method"] || "client_secret_basic",
    )
  end
 end
 # Builds a SEP-990 Cross-App Access provider: the harness injects an IdP ID token plus the IdP token endpoint
 # via context; the assertion provider exchanges them for an ID-JAG (RFC 8693), which the flow then presents to
 # the MCP authorization server with the jwt-bearer grant.
 def build_cross_app_access_provider(context)
  assertion_provider = ->(audience:, resource:) do
    MCP::Client::OAuth::IDJAGTokenExchange.request(
      token_endpoint: context["idp_token_endpoint"],
      id_token: context["idp_id_token"],
      client_id: context["idp_client_id"],
      audience: audience,
      resource: resource,
    )
  end
  MCP::Client::OAuth::CrossAppAccessProvider.new(
    client_id: context["client_id"],
    client_secret: context["client_secret"],
    assertion_provider: assertion_provider,
  )
 end
 # Builds an OAuth provider that drives the authorization code + PKCE + DCR flow
 # non-interactively against the conformance test's auth server. The conformance
 # `/authorize` endpoint redirects synchronously to `redirect_uri` with
 # `code=test-auth-code`, so we follow it manually instead of opening a browser.
 def build_oauth_provider(context, scenario:)
  callback_holder = {}
  redirect_uri = "http://localhost:0/callback"
  redirect_handler = ->(authorization_url) do
    response = Faraday.new.get(authorization_url) do |req|
      req.options.params_encoder = nil
    end
    location = response.headers["location"] || response.headers["Location"]
    abort("Authorization request did not redirect: #{response.status}.") unless location
    callback_holder[:url] = URI.parse(location)
  end
  callback_handler = -> do
    query = URI.decode_www_form(callback_holder.fetch(:url).query).to_h
    # The 3-element form opts into SEP-2468 / RFC 9207 `iss` validation;
    # `query["iss"]` is nil when the authorization response carried no `iss`.
    [query["code"], query["state"], query["iss"]]
  end
  MCP::Client::OAuth::Provider.new(
    client_metadata: {
      client_name: "ruby-sdk-conformance-client",
      redirect_uris: [redirect_uri],
      grant_types: ["authorization_code", "refresh_token"],
      response_types: ["code"],
      token_endpoint_auth_method: "none",
    },
    redirect_uri: redirect_uri,
    redirect_handler: redirect_handler,
    callback_handler: callback_handler,
    storage: storage_for(context),
    client_id_metadata_document_url: (scenario == "auth/basic-cimd" ? CONFORMANCE_CIMD_URL : nil),
  )
 end
 def build_provider_for(scenario, context)
  if context["idp_id_token"]
    build_cross_app_access_provider(context)
  elsif scenario.start_with?("auth/client-credentials")
    build_client_credentials_provider(context)
  else
    build_oauth_provider(context, scenario: scenario)
  end
 end
 oauth = scenario.start_with?("auth/") ? build_provider_for(scenario, conformance_context) : nil
 transport = MCP::Client::HTTP.new(url: server_url, oauth: oauth)
 client = MCP::Client.new(transport: transport)
 # SEP-2322: the MRTR scenario exercises the automatic driver; this elicitation handler accepts
 # every embedded confirmation request, and the driver echoes `requestState` byte-exactly.
 # The same registration answers a real `elicitation/create` request, so nothing here is MRTR-specific.
 if scenario == "sep-2322-client-request-state"
  client.on_elicitation { |_params| { action: "accept", content: { confirmed: true } } }
 end
 capabilities = scenario == "elicitation-sep1034-client-defaults" ? { elicitation: {} } : {}
 # The conformance harness asserts on the observed protocol exchange, not on the client's exit status,
 # and echoes the client's output only when the exit status is non-zero. Several negative auth scenarios
 # (e.g. `auth/resource-mismatch`, `auth/scope-retry-limit`) are expected to drive the client into
 # a terminal failure: the SDK correctly refuses a mismatched resource or stops after the scope step-up
 # retry limit. Report such an expected failure as a one-line reason and exit cleanly so the run stays
 # free of noise, while letting any unexpected error (a real SDK bug) still raise with a full backtrace
 # and a failing exit status.
 begin
  # The harness names the wire version per scenario run: the 2026 draft selects the stateless modern lifecycle,
  # and every dated version through 2025-11-25 keeps the legacy `initialize` handshake
  # (pinned rather than `:auto`, whose `server/discover` probe the legacy scenario servers do not expect).
  mode = ENV["MCP_CONFORMANCE_PROTOCOL_VERSION"] == "2026-07-28" ? :modern : :legacy
  connect = lambda do
    client.connect(
      client_info: { name: "ruby-sdk-conformance-client", version: MCP::VERSION },
      capabilities: capabilities,
      mode: mode,
    )
  end
  begin
    connect.call
  rescue MCP::Client::RequestHandlerError
    # SEP-2575 version negotiation: a server may reject the first request with `-32022` naming
    # its supported versions. Retry once so the harness observes a follow-up request carrying
    # a mutually supported version (this client already speaks the latest draft).
    raise unless mode == :modern
    connect.call
  end
  case scenario
  when "initialize"
    client.tools
  when "json-schema-2020-12-preservation"
    # SEP-1613/SEP-2106: echo the focal tool's observed inputSchema verbatim so the harness
    # can diff what the client preserved. Preservation holds because `Client::Tool#input_schema`
    # is the parsed response untouched.
    tools = client.tools
    focal = tools.find { |t| t.name == "json_schema_2020_12_tool" }
    abort("Tool json_schema_2020_12_tool not found") unless focal
    client.call_tool(name: "json_schema_echo", arguments: { "schema" => focal.input_schema })
  when "request-metadata"
    # SEP-2575: the checks read the envelope and headers of the requests the modern connect
    # and this listing already produce.
    client.tools
  when "sep-2322-client-request-state"
    # SEP-2322: the driver resumes `test_mrtr_echo_state` automatically (fresh JSON-RPC id,
    # byte-exact `requestState` echo); `test_mrtr_unrelated` must carry neither retry field;
    # `test_mrtr_no_state` retries without inventing a state; `test_mrtr_no_result_type`
    # has no `resultType` and therefore must be treated as complete, with no retry.
    client.tools
    client.call_tool(name: "test_mrtr_echo_state", arguments: {})
    client.call_tool(name: "test_mrtr_unrelated", arguments: {})
    client.call_tool(name: "test_mrtr_no_state", arguments: {})
    client.call_tool(name: "test_mrtr_no_result_type", arguments: {})
  when "http-custom-headers"
    # SEP-2243: the harness names the exact tool calls (with encoding edge-case values) via context;
    # listing first teaches the transport the `x-mcp-header` declarations it mirrors.
    client.tools
    (conformance_context["toolCalls"] || []).each do |tool_call|
      client.call_tool(name: tool_call["name"], arguments: tool_call["arguments"])
    end
  when "http-invalid-tool-headers"
    # SEP-2243: the listing carries one valid tool among invalid `x-mcp-header` definitions;
    # calling only the valid one shows the invalid definitions did not block it.
    client.tools
    client.call_tool(name: "valid_tool", arguments: { "message" => "hello" })
  when "http-standard-headers"
    # SEP-2243: the harness inspects the `Mcp-Method` header on every POST and the `Mcp-Name` header on
    # the name-carrying requests, so drive one of each standard request kind.
    tools = client.tools
    tool = tools.find { |t| t.name == "test_headers" } || tools.first
    abort("No tool exposed by conformance server for #{scenario}") unless tool
    client.call_tool(tool: tool, arguments: {})
    resource = client.resources.first
    abort("No resource exposed by conformance server for #{scenario}") unless resource
    client.read_resource(uri: resource["uri"])
    prompt = client.prompts.first
    abort("No prompt exposed by conformance server for #{scenario}") unless prompt
    client.get_prompt(name: prompt["name"])
  when "json-schema-ref-no-deref"
    # SEP-2106: listing tools whose schemas carry `$ref` must not trigger network dereferencing.
    client.tools
  when "tools_call"
    tools = client.tools
    add_numbers = tools.find { |t| t.name == "add_numbers" }
    abort("Tool add_numbers not found") unless add_numbers
    client.call_tool(tool: add_numbers, arguments: { a: 1, b: 2 })
  when "sse-retry"
    # SEP-1699: the server closes the tools/call SSE stream right after a priming event.
    # The transport waits the server's `retry:` interval, reconnects with a GET carrying `Last-Event-ID`,
    # and receives the tool result on the resumed stream; the harness verifies the reconnect,
    # its timing, and the header.
    tools = client.tools
    test_reconnection = tools.find { |t| t.name == "test_reconnection" }
    abort("Tool test_reconnection not found") unless test_reconnection
    client.call_tool(tool: test_reconnection, arguments: {})
  when "elicitation-sep1034-client-defaults"
    # SEP-1034: the server sends `elicitation/create` on the tools/call SSE stream with every property declaring
    # a `default` and none required. The handler accepts and fills the omitted fields from those defaults.
    client.on_elicitation do |params|
      { action: "accept", content: MCP::Client::Elicitation.apply_defaults(params["requestedSchema"] || {}) }
    end
    tools = client.tools
    defaults_tool = tools.find { |t| t.name == "test_client_elicitation_defaults" }
    abort("Tool test_client_elicitation_defaults not found") unless defaults_tool
    client.call_tool(tool: defaults_tool, arguments: {})
  when %r|\Aauth/|
    # Auth-only scenarios: the protocol-level checks (PRM/AS metadata, DCR, PKCE, token usage)
    # are observed by the conformance server during `connect` and the subsequent request below.
    # Listing tools forces a second authenticated MCP request so the bearer token usage check fires.
    tools = client.tools
    # `auth/scope-step-up` only fires its escalation 403 on `tools/call`, not `tools/list`,
    # so the client must actually invoke a tool to drive the second authorization request
    # the scenario asserts on.
    if scenario == "auth/scope-step-up"
      tool = tools.find { |t| t.name == "test-tool" } || tools.first
      abort("No tool exposed by conformance server for #{scenario}") unless tool
      client.call_tool(tool: tool, arguments: {})
    end
  else
    abort("Unknown or unsupported scenario: #{scenario}")
  end
 rescue MCP::Client::OAuth::Flow::AuthorizationError, MCP::Client::RequestHandlerError, Faraday::Error => e
  warn("#{scenario}: client ended in the expected terminal failure (#{e.class}: #{e.message})")
  exit
 end
--- a/conformance/client_runner.rb
+++ b/conformance/client_runner.rb
@ -1,48 +0,0 @@
 # frozen_string_literal: true
 # Runs `npx @modelcontextprotocol/conformance@alpha client` against the conformance client script.
 require "English"
 module Conformance
  class ClientRunner
    def initialize(scenario: nil, spec_version: nil, verbose: false)
      @scenario = scenario
      @spec_version = spec_version
      @verbose = verbose
    end
    def run
      command = build_command
      puts "Command: #{command.join(" ")}\n\n"
      system(*command)
      conformance_exit_code = $CHILD_STATUS.exitstatus
      exit(conformance_exit_code || 1) unless conformance_exit_code == 0
    end
    private
    def build_command
      expected_failures_yml = File.expand_path("expected_failures.yml", __dir__)
      client_script = File.expand_path("client.rb", __dir__)
      npx_command = [
        "npx",
        "--yes",
        "@modelcontextprotocol/conformance@alpha",
        "client",
        "--command",
        "bundle exec ruby #{client_script}",
      ]
      npx_command += if @scenario
        ["--scenario", @scenario]
      else
        ["--suite", "all"]
      end
      npx_command += ["--spec-version", @spec_version] if @spec_version
      npx_command += ["--verbose"] if @verbose
      npx_command += ["--expected-failures", expected_failures_yml]
      npx_command
    end
  end
 end
--- a/conformance/expected_failures.yml
+++ b/conformance/expected_failures.yml
@ -1,6 +0,0 @@
 server: []
 client:
  # Unimplemented authorization extensions.
  - auth/dpop
  - auth/dpop-nonce
  - auth/wif-jwt-bearer
--- a/conformance/server.rb
+++ b/conformance/server.rb
--- a/conformance/server_runner.rb
+++ b/conformance/server_runner.rb
@ -1,101 +0,0 @@
 # frozen_string_literal: true
 # Starts the conformance server and runs `npx @modelcontextprotocol/conformance@alpha` against it.
 require "English"
 require "net/http"
 require_relative "server"
 module Conformance
  class ServerRunner
    # Timeout for waiting for the Puma server to start.
    SERVER_START_TIMEOUT = 20
    SERVER_POLL_INTERVAL = 0.5
    SERVER_HEALTH_CHECK_RETRIES = (SERVER_START_TIMEOUT / SERVER_POLL_INTERVAL).to_i
    def initialize(port: Server::DEFAULT_PORT, scenario: nil, spec_version: nil, verbose: false)
      @port = port
      @scenario = scenario
      @spec_version = spec_version
      @verbose = verbose
    end
    def run
      command = build_command
      server_pid = start_server
      run_conformance(command, server_pid: server_pid)
    end
    private
    def build_command
      expected_failures_yml = File.expand_path("expected_failures.yml", __dir__)
      npx_command = ["npx", "--yes", "@modelcontextprotocol/conformance@alpha", "server", "--url", "http://localhost:#{@port}/mcp"]
      npx_command += ["--scenario", @scenario] if @scenario
      npx_command += ["--spec-version", @spec_version] if @spec_version
      npx_command += ["--verbose"] if @verbose
      npx_command += ["--expected-failures", expected_failures_yml]
      npx_command
    end
    def start_server
      puts "Starting conformance server on port #{@port}..."
      server_pid = fork do
        Conformance::Server.new(port: @port).start
      end
      health_url = URI("http://localhost:#{@port}/health")
      ready = false
      SERVER_HEALTH_CHECK_RETRIES.times do
        begin
          response = Net::HTTP.get_response(health_url)
          if response.code == "200"
            ready = true
            break
          end
        rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Net::ReadTimeout
          # not ready yet
        end
        sleep(SERVER_POLL_INTERVAL)
      end
      unless ready
        warn("ERROR: Conformance server did not start within #{SERVER_START_TIMEOUT} seconds")
        terminate_server(server_pid)
        exit(1)
      end
      puts "Server ready. Running conformance tests..."
      server_pid
    end
    def run_conformance(command, server_pid:)
      puts "Command: #{command.join(" ")}\n\n"
      conformance_exit_code = nil
      begin
        system(*command)
        conformance_exit_code = $CHILD_STATUS.exitstatus
      ensure
        terminate_server(server_pid)
      end
      exit(conformance_exit_code || 1) unless conformance_exit_code == 0
    end
    def terminate_server(pid)
      Process.kill("TERM", pid)
    rescue Errno::ESRCH
      # process already exited
    ensure
      begin
        Process.wait(pid)
      rescue Errno::ECHILD
        # already reaped
      end
    end
  end
 end
--- a/Show more
+++ b/Show more