Let a provider customize the HTTP client the OAuth flow uses

[koic]

Motivation and Context

MCP::Client::OAuth::Flow takes an http_client_factory:, but MCP::Client::HTTP builds the flow itself and passes none, so an application using oauth: could not add middleware to the requests the flow makes: Protected Resource Metadata and authorization server metadata discovery, dynamic client registration, and every token request. The block that customizes the transport's Faraday connection does not help, because that connection is bound to the MCP server URL and carries the headers: meant for that server, and the authorization server is a different origin. The TypeScript SDK hands the transport's fetch to auth() and the Python SDK sends the provider's requests through the transport's httpx client, so both let an application instrument these requests; this SDK did not. (#558)

Providers now take http_client_customizer:, a callable invoked with the Faraday connection the flow builds for its own requests, next to the other callables a provider already holds. It runs after the SDK's defaults (Accept: application/json, no redirect following) and between two middlewares of the SDK's own: Flow::RequestedURLStamp, registered before the customizer is invoked, records the URL the flow asked for on the request environment, and Flow::RequestedOriginGuard, registered last, sees what the customizer's middleware did to the request after that record. A request that would leave that origin, by following a redirect or rewriting the URL, or that arrives without the record, is refused with Flow::DestinationMismatchError before it reaches the adapter. The record lives on the environment rather than in env.request.context, which stays the application's to fill or replace. The error is an ArgumentError rather than an AuthorizationError so neither discovery nor the transport's refresh fallback can absorb a configuration mistake. The boundary resembles the one the Python SDK keeps for its own requests, which follows a redirect only within the origin; this flow follows none itself. Flow.build_http_client assembles that connection and Flow.new(http_client_factory:) keeps replacing it whole. Following done inside an adapter cannot be seen by any guard, so the documentation keeps that, Accept-Encoding, and raise_error off the list of things a customizer may add, and notes that a recording middleware sees client credentials and tokens.

Fixes #558.

How Has This Been Tested?

New tests in test/mcp/client/oauth/flow_test.rb, test/mcp/client/oauth/http_oauth_test.rb, and the three provider test files. Against the library before this change, every one of them fails, on the unknown keyword or on the missing reader.

Breaking Changes

None. The customizer is opt-in, and the guard cannot fire on the SDK's own middleware-free connection.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[kstevens715]

This works for our case — thanks for turning it around so quickly.

Putting http_client_customizer: on the provider is a better shape than the factory keyword I suggested in #558: we construct the provider anyway, so there's nothing to thread through the transport, and it covers discovery and registration rather than just the token requests.

Our middleware is observation-only — it adds no redirect following, doesn't set Accept-Encoding, doesn't add raise_error, and doesn't rewrite the URL — so it sits inside the constraints RequestedOriginGuard enforces.

Together with #555, this closes both of the blockers that kept us off oauth:.