Skip to content

feat(mcp-adapters): accept token AuthProviders and keep auth failures retryable - #11720

Merged
Hunter Lovell (hntrl) merged 10 commits into
mainfrom
mcp-oauth-providers
Sep 27, 2026
Merged

Hunter Lovell (hntrl) merged 10 commits into
mainfrom
mcp-oauth-providers

Conversation

@byhow

@byhow Baihao Wang (byhow) commented Sep 24, 2026 •

Copy link
Copy Markdown
Member

This is the first of two stacked PRs adding OAuth to @langchain/mcp-adapters 2.0. It does four things:

  • moves the adapter to MCP SDK 2.1;
  • accepts the SDK's token-based AuthProvider;
  • labels authentication failures correctly;
  • lets servers that failed on authentication be retried.

It also documents these changes in the README. The follow-up PR, stacked on this one, adds finishAuth to complete an OAuth redirect.

Merging this releases nothing. @langchain/mcp-adapters is still in the changesets ignore list (#11715).

966 changed lines: implementation 143, tests 738 (of which the OAuth server fixture is 320), README 18, lockfile 67.

MCP SDK 2.1 replaces the header workaround

In SDK 2.0, a configured Authorization header and the provider's token were sent joined into one value, Bearer <provider>, Bearer <configured>. #11663 worked around this with getSdkHeaderCase. SDK 2.1.0 (modelcontextprotocol/typescript-sdk#2475) fixes it upstream by matching the transport's own Authorization case-insensitively, so the workaround is deleted rather than kept alongside.

The SDK's fix also decides which value wins, and it picks the opposite of what #11663 did:

  • once the provider has a token, that token replaces a configured Authorization;
  • until then, the configured header is sent.

We follow the SDK instead of patching over it. This order is also the useful one: a static API key works until an OAuth login completes, then the OAuth token takes over. The header tests now pin both cases.

@modelcontextprotocol/client and core now require ^2.1.0. The dev-only server packages move to ^2.1.0 with them.

Token providers

authProvider now accepts the SDK's minimal AuthProvider, { token(), onUnauthorized?() }, as well as an OAuthClientProvider. The adapter hands it to the transport unchanged:

  • the SDK calls token() before each request;
  • on a 401, it calls onUnauthorized() once, then retries.

This covers tokens the application already manages, without implementing the whole OAuth client interface. AuthProvider is exported as a type.

Authentication failures

When a provider-driven flow fails, the SDK throws UnauthorizedError. That error carries no HTTP status, so the old code === 401 check missed it. The new isAuthenticationError recognizes either UnauthorizedError or a 401, on the error itself or up to three levels down its cause chain. The depth matters because the legacy HTTP→SSE fallback wraps the SSE 401 twice. Both the HTTP and SSE paths now use it.

As a result, a provider auth failure:

  • gets the authentication error message;
  • keeps the SDK error as cause;
  • in legacy mode, does not fall back to SSE.

Tests pin this on both transports. UnauthorizedError is exported so callers can check the cause.

Auth failures stay retryable

Discovery used to add every server that failed to connect to #failedServers, which skips that server for the rest of the adapter's lifetime. After a 401, completing the login couldn't bring the server back without creating a new adapter.

Now:

  • auth failures stay out of #failedServers, so the next discovery retries them;
  • unreachable servers and a throwing token() still stay blocked;
  • onConnectionError still runs for every failure.

Docs

Testing

  • pnpm --filter @langchain/mcp-adapters test: 463 passed, 2 skipped, no type errors. oxlint and oxfmt report no issues.
  • The OAuth tests run the real SDK client transport against a real in-process authorization server (src/tests/fixtures/oauth-server.ts). The SDK is not mocked. The server is built from the SDK's own mcpAuthRouter and requireBearerAuth and supports:
    • dynamic client registration;
    • PKCE;
    • RFC 9207 iss, which can be sent, omitted or unsupported;
    • token refresh;
    • RFC 9728 resource metadata for both /mcp and /sse.
  • A test reproduces the double-wrapped legacy HTTP→SSE fallback and checks the server is retried. It fails when isAuthenticationError checks only one cause level.
  • In the stack's mutation run, deliberately reverting the token-provider, auth-labeling or retry change each made its tests fail.

@changeset-bot

changeset-bot Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 0990900

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@socket-security

socket-security Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Updated@​modelcontextprotocol/​server-legacy@​2.0.0 ⏵ 2.1.099 +2110086 +150100
Updated@​modelcontextprotocol/​client@​2.0.0 ⏵ 2.1.092 -210084 +190 -4100
Updated@​modelcontextprotocol/​server@​2.0.0 ⏵ 2.1.0100 +110085 +195100
Updated@​modelcontextprotocol/​core@​2.0.0 ⏵ 2.1.010010085 +190 -4100
Updated@​modelcontextprotocol/​node@​2.0.0 ⏵ 2.1.0100 +110093 +195 +4100

View full report

@robin-agent robin-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open SWE Review found 3 potential issues.

Open in Web • View Open SWE trace

oxfmt 0.65.0 (the version CI runs) wraps a few long expect() lines in
src/tests/oauth.test.ts differently than the file was written; the
"Check formatting" CI job fails on the drift. Run oxfmt over the file
to match its output exactly.
isAuthenticationError only checked an error and its direct cause, but
the legacy HTTP->SSE fallback in _initializeStreamableHTTPConnection
wraps _initializeSSEConnection's own MCPClientError (whose cause is the
SSE transport's 401) in another MCPClientError. That put the real
signal two `.cause` hops down, so onConnectionError misclassified the
failure as non-auth and #discoverToolsets added the server to
#failedServers for the adapter's lifetime instead of retrying it on the
next discovery.

Walk the cause chain with a small depth bound instead of
checking just one hop. Add a regression test that reproduces the
double-wrapped legacy-mode fallback through the real in-process OAuth
fixture and asserts the server stays retryable.

_loadToolsForServer's own wrap of a failed client.listTools() was also
suspected of needing a multi-hop walk, but every reachable failure
there (bare {token} provider, onUnauthorized retry that still 401s, or
an OAuthClientProvider's adapted onUnauthorized) arrives as a single,
directly-recognizable UnauthorizedError or 401-carrying SdkHttpError -
confirmed empirically against the real fixture - so the pre-existing
one-hop check already classified it correctly and no second reachable
path exists there today.
Drop the httpOptionsSchema authProvider JSDoc's dangling reference to
MCPAdapter#finishAuth, which lands in the upper mcp-oauth PR and
doesn't exist on this branch.

Bring the README's Authentication section and the pending
mcp-adapters-sdk-2 changeset up to date with what this PR actually
adds: the AuthProvider ({ token, onUnauthorized? }) shape alongside
OAuthClientProvider, and provider-token-over-configured-header
precedence. Wording is kept identical to the upper branch's final text
(minus its finishAuth/pending-login additions, which belong there, not
here) so integrating this branch into it stays a no-op for these
sections.
Co-authored-by: Hunter Lovell <[email protected]>
Signed-off-by: Hunter Lovell <[email protected]>
@github-actions github-actions Bot added the ready label Sep 27, 2026
@hntrl
Hunter Lovell (hntrl) merged commit 13283cd into main Sep 27, 2026
25 checks passed
@hntrl
Hunter Lovell (hntrl) deleted the mcp-oauth-providers branch September 27, 2026 06:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants