fix(mcp): keep the refresh token stable for Google Connected Apps MCP OAuth clients
What
Google's Gemini connector keeps the refresh token it first received and expects every refresh to return that same token (Google's requirement). This server rotated the refresh token on every refresh, so the connector's next refresh presented a retired token and the connection ended.
For an MCP OAuth client whose every registered redirect URI is a Google Connected Apps callback, refresh now:
- returns the presented refresh token and extends its expiry to 30 days after that refresh;
- issues each new access token as a child session row linked to the root session, so earlier access tokens stay valid until their own one-hour expiry (responses can arrive out of order);
- deletes expired children inside the same transaction, so the rows per connection are bounded by the one-hour overlap window.
All other clients keep rotation unchanged.
Stacked on #259 (base fix/mcp-oauth-lost-refresh-response). Land #259 first, then retarget this to main.
Decision for the owner
This is a weaker bearer lifecycle for one client class: a stolen refresh token for a Google callback client is not detected by reuse, because reuse is the normal case. It is limited to clients whose whole redirect set is one of three Google hosts (oauth-redirect, oauth-redirect-sandbox, oauth-redirect-test on googleusercontent.com) with a single /r/<id> or /a/<id> path. Revocation, grant revocation, membership loss and the 30-day idle expiry still end the connection.
Behaviour changes
- Migration 0085 adds
mcp_oauth_sessions.parent_session_id(self-reference,ON DELETE CASCADE) and a child-only partial index. Existing rows keepNULLand are root sessions. - A child session's own refresh token is never returned and is refused if presented (
child_session). - Revoking the refresh token or the grant ends the root and all its children.
- Code replay: continuation detection counts root sessions only. An initial-code replay revokes the grant; a continuation-code replay revokes that continuation's session and its children and leaves the rest of the grant live.
- New refresh log outcome
extended. - Pruning deletes expired child rows. A row that an authorization code points to is never deleted.
Concurrency
Refresh and code redemption (including replay) both take the per-user and per-organisation advisory transaction locks before reading, so a refresh that is adding a child cannot interleave with a replay that revokes the family. No separate family lock is added. The stable refresh itself is one guarded UPDATE on the root row; a refresh that loses to a revoke is refused.
Upgrade notes
- During a rolling upgrade an older replica still rotates the token for these clients. A connection rotated that way is not repaired: the connector must be reconnected once.
- A Google callback connection that an earlier version already rotated must also be reconnected once.
Not changed
- The foreign-
Originguard on the OAuth endpoints is not relaxed. - Dynamic client registration still refuses
token_endpoint_auth_methodother thannoneand over-long or reserved client names. If Gemini registers with another auth method this would make it ask for a client ID and secret; no captured registration request exists to confirm that, so it is left for a follow-up.
Checks
Local, on this head, one at a time:
tsc --noEmit: passmcp-oauth-token-flow: 46/46 (ten new stable-refresh tests)migrations: 11/11- import verifier dry run with the refreshed manifest: 109/109 (manifest diff is the 0085 hash, the column, the foreign key, the index and the seal)
Run before the last two edits (a test-only clock change and the index predicate), source unchanged since: mcp-oauth-protocol 20/20, mcp-oauth-sessions 10 pass + 1 skip, mcp-oauth-store 11/11, mcp-oauth-admission 57/57, mcp-oauth-http 16/16, mcp-oauth-public-handlers 5/5, mcp-oauth-departure 4/4, mcp-oauth-oidc 6/6, grok-routines 21/21, mcp 61/61.
Not covered by tests: two stable refreshes racing in separate connections, single-tenancy mode on the stable path, and the rolling-upgrade case.
🤖 Generated with Claude Code

Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
Stops rotating refresh tokens for MCP OAuth clients whose every registered redirect URI is a Google Connected Apps callback; Google's connector expects the same refresh token back on every refresh, and rotation made it present a retired token on the next refresh, ending the connection. For those clients, refresh returns the presented refresh token, extends its expiry to 30 days after that refresh, and issues the new access token as a child session row linked to the root session, so earlier access tokens stay valid until their own one-hour expiry. All other clients keep rotation.
Behavior changes
- Migration 0085 adds
mcp_oauth_sessions.parent_session_id(self-reference,ON DELETE CASCADE) and a child-only partial index; existing rows stay NULL as root sessions. - A child session's refresh token is never returned and is refused if presented; expired children are deleted on the next refresh.
- Revoking the refresh token or the grant ends the root session and all its children; a replayed continuation code revokes only that session and its children.
- Continuation detection counts root sessions only, and new refresh log outcome is
extended. - This is a weaker bearer lifecycle for one client class: a stolen refresh token is not detected by reuse, and undelivered-response recovery does not apply, so it is limited to the Google callback set.
Upgrade notes
- A Google callback connection whose refresh token a previous version already rotated must be reconnected once; during a rolling upgrade an older replica still rotates and that connection is not repaired.