[kohjunhao]

When a refresh fails with invalid_grant or invalid_dpop_proof, auth() no longer sends that refresh token to the token endpoint again, in the immediate retry or in later auth() calls. It goes straight to a new authorization request until a different refresh token is stored.

Refs #2915 (this is its second half; the concurrent-refresh half is #1760, handled by #2757)

Motivation and Context

auth() treats invalid_grant as recoverable: it warns, calls provider.invalidateCredentials?.('tokens') and retries authInternal. invalidateCredentials is optional. When a provider does not implement it, tokens() still returns the refresh token the authorization server just rejected, so the retry refreshes with it again, gets invalid_grant again, and that second error reaches the caller. The warning says "retrying authorization", but authorization is never reached, and the session stays unusable until the user reconnects.

Sending the same refresh token again cannot succeed (RFC 6749 §5.2: the grant "is invalid, expired, revoked, ..."), and the MCP authorization spec requires refresh token rotation for public clients.

The fix records the rejected refresh token per provider (a WeakMap keyed on the provider object) when the refresh fails with invalid_grant or invalid_dpop_proof, and skips the refresh branch while tokens() still returns that token. The retry and any later auth() call therefore start a new authorization request, which is what the warning and the v2 migration guide ("invalid_grant ... are still recovered by discarding stored credentials and retrying") already describe. Once a new authorization or another writer saves a different refresh token, it is refreshed as usual. Only a refresh failure records the token, so an invalid_grant from a code exchange is unaffected. invalid_client and unauthorized_client keep their current retry: skipping the refresh would not help there, since the retry would still authorize with the client credentials the server just rejected.

How Has This Been Tested?

• Updated the auth() unit test that pinned the old outcome (added in fix(client/auth): propagate saveTokens errors after refresh #2053). It now expects 'REDIRECT', one token request instead of two, and one redirectToAuthorization() call. On main it fails with OAuthError: Refresh token expired, thrown from the retry.
• Added does not resend a rejected refresh token on a later auth() call either: two auth() calls against the provider without invalidateCredentials() make one token request in total. It fails with the retry-only fix (two requests).
• Added refreshes again once a different refresh token is stored after a rejection.
• The tests that cause a rejection use their own provider object, so the remembered token cannot leak into later tests that share mockProvider.
• Updated the SSE transport test for invalid_grant during refresh. Its mock invalidateCredentials() clears nothing, so it was asserting the same replay. It now expects UnauthorizedError after one redirect.
• Rebased on main (8 Nov). On Node 22: the client package's 1,080 tests pass, and the pre-push hook's pnpm typecheck:all, pnpm lint:all and pnpm build:all pass. Earlier, on Node 24: pnpm typecheck:all, pnpm lint:all, pnpm build:all, pnpm check:all, node scripts/smoke-dist-types.mjs, pnpm test:all, pnpm test:conformance:client:all and the 2026 client conformance suite pass. The only test:all failure was protocol:timeout:max-total [sse] in the e2e package, which also fails intermittently on unmodified main and has no auth in it.

Breaking Changes

Providers that implement invalidateCredentials() see no change, because their tokens are already gone when the retry runs. For providers that do not, auth() now returns 'REDIRECT' after invalid_grant instead of throwing OAuthError, and the transports throw UnauthorizedError. If another caller saved a newer refresh token between the failure and the retry, the retry still refreshes with it, as before.

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

#2757 moves the body of auth() into a new function, so whichever PR lands second needs a one-line rebase.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6cc5dd8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/client	Patch
@modelcontextprotocol/codemod	Patch
@modelcontextprotocol/core	Patch
@modelcontextprotocol/server-legacy	Patch
@modelcontextprotocol/server	Patch
@modelcontextprotocol/core-internal	Patch

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@2924

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@2924

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@2924

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@2924

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@2924

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@2924

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@2924

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@2924

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@2924

commit: 6cc5dd8

[soyeladice-svg]

This stops the immediate second refresh attempt, but for a provider without invalidateCredentials() it does not actually stop the rejected token from being replayed on the next auth() call.

The new forceReauthorization: true exists only in the recursive retry. The provider still stores the dead refresh token, so a later:

auth(provider, originalOptions)

starts again with forceReauthorization === false, reads the same token from tokens(), and sends it to the token endpoint once more before falling back to authorization.

That is particularly visible for the headless/no-op redirect case the warning already discusses, or any transport/application that retries auth before a fresh authorization callback has replaced the stored tokens.

If the intended guarantee is "do not resend a refresh token after this process has observed invalid_grant/invalid_dpop_proof", could the provider/session layer keep an in-memory rejected-token marker until new tokens are saved? Otherwise I would narrow the changeset/title to "avoid the immediate retry" because cross-call replay still occurs by design.

A regression calling auth() twice against the no-invalidateCredentials provider would expose the distinction.

AI-assisted review; checked the current head and auth retry/token-loading path before posting.

[GollyJer]

It would be great to get this in. It's affecting downstream applications such as MCPHub.

[kohjunhao]

@soyeladice-svg you're right, the retry flag only covered the immediate retry. Changed it to what you suggested: auth() now remembers the refresh token that was rejected with invalid_grant / invalid_dpop_proof, per provider, and skips the refresh while tokens() keeps returning it. That covers the retry and later auth() calls, and the forceReauthorization change on the retry is gone. A different stored refresh token refreshes as usual.

Added the regression you described (two auth() calls against the provider without invalidateCredentials(), one token request in total; it fails with the earlier version) plus one for a replaced token. Also rebased on main.