feature(auth): Allow delegating OAuth authorization to existing app-level implementations

[m-paternostro]

An optional provider that clients can use whenever the authentication should be delegated to an existing implementation.

This PR introduces a new optional DelegatedAuthClientProvider interface. It allows clients to delegate authentication to existing systems when they already manage authorization through another mechanism (e.g. platform tokens, ambient credentials, preexisting identity systems). When provided, this provider takes precedence over the standard OAuth flow and gives control to the host application for both header injection and authentication handling.

Motivation and Context

Some applications embedding the MCP SDK already have fully functional authorization systems. In such cases, the SDK’s built-in OAuth flow can be redundant or even problematic - especially when the app simply needs to know when authorization is required, not how to perform it.

Prior to this change, the only way to hook into the authorization process was by subclassing StreamableHTTPClientTransport and/or SSEClientTransport and overriding enough methods to reimplement the auth flow. However, because the relevant methods are private and deeply interwoven, doing so required replicating a significant amount of transport code - leading to maintenance burden and fragile overrides.

This change introduces a clean, focused interface for delegating authentication to external systems without needing to reimplement transport logic. The DelegatedAuthClientProvider is implemented directly in both transport classes and takes precedence over OAuthClientProvider when both are provided.

How Has This Been Tested?

The implementation was validated with comprehensive unit tests covering both StreamableHTTPClientTransport and SSEClientTransport. Tests verify header injection, precedence over OAuth providers, 401 handling with successful reauth, and error handling when authentication fails.

Breaking Changes

No: the new method is purely opt-in, backward-compatible, and safely ignored if unimplemented. It’s designed to be as simple and low-friction as possible while avoiding the need to subclass transports or bypass internal behavior.

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

Additional context

Notes about the changes:

• A new DelegatedAuthClientProvider interface is defined in src/client/auth.ts with headers() and authorize() methods.
• Both StreamableHTTPClientTransport and SSEClientTransport support the optional delegatedAuthProvider option.
• When provided, delegatedAuthProvider takes precedence over authProvider for all authentication operations.
• Comprehensive unit tests were added to verify:
  • Header injection from the delegated provider.
  • Precedence over OAuth providers when both are configured.
  • 401 handling with successful and failed reauth scenarios.
  • Context information (serverUrl, resourceMetadataUrl) is passed to the authorize method.
• The implementation follows existing conventions and coexists seamlessly with the OAuth provider system.

[m-paternostro]

Hi @ihrpr ,

Sorry for the direct tag. I really appreciate that this is already on the HPR list, and I completely understand you have a lot on your plate.

This is just a gentle nudge on the PR - a decision here would really help me move forward on my side, especially if the change is accepted.

Thanks again for all the amazing work on the SDK! It’s been a real pleasure working with it over the past three months ;-)

[m-paternostro]

One additional detail worth mentioning: the OAuth implementation used by my company (and others as well 😉) includes JWT tokens in the final authentication response. These tokens encode valuable metadata such as user identity, organization context, and more.

This is yet another reason to allow client implementations to fully control the authentication flow - they may want to extract and act on this information in ways that are specific to their environment.

[m-paternostro]

👋 Hello,

I just wanted to follow up on this PR. I’ve been keeping it up to date over the past month, including adapting to changes like the recent addition of protected resource support (RFC 8707), which this PR now explicitly handles.

I really appreciate that it was marked as an HPR and I took that as a sign that it might be reviewed soon. I also sent a (hopefully gentle) nudge to @ihrpr at the time, just to make sure it was on the radar.

My main reason for commenting now is to ask for a bit of clarity: I’m more than happy to continue monitoring and updating this PR for as long as there’s a reasonable chance it might be reviewed and potentially merged. I sincerely believe it improves the SDK’s OAuth2 support and brings tangible value to the community.

That said, I totally understand if this PR isn’t likely to be accepted either for technical or strategic reasons. However, in this case, I’d rather step back than keep chasing changes unnecessarily.

Regardless, thanks again for all the work you do on this project!

[m-paternostro]

👋 Hello @pcarleton,

Hope you had a great week off! We all need to recharge now and then - I’ll actually be off for the next two weeks starting Monday.

If you get a chance to take a look at the changes before Friday and spot anything we should tweak, I’ll do my best to fit it in before I go. Let me know!

[pcarleton]

Hey @m-paternostro sorry for the delay here, this is on my list, just didn't get to it this week.

[pcarleton]

hey @m-paternostro thanks for the patience here. I had a long chat with some other folks (@ihrpr , @dsp-ant, @ochafik ) and we're thinking that an even higher level approach would be better here, and I wanted to see if it'd work for you and if you'd be up for adjusting this PR to tackle it.

It'd look something like this:

  // Simple auth wrapper type
  type FetchWrapper = (fetch: FetchLike) => FetchLike;

  // The default implementation
  const withOAuth = (provider: OAuthProvider): FetchWrapper =>
    (fetch) => async (input, init) => {
      const headers = new Headers(init?.headers);
      const tokens = await provider.tokens();
      if (tokens) {
        headers.set('Authorization', `Bearer ${tokens.access_token}`);
      }

      const response = await fetch(input, { ...init, headers });
      if (response.status === 401) {
          const resourceMetadataUrl = extractResourceMetadataUrl(response);

          const result = await auth(provider, { serverUrl: this._url, resourceMetadataUrl, fetchFn: fetch });
          if (result !== "AUTHORIZED") {
            throw new UnauthorizedError();
          }

          const tokens = await provider.tokens();
          if (tokens) {
            headers.set('Authorization', `Bearer ${tokens.access_token}`);
          }

          return await fetch(input, { ...init, headers });
      }

      return response;
    };


  // Adding a custom wrapper:
  const transport = new StreamableHttpClientTransport(url, {
    fetch: withCustomOAuth(oauthProvider)(withLogging(fetch))
  });

The idea is then we could support any type of custom auth there, or other request/response munging.

Let me know what you think.

[m-paternostro]

Hey @pcarleton - sorry for the delay (was out on PTO as mentioned 😊)

I really like the direction this design is heading. I took a pass at implementing the default OAuth and logging wrappers you suggested. And as you were likely signaling, the logic now feels simple and flexible enough that writing custom wrappers is straightforward - no need for a dedicated CustomAuth type or withCustomOAuth.

Btw, for now I kept everything in a single file under shared - we should probably split it, placing the withOAuth in client.

Let me know your thoughts!

[dsp-ant]

@m-paternostro Thank you. This is really good and nearly where we want it.

I took the liberty to refactor this and call it middleware and move it to client/ to avoid confusion with middleware in servers. I think this fits the common terminology better. Let me know if that works for you.

There is still a lint error around usage of console, which i believe existed in your version. I can take a look but if you get to it before, i'd much appreciate it. I think we are very close to accepting this.

[m-paternostro]

@dsp-ant Great news!

Your changes look good! Some comments:

• Do we need the deprecated types FetchWrapper and FetchMiddleware? I don't see other references to them on the project.
• Should applyMiddleware be applyMiddlewares? You know the naming conventions more than I do.
• The createMiddleware is very nice!

Regarding the lint errors, the offending code is related to providing logging for fetch operations, so probably not related to stdio. Would the use of console.log and console.error be OK or is there a better alternative? Btw, the error does not show up on shared where the code was initially located - the no console rule only applies to the files in client and server.