Skip to content

OAuth client-side token-refresh bug #2862

Closed

Description

@lgndluke

Description

Summary:

@jlowin I think I found an issue that prevents clients from correctly refreshing tokens.
However, I am unsure whether this is a FastMCP, or MCP-SDK issue. (I guess its more MCP-SDK related though)

Details:

The problem is caused by how the _initialize() method within the OAuth class in "/client/auth/oauth.py" handles the recalculation of the self.context.current_tokens.expires_in value, which in turn causes the self.context.token_expiry_time to be wrong.

    async def _initialize(self) -> None:
        """Load stored tokens and client info, properly setting token expiry."""
        # Call parent's _initialize to load tokens and client info
        await super()._initialize()

        # If tokens were loaded and have expires_in, update the context's token_expiry_time
        if self.context.current_tokens and self.context.current_tokens.expires_in:
            self.context.update_token_expiry(self.context.current_tokens)

The crucial part about this:

The update_token_expiry() method internally calls the calculate_token_expiry() method with the self.context.current_tokens.expires_in value, which returns time.time() + int(expires_in) as the self.context.token_expiry_time.

Simple example why this is problematic:

  • Access-Token: valid for e.g.: 5 minutes - has expired.
  • Refresh-Token: valid for e.g.: 30 minutes - is still valid and could be used to obtain a new valid access-token.

The way the calculate_token_expiry() method handles things it would add the 5 minutes to the time.time()'s value which would in turn mean the access-token is seen as valid, although it had already previously expired. Hence, preventing the auth_flow() method from performing a token refresh.

Example:

**Values fetch from Token Storage:**
Access Token: <Expired_Access_Token>
Expires in (old): 300
Refresh Token: <Active_Refresh_Token>

Token Expiry Time (old): None

Updated Token Expiry after update_token_expiry() call in _initialize()
Expires in (new): 300

Token Expiry Time (new): 1768302705.0777717 

The new token expiry time is thereby set in the future. 
As mentioned above, this is critical as it indicates the auth_flow to recognize 
the access-token as valid, instead of the access-token being invalid and the 
client silently performing a token-refresh.

Impact of this issue:

Whenever the access-token expires the user has to re-authenticate with the MCP-Client instead of the MCP-Client performing a Token-Refresh.

Example Code

async def _initialize(self) -> None:
        # Call parent's _initialize to load tokens and client info
        await super()._initialize()

        Logger.info('Values fetch from Token Storage:')
        Logger.info('Access Token: {}'.format(self.context.current_tokens.access_token))
        Logger.info('Expires in (old): {}'.format(self.context.current_tokens.expires_in))
        Logger.info('Refresh Token: {}'.format(self.context.current_tokens.refresh_token))
        Logger.info('Token Expiry Time (old): {}'.format(self.context.token_expiry_time))

        # If tokens were loaded and have expires_in, update the context's token_expiry_time
        if self.context.current_tokens and self.context.current_tokens.expires_in:
            self.context.update_token_expiry(self.context.current_tokens)
            Logger.info('Updated Token Expiry:')

        Logger.info('Expires in (new): {}'.format(self.context.current_tokens.expires_in))
        Logger.info('Token Expiry Time (new): {}'.format(self.context.token_expiry_time))

Version Information

FastMCP version:                                                                     2.14.3
MCP version:                                                                         1.25.0
Python version:                                                                      3.13.7
Platform:                                                         Windows-11-10.0.26200-SP0
FastMCP root path:                                                 \.venv\Lib\site-packages

Activity

  1. added
    bugSomething isn't working. Reports of errors, unexpected behavior, or broken functionality.
    on Jan 13, 2026
  2. added
    authRelated to authentication (Bearer, JWT, OAuth, WorkOS) for client or server.
    clientRelated to the FastMCP client SDK or client-side functionality.
    on Jan 13, 2026
  3. lgndluke commented on Jan 20, 2026

    @lgndluke
    ContributorAuthor

    @jlowin What do you think about this?

  4. jlowin commented on Mar 7, 2026

    @jlowin
    Member

    Cross-referencing from #3425 (Codex security scan found the same bug independently).

    Root cause confirmed: _initialize() at src/fastmcp/client/auth/oauth.py:287-288 calls update_token_expiry(tokens) which computes time.time() + expires_in. But expires_in is a stale relative value from the original token issuance, not from now.

    Suggested fix: Store an absolute expires_at = time.time() + expires_in timestamp at cache write time in set_tokens(), and use that on reload instead of re-interpreting the relative expires_in:

    async def set_tokens(self, tokens: OAuthToken) -> None:
        expires_at = None
        if tokens.expires_in:
            expires_at = time.time() + tokens.expires_in
        await self._storage_oauth_token.put(
            key=self._get_token_cache_key(),
            value={"tokens": tokens, "expires_at": expires_at},
            ttl=60 * 60 * 24 * 365,  # keep 1-year TTL for refresh token persistence
        )

    Then in _initialize(), check expires_at against time.time() rather than calling update_token_expiry with the stale expires_in.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    authRelated to authentication (Bearer, JWT, OAuth, WorkOS) for client or server.bugSomething isn't working. Reports of errors, unexpected behavior, or broken functionality.clientRelated to the FastMCP client SDK or client-side functionality.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions