[rekram1-node]

Problem

MCP OAuth tokens were only refreshed after the server rejected one with a 401. To do that we let the MCP SDK's auth() run the refresh and worked around it: a fetch wrapper recognized refresh requests by their body, a WeakMap routed them to our locked refresh, and the outcome went back to the SDK as fake HTTP responses (200, 400 invalid_grant, 503 temporarily_unavailable) so the SDK would neither sign the user out nor save outside the lock.

Change

Follows how other MCP clients refresh (Pi, Codex, OpenClaw):

• A connection hands the transport the SDK's minimal AuthProvider (token() and onUnauthorized()) instead of a full OAuthClientProvider. The SDK's auth() is only used for the interactive login.
• token() refreshes a token that expires within 30 seconds before sending it (Credential.expiring now takes a margin; provider logins keep 5 minutes). If the refresh fails, the current token goes out and a 401 decides.
• onUnauthorized() refreshes once, only while the stored row still holds the token that was sent, so a token another process already rotated is not spent again.
• The login saves its discovery result (authorization server, its metadata, resource metadata) with the credential, and refreshes use it, so a refresh is a single token request. Logins saved before this, which have no discovery, refresh only after a 401, discovering with its resource_metadata hint as before, and then save it. A configured auth_server_metadata_url is read on every refresh and not saved.
• Both go through Credential.refresh (refactor(core): share OAuth credential refresh between provider logins and MCP #63022). The 30 s limit aborts the request.
• Tokens are only sent to the authorization server that issued them: if discovery names another issuer than the one stored with the credential, nothing is sent and the connection needs auth, keeping the credential, as the SDK did. An OAuth error from the token endpoint is reported by its code only, since its description can quote the whole response.
• invalid_grant, invalid_client and unauthorized_client remove the credential (needs auth). Timeouts, network errors, 429 and 5xx keep it and fail the attempt as before (fix(core): keep MCP OAuth credentials when a refresh fails temporarily #63012).
• Removed: the refresh-request sniffing, the in-process refresh share, the WeakMap, the fake responses, toTokens, and the provider-backed credential store. A 403 insufficient_scope still ends in needs auth.
• Configured headers are no longer sent to the authorization server; they were only sent there on refresh, never at login.

Replaces #63008, which ran the SDK's whole auth() 5 minutes ahead of expiry: that refreshed short-lived tokens (Keycloak and Spring Authorization Server default to 5 minutes) with full discovery on every request, and failed on servers that only name their resource metadata in the 401.

Tests

packages/core/test/mcp-oauth.test.ts, with a real database shared by two instances and fake servers:

• A refused token is refreshed and the request retried. A token within 30 s of expiry is refreshed with the saved discovery (one request) before it is sent; a failed refresh sends the current token; tokens with time left, no lifetime, or no saved discovery are left to the 401.
• A login saved without discovery follows the 401 to its resource metadata and saves it; login saves its discovery.
• Two instances refreshing at once send one request; a token another instance already spent is not sent again; a signed-out credential needs auth without a request.
• 503, unreachable and timed-out refreshes keep the credential (a timeout aborts the request); invalid_grant and missing client information sign out; a 401 pointing at another authorization server sends nothing and keeps the credential; a non-OAuth error body is not quoted; a 502 on one metadata URL falls back to the next; 403 insufficient_scope needs auth.
• Resource selection (no metadata, echoed query, configured authorization server metadata).

Visual

<svg xmlns="http://www.w3.org/2000/svg" width="240" height="72" viewBox="0 0 240 72" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
  <style>
    .bar{opacity:.25}
    .fill{transform-origin:20px 36px;animation:drain 4s linear infinite}
    .key{opacity:0;animation:swap 4s linear infinite}
    @keyframes drain{0%{transform:scaleX(1)}70%{transform:scaleX(.25)}72%{transform:scaleX(1)}100%{transform:scaleX(1)}}
    @keyframes swap{0%,64%{opacity:0}68%,76%{opacity:1}82%,100%{opacity:0}}
    @media (prefers-reduced-motion:reduce){.fill,.key{animation:none}}
  </style>
  <line class="bar" x1="20" y1="36" x2="160" y2="36" stroke-width="10"/>
  <line class="fill" x1="20" y1="36" x2="160" y2="36" stroke-width="10" opacity=".7"/>
  <line x1="55" y1="24" x2="55" y2="48" opacity=".5" stroke-dasharray="3 3"/>
  <g class="key" transform="translate(196 36)">
    <circle r="8"/>
    <path d="M8 0h16M18 0v6M23 0v5"/>
  </g>
</svg>

---

Added by the opencode bot (AI-generated).

Fixes #60269
Fixes #62199

Related: #59109

[opencodejr]

The approach looks right. Using the SDK's minimal AuthProvider with Credential.refresh is much simpler than sniffing refresh requests and faking responses. It also handles both servers that answer an expired token with something other than a 401 and servers that report expiry inside a 200 result.

Checked: on this branch mcp-oauth.test.ts passes (33/33) and tsc -b in packages/core is clean. The same test file on the base fails the tests that refresh ahead of expiry, among others; many of the other failures come from the changed signature, so I'm marking this not verified end to end.

Public API: unchanged. All changes are internal to packages/core; the credential row only gains an optional metadata.resource.

One concern is worth fixing before merge (inline): credentials saved before this change already have an issuer but no resource. Their refresh now skips reading the resource from the server's metadata and sends the configured URL. When the server names a different resource, a strict authorization server rejects the refresh with invalid_target, which keeps the credential and fails every attempt instead of prompting the user to sign in again. A smaller point is also inline: 429 and 5xx now abort discovery too, where the SDK skips a 502.

Fixes #60269
Fixes #62199
Related: #59109

[opencodejr]

Rows saved before this change already have metadata.issuer (the SDK stamps it on saveTokens) but no metadata.resource. With a stored issuer, server.resourceMetadata is undefined, so this falls back to the configured URL. The old path sent the resource from the server's metadata. When a server's metadata names a different resource (e.g. its origin while the config points at /mcp), a strict authorization server answers invalid_target. That code is not in rejections, so the credential is kept and every attempt fails with temporarily_unavailable; the user is never asked to sign in again. Could rows without a stored resource discover it from the server as before (or treat invalid_target as a rejection)? A test with an issuer-but-no-resource row would cover this.

[opencodejr]

This wrapper also covers the metadata lookups (discoverAuthorizationServerMetadata / discoverOAuthServerInfo). The SDK deliberately skips a 502 there and tries the next well-known URL, but now any 429 or 5xx throws first. Discovery can fail where it used to succeed, which also affects rows that discover at refresh time. Limiting the throw to the token request (or leaving discovery responses alone) would keep the old behaviour.

[opencodejr]

Both earlier points are addressed. Rows without a stored resource discover it again, and the 429/5xx short-circuit now only covers the token request, so a 502 on one metadata URL falls back to the next as before. Tests (39/39) and tsc -b in packages/core pass. Public API: unchanged; the stored credential only gains optional metadata.resource and metadata.lifetime.

One new concern (inline): with refresh ahead moved to the background, a token that is already expired is still sent. On servers that answer an expired token with a 401 that is fine, since the 401 joins the refresh. On the servers that motivated this change it is not: one answers 429 (#60269), so that reconnect still fails; another reports expiry in a 200 tool result (#62199), so that call still fails. Both cases happen after an idle gap longer than the 5-minute window, so they stay only partly fixed.

[opencodejr]

Sending the current token while the refresh runs in the background makes sense for a token that is only expiring. When it has already expired (e.g. the first request after the session sat idle past the 5-minute window), this sends a token we know is dead. A 401 then joins the refresh, but servers that answer 429 (#60269) or put the expiry in a 200 tool result (#62199) never send a 401, so that reconnect or tool call still fails, and only the next one gets the new token. Could token() wait for the refresh when current.expires <= now, and keep the background path for tokens that are still valid? A slow authorization server would then only delay requests whose token is already unusable.

[opencodejr]

Threads 1 and 2 are fixed. Rows without a stored resource discover it from the server again, and only the token request short-circuits on 429/5xx. On thread 3: expired tokens are now deliberately left to the 401 instead of refreshed first, so that thread stays open. Servers that never send a 401 for an expired token (#60269, #62199) stay only partly fixed. Nothing else in this push is worth blocking on: not retrying a refresh token that already failed ahead, and keeping the credential when the issuer no longer matches, both look right. Tests (40/40) and tsc -b in packages/core pass. Public API: unchanged.

[opencodejr]

All three earlier points are addressed. Older logins discover again and take the resource from the server's metadata. Only the token request short-circuits on 429/5xx. A due or expired token is now refreshed before it is sent, using the discovery the login saved. One limit remains: logins saved before this change have no saved discovery and still need a 401 first. Servers that answer an expired token with something else (#60269, #62199) keep failing for those users until they log in again. Tests (43/43) and tsc -b in packages/core pass. Public API: unchanged (Credential.expiring gains an optional margin argument, internal to core).

[opencodejr]

The earlier points stay addressed. This push narrows the saved discovery to the authorization server and resource, re-reads that server's metadata on refresh, and refuses to send tokens to a different issuer, keeping the credential. Refresh failures now report only the OAuth error code. Nothing new worth blocking on. Tests (45/45) and tsc -b in packages/core pass. Public API: unchanged.