Client should silently refresh access tokens on 401 when a refresh token is available #2031

The MCP HTTP client should automatically perform an OAuth 2.1 refresh_token grant when a remote MCP server returns HTTP 401 with WWW-Authenticate: Bearer error="invalid_token", and retry the original request — without surfacing the failure to the model or requiring user reauthentication.

This complements SEP-2207 (OIDC-flavored refresh token guidance), which standardized how clients request refresh tokens via offline_access. SEP-2207 stops at issuance; it does not specify how the client should use the refresh token on 401. That's the gap this issue addresses.

Context: how this surfaces today

I maintain a remote MCP connector for Power BI / Azure Data Factory analytics. The connector:

• Requests offline_access at sign-in (per SEP-2207) — refresh token IS issued by the Entra Authorization Server.
• Returns HTTP 401 with WWW-Authenticate: Bearer resource_metadata="<RFC 9728 URL>", error="invalid_token", error_description="The access token expired" when the bearer is past exp. (Per RFC 6750 §3.)
• Publishes Protected Resource Metadata at /.well-known/oauth-protected-resource/mcp.

So all four spec-compliant prerequisites are met:

1. Server returns 401 (not 403, not 200-with-error)
2. Server includes WWW-Authenticate: Bearer error="invalid_token"
3. Server publishes RFC 9728 Protected Resource Metadata
4. Client has a refresh token from offline_access at sign-in

Despite this, in some Claude client sessions, the 401 propagates to the model as a tool error and the user has to manually reauth. In other sessions (Claude Desktop with a fresh access token in cache), tool calls go through cleanly — but I have no way to confirm whether the silent-refresh path is exercised, since I haven't been able to force expiry deterministically.

Reproduction

1. Configure a remote MCP server that meets the four prerequisites above.
2. Sign into the server through the MCP client.
3. Wait for the access token to age past exp (typically 60 minutes for Entra).
4. Issue a tool call.

Observed: the 401 is sometimes surfaced to the model as a tool error.

Expected: the MCP HTTP client framework intercepts the 401, performs grant_type=refresh_token against the AS token endpoint, retries the original request with the new access token, and returns the success result to the model. The user sees nothing.

Proposed behavior in the SDK

When the MCP HTTP transport receives a 401 from a remote MCP server:

1. Parse the WWW-Authenticate header.
2. If error="invalid_token" AND a stored refresh token exists for that connector:
   1. POST to the AS token endpoint with grant_type=refresh_token, refresh_token=<stored>, client_id=<from registration>. Use the AS's token_endpoint from its OAuth metadata (already discoverable per SEP-2207 path).
   2. On 200: replace stored access_token + refresh_token (Entra rotates refresh tokens), and re-issue the original tool call with the new access token. Preserve the original tool_use_id.
   3. On 4xx (refresh token expired/revoked): surface a structured needs_reauth error to the model so the user is prompted via the Connectors UI.
3. Else (no error="invalid_token", or no refresh token available): surface the original 401 to the model.

The retry must be capped at 1 attempt per request to prevent infinite loops if the AS keeps rejecting.

Why this matters

1. User experience. Mid-session reauth interrupts a working tool flow for a token-lifecycle reason that OAuth 2.1 + RFC 6750 were specifically designed to hide.
2. B2B deployments. Enterprise users running multi-hour sessions hit access-token expiry routinely. Each one becoming a manual reauth is operational noise, not a security event.
3. Spec alignment. SEP-2207 already mandates that clients request refresh tokens; if the SDK doesn't use them on 401, the SEP-2207 work is half-finished from a UX perspective.
4. Precedent in the local-MCP path. stdio MCP servers using MSAL / Azure CLI credentials already refresh transparently. Remote MCP behavior should match.

Out of scope for this issue

• The MCP spec itself. SEP-2207 already covers issuance; a new SEP could be written for refresh-on-401 behavior. This SDK issue takes the simpler path: implement the documented-but-not-spec-mandated client convention in the reference SDK.
• Server-side caching of user refresh tokens. Servers should not store user refresh tokens; this proposal is purely about client-side token use.

Server-side checklist (for SDK maintainers triaging)

For silent refresh to work end-to-end, the server must:

• Return 401 with WWW-Authenticate: Bearer error="invalid_token" per RFC 6750 §3.
• Publish RFC 9728 Protected Resource Metadata.
• Have requested offline_access at sign-in (per SEP-2207) so a refresh token was issued.

If those are in place, the SDK's behavior should be deterministic.

Happy to help

I have a spec-compliant repro server and packet captures. Happy to share if useful for SDK-side testing.