Skip to content

fix(mcp): recover an MCP OAuth refresh whose response never reached the client - #259

Open
agent-relay-code[bot] wants to merge 2 commits into
mainfrom
fix/mcp-oauth-lost-refresh-response
Open

agent-relay-code[bot] wants to merge 2 commits into
mainfrom
fix/mcp-oauth-lost-refresh-response

Conversation

@agent-relay-code

@agent-relay-code agent-relay-code Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

What

A hosted MCP connector lost its connection roughly a day after each reconnect: a timeout, then HTTP 401 on every call until the user reconnected.

A refresh rotates the token pair before the response is written. When that response never reaches the client and the client retries with the refresh token it still holds more than 30 seconds later, the server treated the retry as refresh-token reuse and revoked the whole grant. This is the self-hosted twin of the same fix on the hosted edition, and it follows the same rules.

Change

  • Each rotation records the exact successor refresh-token hash and the retired token's own expiry on the retired-token row.
  • Bearer admission records the first authenticated use of each pair (mcp_oauth_sessions.current_pair_used_at). Rotation clears it.
  • A retired refresh token is recoverable when its client and resource match, the grant is live, its recorded successor pair has never been used as a bearer token, its own expiry has not passed, and at most 36 hours have passed since the first rotation. The server then rotates the undelivered pair again, under a row lock, and returns the new pair on the same grant, agent identity and scopes. The re-issued pair keeps its refresh expiry, so recovery never extends the grant.
  • A retry within 30 seconds of the rotation, or within 30 seconds of a recovery, is refused with invalid_grant and revokes nothing (two retries racing each other).
  • Reuse of a retired token whose successor pair was used still revokes the grant, as before.
  • Each refresh decision is logged as mcp_oauth_refresh with an outcome and reason and no token material.

Behaviour changes to review

  1. Migration 0084 adds mcp_oauth_sessions.current_pair_used_at and, on mcp_oauth_retired_refresh_tokens, successor_token_hash, refresh_token_expires_at and reissued_at. All nullable, no backfill. The verifier schema manifest is refreshed in its own commit.
  2. Revocation endpoint: revoking a retired refresh token now ends its grant (before, an unknown-token no-op). A client mismatch is still ignored.
  3. Bearer admission fails closed on a lost race: a request whose access token was rotated or re-issued away between the session read and the first-use mark is refused with 401 instead of being admitted on the old pair. Without this an unused pair could be both used and re-issued.
  4. Kept difference from the hosted edition: a retired token presented by the wrong client is answered invalid_grant, and one for the wrong resource invalid_target, in both cases without revoking and before the 30-second check. The hosted edition revokes on such a mismatch after 30 seconds. This keeps the existing self-hosted answers.
  5. Rolling upgrade: pairs rotated before the upgrade have no recorded successor and are never re-issued, so they keep the previous behaviour. During a rolling upgrade an old replica does not mark first use; a pair first used only through an old replica can be re-issued once by a new one. Run the migration before the new image, as usual.

The agent identity and the relay inbox position are untouched: recovery keeps the grant, and both are bound to the grant.

Checks

Local, on this head, one suite at a time:

  • tsc --noEmit: pass
  • test/mcp-oauth-token-flow.test.ts: 36/36 (20 new cases: a lost response is re-issued, and re-issued again when that response is lost too; a retry racing a recovery or the rotation is refused without revoking; two concurrent recoveries; recovery refused once the successor pair was used, past 36 hours, past the retired token's own expiry, for another client id, and for a retired row from before the upgrade; only the exact successor session is re-issued on a grant with several sessions; re-issue keeps the refresh expiry; revoking a retired token ends its grant)
  • test/mcp-oauth-sessions.test.ts: 10 pass, 1 skipped
  • mcp-oauth-admission 57/57, mcp-oauth-store 11/11, 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, migrations 11/11, mcp 61/61
  • Import verifier dry run against PostgreSQL 15 with the refreshed manifest: 109/109. The manifest diff is the 0084 hash, the four new columns and the seal.
  • mcp-oauth-postgres (4) and cloud-import-verify (21) need a PostgreSQL URL and are skipped locally; CI runs them.

One case in test/mcp-oauth-sessions.test.ts needs a PostgreSQL URL and is skipped locally, as on main.

Held for the owner's merge decision.

🤖 Generated with Claude Code


Proof this PR
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Fixes MCP OAuth connections being revoked when a refresh response never reached the client.

Previously a refresh rotated the token pair before the response was written; if that response was lost and the client retried more than 30 seconds later with the refresh token it still held, the retry counted as token reuse and revoked the entire grant, forcing a reconnect.

Now each rotation records its exact successor token hash on the retired token, and bearer admission records first use of each pair. If the successor pair has never been used, a retired refresh token re-rotates that pair and returns the new pair on the same grant, for up to 36 hours after the first rotation and never past the retired token's own expiry. Re-issued pairs keep their refresh expiry, so recovery never extends the grant. A retry within 30 seconds of a rotation or recovery is refused without revoking; reuse after the successor pair was used still revokes the grant. Revoking a retired refresh token at the revocation endpoint now ends its grant. Each refresh logs one mcp_oauth_refresh line with outcome and reason, never token material.

Behavior changes

  • Migration 0084 adds the tracking columns, all nullable, no backfill.
  • Pairs rotated before the upgrade have no recorded successor and keep the previous behavior; run the migration before deploying the new image.
  • Bearer admission refuses a token rotated or re-issued away between the session read and the first-use mark, so an unused pair is never both used and re-issued.
  • A retired token presented by the wrong client is answered invalid_grant, one for the wrong resource invalid_target, without revoking — keeping the existing self-hosted answers.
  • During a rolling upgrade, a pair first used only through an old replica can be re-issued once by a new one.

Written for commit 9c2d36a. Summary will update on new commits.

View guided diff Turn on auto-fix

layered-control-agent-host and others added 2 commits November 22, 2026 06:22
…he client

A refresh rotates the pair before the response is written. When the response
was lost and the client retried with its retired refresh token more than 30
seconds later, the retry was treated as token reuse and the whole grant was
revoked, so the connector had to be reconnected.

Each rotation now records the exact successor on the retired token, and bearer
admission records the first use of each pair. A retired token whose successor
pair has never been used rotates that pair again and returns the new pair on
the same grant, for up to 36 hours after the first rotation and never past the
retired token's own expiry. The re-issued pair keeps its refresh expiry. A
retry within 30 seconds of a recovery is refused without revoking. Reuse after
the successor pair was used still revokes the grant.

Bearer admission now refuses a token that was rotated or re-issued away
between the read and the first-use mark, so an unused pair is never both used
and re-issued. Revoking a retired refresh token at the revocation endpoint now
ends its grant. Refresh decisions are logged as `mcp_oauth_refresh` without
token material.

Migration 0084 adds the columns. Pairs rotated before the upgrade have no
recorded successor and keep the previous behaviour.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
@agent-relay-code agent-relay-code Bot added the merge-train:hold Do not merge until the owner gives the go label Nov 22, 2026
@coderabbitai

coderabbitai Bot commented Nov 22, 2026

Copy link
Copy Markdown

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 48f53cea-b43e-46f6-9623-1b914a616422

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

This branch has not been deployed

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

Labels

merge-train:hold Do not merge until the owner gives the go

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants