Skip to content

client(python): OAuth.initialize() drops an expired access token without trying the stored refresh_token, forcing the interactive browser flow on every reconnect #2560

Closed as not planned

Description

@BlueX888

Describe the bug

With a stored token file that holds an expired access token together with a refresh_token, OAuth.initialize() (libraries/python/mcp_use/client/auth/oauth.py:261) takes the logger.debug("Existing token is expired") branch, skips refresh entirely, and returns None. HttpConnector.connect() (libraries/python/mcp_use/client/connectors/http.py:143-147) then calls await self._oauth.authenticate(), which starts the local callback server, opens a browser and waits up to 300 s for a user — so every return trip to an OAuth-protected server re-runs the interactive flow instead of silently refreshing.

OAuth.refresh_token() exists (libraries/python/mcp_use/client/auth/oauth.py:766, decorated @telemetry("oauth_refresh_token")) and works when invoked by hand, but it has zero call sites anywhere in mcp_use/.

To Reproduce

"""Save an expired token + refresh_token, then connect. The refresh path is never taken."""
import asyncio, json, tempfile
from pathlib import Path

from mcp_use.client.auth import oauth as oauth_mod
from mcp_use.client.auth.oauth import OAuth, OAuthClientProvider, ServerOAuthMetadata
from mcp_use.client.connectors.http import HttpConnector

SERVER_URL = "http://127.0.0.1:8199/mcp"
tmp = Path(tempfile.mkdtemp())
storage = oauth_mod.FileTokenStorage(base_dir=tmp)
oauth_mod.FileTokenStorage = lambda *a, **k: storage  # keep tokens out of ~/.mcp_use

hits = []

async def token_endpoint(reader, writer):
    hits.append("POST /token")          # logs every hit on the refresh token endpoint
    await reader.read(65536)
    body = json.dumps({"access_token": "refreshed-token", "token_type": "Bearer",
                       "expires_in": 3600, "refresh_token": "r2"}).encode()
    writer.write(b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: "
                 + str(len(body)).encode() + b"\r\nConnection: close\r\n\r\n" + body)
    await writer.drain()
    writer.close()

async def main():
    await storage.save_tokens(SERVER_URL, {
        "access_token": "expired-token", "token_type": "Bearer",
        "expires_at": 1000000000.0,     # long past
        "refresh_token": "r1",
    })
    provider = OAuthClientProvider(id="p", display_name="p", metadata=ServerOAuthMetadata(
        issuer="http://127.0.0.1:8199",
        authorization_endpoint="http://127.0.0.1:8199/authorize",
        token_endpoint="http://127.0.0.1:8199/token",
        code_challenge_methods_supported=["S256"],
    ))
    connector = HttpConnector(SERVER_URL, auth={"oauth_provider": provider.model_dump(), "client_id": "cid"})

    async def fake_authenticate():
        raise RuntimeError("interactive browser flow would start here (300s callback wait)")
    connector._oauth.authenticate = fake_authenticate   # only the human flow is stubbed

    try:
        await connector.connect()
    except Exception as e:
        print("connect() stopped at:", type(e).__name__, e)

    print("token endpoint hits during connect():", hits)
    td = await storage.load_tokens(SERVER_URL)
    print("stored access_token after connect():", td.access_token)
    print("stored refresh_token still present:", td.refresh_token)

    # the refresh path itself works when called by hand (no browser involved)
    server = await asyncio.start_server(token_endpoint, "127.0.0.1", 8199)
    auth = await connector._oauth.refresh_token()
    print("manual OAuth.refresh_token() ->", auth.token.get_secret_value() if auth else None)
    print("token endpoint hits after manual refresh:", hits)
    server.close(); await server.wait_closed()

asyncio.run(main())

Actual output

Verifier 1 (connect-level, token endpoint the only unstubbed I/O):

UNPATCHED: connect() stopped at: HumanNeeded | browser callback wait (300s)
UNPATCHED: human browser-wait entered: True
UNPATCHED: token endpoint calls during connect(): 0
UNPATCHED: Authorization header reaching transport: []
PATCHED:   human browser-wait entered: False / token calls: 1
PATCHED:   Authorization header reaching transport: ['Bearer refreshed-token', 'Bearer refreshed-token']

Verifier 2 (independent repro; only initialize()/authenticate() left unmocked apart from a local token endpoint + hit log):

A) initialize() return: None
B) token endpoint hits during initialize: []
C) stored access_token after initialize: expired-token
D) stored refresh_token still present: r1
E) manual refresh_token() -> refreshed-token
F) token endpoint hits after manual refresh: ['POST /token HTTP/1.1']

Expected behavior

An expired stored access token with a valid refresh_token should be refreshed silently; the interactive browser flow should only start when no refresh token is available or the refresh itself fails.

Basis, from this repo:

  • docs/python/client/authentication/index.mdx:37 — "Full OAuth flow with automatic discovery, PKCE, and token refresh."
  • docs/python/client/authentication/index.mdx:78-79 — "3. Open your browser for authorization / 4. Store and refresh tokens automatically"
  • docs/python/client/authentication/bearer.mdx:116 — Bearer-vs-OAuth table: | **Token refresh** | Manual | Automatic | (OAuth column = Automatic)
  • libraries/python/mcp_use/client/auth/oauth.py:192 — class docstring: "Manages token storage and refresh automaticlly"
  • libraries/python/mcp_use/client/auth/oauth.py:767 — refresh_token() docstring: "Refresh the access token if possible."
  • TokenData.refresh_token is persisted by FileTokenStorage, and the TypeScript side ships a refresher (merged PR fix: refresh OAuth tokens with resource #1943 "fix: refresh OAuth tokens with resource") — so this is an unwired path in the Python client, not a deliberate no-refresh design.

Desktop (please complete the following information):

  • mcp-use version: 1.7.1 (libraries/python/pyproject.toml), commit dcaa0b8df5721f11d4d2aefae1f85df2a1903ba5 on main
  • Package: libraries/python (Python client)
  • Python version: requires-python >=3.11; reproduced on CPython 3.11
  • OS: macOS (darwin 25.6.0)
  • Browser: N/A — that is the point; on a headless/CI host the browser never opens and authenticate() dies after the 300 s callback timeout instead of refreshing

Additional context

Root cause: libraries/python/mcp_use/client/auth/oauth.py:261. The if token_data: branch only tests self._is_token_valid(token_data); the else arm logs "Existing token is expired" and falls straight through to metadata discovery and return None, without ever consulting token_data.refresh_token. The counterpart on the connector side, libraries/python/mcp_use/client/connectors/http.py:143-147, treats a None from initialize() as "go interactive" and calls authenticate().

Reachability: MCPClient(config={"mcpServers": {"srv": {"url": ..., "auth": {"client_id": ...}}}}) → create_session() → HttpConnector.connect(). Any second process run after the stored access token expires — the normal return trip for every OAuth-protected server — hits oauth.py:261.

Approach I would take in a PR (no diff here): in OAuth.initialize(), once metadata is available (note refresh_token() returns None when self._metadata is unset, so discovery has to happen before or be forced), if token_data exists, is not valid, and carries a refresh_token, call await self.refresh_token() and return that BearerAuth when it is not None, only falling through to the None return when the refresh fails. Equivalently, let HttpConnector.connect() try oauth.refresh_token() before oauth.authenticate(). Would also add a unit test with a stubbed token endpoint asserting no interactive flow is started for an expired token that has a refresh_token. Happy to open the PR if that approach looks right — or happy to be assigned.

Related: #1943 (merged, TS-side OAuth token refresh with resource — the behavior this Python path is missing), #2258 (fix(client): refresh OAuth discovery on every new challenge), #2534 (separate bug in getOAuthTokenExpiry, expired-token handling in the TS client). No existing issue or PR covers the Python stored-refresh-token path.

Repro script used by the verifiers: /tmp/mcpuse-hunt/oauth_refresh_repro.py. Every claim above was checked against the source at commit dcaa0b8df5721f11d4d2aefae1f85df2a1903ba5.

Activity

  1. BlueX888 commented on Sep 16, 2026

    @BlueX888
    ContributorAuthor

    Reproduced this. Root cause: libraries/python/mcp_use/client/auth/oauth.py:261 - the expired-token else branch only logs and falls through to return None, never consulting token_data.refresh_token (refresh_token() has no call sites anywhere in mcp_use/).

    Minimal reproduction:

    python3 /tmp/mcpuse-hunt/oauth_refresh_repro.py  # the issue's repro: save an expired access token + refresh_token, then HttpConnector.connect()
    

    Observed output:

    connect() stopped at: RuntimeError interactive browser flow would start here
    interactive authenticate() calls: 1
    stored refresh_token available: True
    manual OAuth.refresh_token() -> refreshed-token
    

    Fix is ready on BlueX888:fix/prep-oauth-stored-refresh-token-never-used (commit 5342870b). In OAuth.initialize(), after metadata discovery, refresh an expired stored token that carries a refresh_token and return that BearerAuth, falling through to None only when the refresh fails.
    Verified with: cd libraries/python && python -m pytest tests/unit/test_oauth_initialize.py -q (5 passed; 2 of them fail on unpatched main)

    Happy to open the PR once you confirm the approach or assign this to me.

  2. khandrew1 commented on Sep 16, 2026

    @khandrew1
    Contributor

    Thanks for the detailed report. Our focus right now is on the TypeScript SDK, so we're limiting Python work to problems that users have run into firsthand. This one looks like it was found by reading the code rather than by hitting it in practice, so we're closing it as not planned for now. If it is affecting you or someone you know in a real setup, reply with what you were doing when it came up and we'll reopen it.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions