_handle_refresh_response discards existing refresh_token when server omits it

[oedokumaci]

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

_handle_refresh_response() in src/mcp/client/auth/oauth2.py replaces the stored token object with the parsed refresh response as-is. When the authorization server does not return a new refresh_token in the refresh response, the previously stored refresh_token is lost. After the first successful refresh, can_refresh_token() returns False and all subsequent refreshes fail, forcing full re-authentication.

Per RFC 6749 Section 6, issuing a new refresh token in the refresh response is optional:

"The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token."

The implicit corollary is that if the server does not issue a new refresh token, the client must preserve the existing one.

Many OAuth providers omit the refresh_token from refresh responses by default (e.g., Google, Auth0 without rotation enabled, Okta in persistent token mode). This makes the current behavior a practical issue for a wide range of OAuth servers.

Current Code

async def _handle_refresh_response(self, response: httpx.Response) -> bool:
    ...
    token_response = OAuthToken.model_validate_json(content)

    self.context.current_tokens = token_response  # overwrites old refresh_token
    self.context.update_token_expiry(token_response)
    await self.context.storage.set_tokens(token_response)
    ...

Proposed Fix

Preserve the existing refresh_token when the refresh response omits one:

token_response = OAuthToken.model_validate_json(content)

# Per RFC 6749 Section 6, the server MAY issue a new refresh token.
# If the response omits it, preserve the existing one.
if not token_response.refresh_token and self.context.current_tokens and self.context.current_tokens.refresh_token:
    token_response = token_response.model_copy(
        update={"refresh_token": self.context.current_tokens.refresh_token}
    )

self.context.current_tokens = token_response
...

Related Issues

• Critical Token Refresh Bugs - Prevents Proactive Refresh #1318 - Critical Token Refresh Bugs (token expiry tracking, P1)
• Framework does not handle refreshed tokens correctly #1250 - Framework does not handle refreshed tokens correctly (P1)
• PR SEP-2207: Refresh token guidance #2039 - SEP-2207: Refresh token guidance (adds offline_access scope, does not address preservation)

Python & MCP Python SDK

v1.26.0