mcp 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b7c0c225e89be4cfc9c73a0707b8a6a61d0d76a8a21340b20b3dd276f36eec6
-  data.tar.gz: fdd1b11cbe6ac733820bc604f72c95c6f0aa67162776c8778de7adb04aa7ca39
+  metadata.gz: 325fab0f82b31b6a2614ef626ebecb12a7bf22c199ddf189dcd70b4fcf9acb58
+  data.tar.gz: 7cb2b010e0808efce62e9d80f487c7cb6bff9604e13f6b2b68590ffa4e0fc784
 SHA512:
-  metadata.gz: c6dce7fe76f5f3996c9f5caffe884237147c74840d4d68dce5ec6ec24be49e65e0eea39306c2c52353c5014c8247295491b3337e166cec662eca19742565d741
-  data.tar.gz: b944ae1938952c5e4fd20fb4b5d1ade071cf5ffa193b6c0cd56ba25e79aa583e2de38804045ce0d038eb2e38b5ea5bed4fd6b6073a16fea8bdba02f7e1e8b148
+  metadata.gz: 6c675a999c460dd7a285203e949587ecf1faf43a0f80f67f6f00bbb06abaa31846382cf013a0590a22c237b341860bc9a880d2d6d5de2971c8f70cde8d9d78ee
+  data.tar.gz: 84f4ca2c9a3a745976059655e2ea6f89ff5bae6637b32ab151894f12b3aea96ce5f11d9e50b3c908769f97e9bc923fd68f0e0b83060104964710d6ca70f06cb0

data/README.md

@@ -1885,6 +1885,113 @@ 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.
 
+#### OAuth 2.1 Authorization
+
+When an MCP server enforces the [MCP Authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization),
+pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Authorization` header. The transport will:
+
+- Send `Authorization: Bearer <access_token>` on every request when a token is available.
+- 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.
+- 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).
+
+```ruby
+require "mcp"
+
+provider = MCP::Client::OAuth::Provider.new(
+  client_metadata: {
+    client_name: "My MCP App",
+    redirect_uris: ["http://localhost:3030/callback"],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+  },
+  redirect_uri: "http://localhost:3030/callback",
+  redirect_handler: ->(authorization_url) {
+    # Send the user to the authorization URL - typically `Launchy.open(authorization_url)`
+    # or a manual `puts authorization_url` in CLI tools.
+  },
+  callback_handler: -> {
+    # Capture the redirect (for example, by running a small HTTP listener on
+    # `redirect_uri`) and return [code, state] from the query string.
+  },
+)
+
+transport = MCP::Client::HTTP.new(
+  url: "https://api.example.com/mcp",
+  oauth: provider,
+)
+client = MCP::Client.new(transport: transport)
+client.connect # `initialize` is sent here; if the server replies 401 the OAuth flow runs and the handshake is retried with the acquired token
+client.tools
+```
+
+Required keyword arguments to `Provider.new`:
+
+- `client_metadata`: Hash sent to the authorization server's Dynamic Client Registration endpoint. Must include `redirect_uris`, `grant_types`, `response_types`,
+  `token_endpoint_auth_method`. `redirect_uri` (below) must appear in this list, otherwise the constructor raises `Provider::UnregisteredRedirectURIError`.
+- `redirect_uri`: String. Must use HTTPS or be a loopback URL (`localhost`, `127.0.0.0/8`, `::1`); other values raise `Provider::InsecureRedirectURIError`.
+- `redirect_handler`: Callable invoked with the fully-built authorization `URI`. Typically opens the user's browser.
+- `callback_handler`: Callable that returns `[code, state]` after the user is redirected back to `redirect_uri`.
+
+Optional keyword arguments:
+
+- `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
+- `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.
+
+To persist credentials across restarts, supply your own storage:
+
+```ruby
+class FileTokenStorage
+  def initialize(path)
+    @path = path
+  end
+
+  def tokens
+    read["tokens"]
+  end
+
+  def save_tokens(value)
+    write("tokens" => value)
+  end
+
+  def client_information
+    read["client"]
+  end
+
+  def save_client_information(value)
+    write("client" => value)
+  end
+
+  private
+
+  def read
+    File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+  end
+
+  def write(updates)
+    File.write(@path, JSON.dump(read.merge(updates)))
+  end
+end
+
+provider = MCP::Client::OAuth::Provider.new(
+  # ... required keywords ...
+  storage: FileTokenStorage.new(File.expand_path("~/.config/my-app/oauth.json")),
+)
+```
+
+##### Communication Security
+
+When `oauth:` is set, the MCP transport URL and every OAuth-facing URL (PRM, Authorization Server metadata, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,
+`redirect_uri`) must use HTTPS or a loopback host. Non-loopback `http://` URLs are rejected at the SDK boundary so a bearer token is never sent over plain HTTP to a remote host.
+
+The transport also snapshots the canonicalized origin, path, and query string of the MCP URL at `initialize` time and re-checks them on every outgoing request through
+a Faraday middleware that runs after any user-supplied customizer. That means any URL swap raises `MCP::Client::HTTP::InsecureURLError` before the request reaches the adapter,
+whether the swap was triggered by
+`instance_variable_set(:@url, ...)`, by a Faraday customizer rewriting `url_prefix`, or by a custom middleware rewriting `env.url` (including just `env.url.query`) at request time,
+and whether the new URL is `http://` *or* `https://` to a different host or tenant.
+
 #### Customizing the Faraday Connection
 
 You can pass a block to `MCP::Client::HTTP.new` to customize the underlying Faraday connection.

data/lib/mcp/client/http.rb

@@ -17,12 +17,74 @@ module MCP
       SESSION_ID_HEADER = "Mcp-Session-Id"
       PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version"
 
-      attr_reader :url, :session_id, :protocol_version, :server_info
+      # Raised when an `oauth:` provider is paired with an MCP URL that is neither HTTPS nor
+      # a loopback `http://` URL, since a bearer token sent over plain HTTP to a remote host
+      # is trivially observed and stolen.
+      class InsecureURLError < ArgumentError; end
+
+      # Faraday request middleware that compares the outgoing request URL
+      # against the URL snapshotted at `MCP::Client::HTTP#initialize` time.
+      # Registered after the user's customizer so it sees `env.url` *after*
+      # any custom middleware has had a chance to rewrite it - closing
+      # the `Faraday env.url = URI("https://attacker...")` bypass that a plain
+      # `client.url_prefix` check would miss. The comparison includes
+      # the query string, so a middleware that rewrites `env.url.query` to
+      # a different tenant (e.g. `?tenant=evil`) is rejected as well; otherwise
+      # the audience-binding check on the OAuth side could be bypassed at
+      # the send step.
+      class OAuthURLGuard
+        def initialize(app, expected_url:)
+          @app = app
+          @expected_url = expected_url
+        end
+
+        def call(env)
+          effective = MCP::Client::OAuth::Discovery.canonicalize_url(env.url.to_s)
+          unless effective == @expected_url
+            # Surface the *canonicalized* form (no userinfo, no fragment) so
+            # credentials like `user:pass@` cannot leak into logs, stack
+            # traces, or exception reporters.
+            raise InsecureURLError,
+              "Effective request URL #{effective.inspect} does not match the URL " \
+                "validated at initialize time (#{@expected_url.inspect}); refusing to send a bearer token."
+          end
+          @app.call(env)
+        end
+      end
+
+      attr_reader :url, :session_id, :protocol_version, :server_info, :oauth
+
+      def initialize(url:, headers: {}, oauth: nil, &block)
+        if oauth && !MCP::Client::OAuth::Discovery.secure_url?(url)
+          # Mask credentials (userinfo) and query parameters before quoting the URL in the error message
+          # so they cannot leak into logs.
+          safe_url = MCP::Client::OAuth::Discovery.canonicalize_origin_and_path(url)
+          raise InsecureURLError,
+            "MCP URL #{safe_url.inspect} must use https or be a loopback http URL when an oauth provider is set; " \
+              "sending bearer tokens over plain http to a remote host would leak them on the wire."
+        end
 
-      def initialize(url:, headers: {}, &block)
         @url = url
         @headers = headers
         @faraday_customizer = block
+        @oauth = oauth
+        # Snapshot the canonical URL at construction time. This single value
+        # serves two related roles, both of which need to see the query string:
+        #
+        # - As the RFC 8707 `resource` claim sent on the authorization and
+        #   token requests (and as the base for PRM discovery URLs) -
+        #   matching the TS / Python SDKs' `resourceUrlFromServerUrl` /
+        #   `resource_url_from_server_url` so multi-tenant servers that scope
+        #   by `?tenant=...` round-trip correctly.
+        # - As the comparison value for the URL guard middleware. Comparing
+        #   query strings as well as origin + path is required so a Faraday
+        #   middleware that rewrites `env.url.query` to a different tenant
+        #   cannot send the bearer token to the wrong audience while
+        #   the resource binding on the OAuth side stays correct.
+        #
+        # Saved only when `oauth:` is set so non-OAuth transports keep their
+        # existing behavior.
+        @oauth_server_url = oauth ? MCP::Client::OAuth::Discovery.canonicalize_url(url) : nil
         @session_id = nil
         @protocol_version = nil
         @server_info = nil
@@ -30,8 +92,8 @@ module MCP
       end
 
       # Performs the MCP `initialize` handshake: sends an `initialize` request
-      # followed by the required `notifications/initialized` notification. The
-      # server's `InitializeResult` (protocol version, capabilities, server
+      # followed by the required `notifications/initialized` notification.
+      # The server's `InitializeResult` (protocol version, capabilities, server
       # info, instructions) is cached on the transport and returned.
       #
       # Idempotent: a second call returns the cached `InitializeResult` without
@@ -122,68 +184,80 @@ module MCP
       def send_request(request:)
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
+        oauth_retried = false
 
-        response = client.post("", request, session_headers)
-        body = parse_response_body(response, method, params)
+        begin
+          response = client.post("", request, session_headers)
+          body = parse_response_body(response, method, params)
 
-        capture_session_info(method, response, body)
+          capture_session_info(method, response, body)
 
-        body
-      rescue Faraday::BadRequestError => e
-        raise RequestHandlerError.new(
-          "The #{method} request is invalid",
-          { method: method, params: params },
-          error_type: :bad_request,
-          original_error: e,
-        )
-      rescue Faraday::UnauthorizedError => e
-        raise RequestHandlerError.new(
-          "You are unauthorized to make #{method} requests",
-          { method: method, params: params },
-          error_type: :unauthorized,
-          original_error: e,
-        )
-      rescue Faraday::ForbiddenError => e
-        raise RequestHandlerError.new(
-          "You are forbidden to make #{method} requests",
-          { method: method, params: params },
-          error_type: :forbidden,
-          original_error: e,
-        )
-      rescue Faraday::ResourceNotFound => e
-        # Per spec, 404 is the session-expired signal only when the request
-        # actually carried an `Mcp-Session-Id`. A 404 without a session attached
-        # (e.g. wrong URL or a stateless server) surfaces as a generic not-found.
-        # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
-        if @session_id
-          clear_session
-          raise SessionExpiredError.new(
-            "The #{method} request is not found",
+          body
+        rescue Faraday::BadRequestError => e
+          raise RequestHandlerError.new(
+            "The #{method} request is invalid",
             { method: method, params: params },
+            error_type: :bad_request,
             original_error: e,
           )
-        else
+        rescue Faraday::UnauthorizedError => e
+          # Run the OAuth flow at most once per `send_request` invocation.
+          # The `oauth_retried` flag lives outside the `begin` so it survives `retry`,
+          # ensuring a server returning 401 indefinitely raises rather than loops.
+          if @oauth && !oauth_retried
+            oauth_retried = true
+            run_oauth_flow!(unauthorized_error: e)
+            retry
+          end
+
           raise RequestHandlerError.new(
-            "The #{method} request is not found",
+            "You are unauthorized to make #{method} requests",
             { method: method, params: params },
-            error_type: :not_found,
+            error_type: :unauthorized,
+            original_error: e,
+          )
+        rescue Faraday::ForbiddenError => e
+          raise RequestHandlerError.new(
+            "You are forbidden to make #{method} requests",
+            { method: method, params: params },
+            error_type: :forbidden,
+            original_error: e,
+          )
+        rescue Faraday::ResourceNotFound => e
+          # Per spec, 404 is the session-expired signal only when the request
+          # actually carried an `Mcp-Session-Id`. A 404 without a session attached
+          # (e.g. wrong URL or a stateless server) surfaces as a generic not-found.
+          # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+          if @session_id
+            clear_session
+            raise SessionExpiredError.new(
+              "The #{method} request is not found",
+              { method: method, params: params },
+              original_error: e,
+            )
+          else
+            raise RequestHandlerError.new(
+              "The #{method} request is not found",
+              { method: method, params: params },
+              error_type: :not_found,
+              original_error: e,
+            )
+          end
+        rescue Faraday::UnprocessableEntityError => e
+          raise RequestHandlerError.new(
+            "The #{method} request is unprocessable",
+            { method: method, params: params },
+            error_type: :unprocessable_entity,
+            original_error: e,
+          )
+        rescue Faraday::Error => e
+          raise RequestHandlerError.new(
+            "Internal error handling #{method} request",
+            { method: method, params: params },
+            error_type: :internal_error,
             original_error: e,
           )
         end
-      rescue Faraday::UnprocessableEntityError => e
-        raise RequestHandlerError.new(
-          "The #{method} request is unprocessable",
-          { method: method, params: params },
-          error_type: :unprocessable_entity,
-          original_error: e,
-        )
-      rescue Faraday::Error => e # Catch-all
-        raise RequestHandlerError.new(
-          "Internal error handling #{method} request",
-          { method: method, params: params },
-          error_type: :internal_error,
-          original_error: e,
-        )
       end
 
       # Terminates the session by sending an HTTP DELETE to the MCP endpoint
@@ -228,20 +302,93 @@ module MCP
           end
 
           @faraday_customizer&.call(faraday)
+
+          # Register the URL identity guard *after* the user's customizer
+          # so it sits closest to the adapter in the request stack. That way
+          # the guard sees `env.url` after any customizer-added middleware has had
+          # a chance to rewrite it, closing the `env.url = URI("https://...")`
+          # bypass that a `Faraday::Connection#url_prefix` check cannot detect.
+          faraday.use(OAuthURLGuard, expected_url: @oauth_server_url) if @oauth_server_url
         end
       end
 
       # Per spec, the client MUST include `MCP-Session-Id` (when the server assigned one)
       # and `MCP-Protocol-Version` on all requests after `initialize`.
+      #
       # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
       # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header
       def session_headers
         request_headers = {}
         request_headers[SESSION_ID_HEADER] = @session_id if @session_id
         request_headers[PROTOCOL_VERSION_HEADER] = @protocol_version if @protocol_version
+        if @oauth && (token = @oauth.access_token)
+          request_headers["Authorization"] = "Bearer #{token}"
+        end
         request_headers
       end
 
+      # Drives the OAuth orchestrator on a 401 from the MCP endpoint.
+      # The `WWW-Authenticate` header (when present) supplies the `resource_metadata`
+      # URL and an optional `scope` challenge per RFC 9728 Section 5.1.
+      #
+      # If the provider already holds a refresh token, we try to exchange it
+      # for a fresh access token first; only when that fails (e.g., the refresh token was revoked)
+      # do we fall back to the full Authorization Code + PKCE + DCR flow.
+      #
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#error-handling
+      def run_oauth_flow!(unauthorized_error:)
+        response = unauthorized_error.response || {}
+        response_headers = response[:headers] || {}
+        www_authenticate = response_headers["www-authenticate"] || response_headers["WWW-Authenticate"]
+        params = MCP::Client::OAuth::Discovery.parse_www_authenticate(www_authenticate)
+
+        flow = MCP::Client::OAuth::Flow.new(provider: @oauth)
+        if attempt_refresh(flow: flow, resource_metadata_url: params["resource_metadata"])
+          return
+        end
+
+        # Use the URL snapshotted at `initialize` time so a post-construction
+        # mutation of `@url` cannot redirect PRM/AS discovery and the authorize
+        # URL to an attacker-controlled host.
+        flow.run!(
+          server_url: @oauth_server_url,
+          resource_metadata_url: params["resource_metadata"],
+          scope: params["scope"],
+        )
+      end
+
+      # Tries to swap a saved `refresh_token` for a fresh access token. Returns truthy
+      # on success and falsy on either "no refresh token available" or "refresh attempt failed"
+      # (in which case the caller should run the full interactive flow).
+      def attempt_refresh(flow:, resource_metadata_url:)
+        return false unless refresh_token_available?
+
+        # Use the snapshotted URL for the same reason as `run_oauth_flow!` above:
+        # post-construction `@url` mutation must not redirect token-refresh
+        # discovery to an attacker-controlled host. Use the query-bearing form
+        # so the refresh request's RFC 8707 `resource` claim matches
+        # the original authorization request.
+        flow.refresh!(server_url: @oauth_server_url, resource_metadata_url: resource_metadata_url)
+        true
+      rescue MCP::Client::OAuth::Flow::InvalidGrantError
+        # The refresh token has been revoked or expired by the AS. Wipe it so
+        # the full interactive flow runs fresh on the retry.
+        @oauth.clear_tokens!
+        false
+      rescue MCP::Client::OAuth::Flow::AuthorizationError
+        # Transient failure (network, 5xx, AS metadata, etc.). Leave the refresh
+        # token in place; the next attempt may succeed and we avoid forcing
+        # the user through an interactive reauth for a recoverable error.
+        false
+      end
+
+      def refresh_token_available?
+        tokens = @oauth.tokens
+        return false unless tokens.is_a?(Hash)
+
+        !(tokens["refresh_token"] || tokens[:refresh_token]).to_s.empty?
+      end
+
       def capture_session_info(method, response, body)
         return unless method.to_s == Methods::INITIALIZE