[MCP] Make OAuth lifecycle and reauthentication reliable for enterprise SSO

[publi0]

Summary

This is an umbrella/tracking issue for the end-to-end MCP OAuth lifecycle. It
does not replace the narrower bug reports linked below.

Codex has already landed important foundations: shared credential-store
locking and pinning (#30292 and #30293), serialized proactive refresh before
startup and public operations (#32229), typed reauthentication signaling
(#29877 and #30257), and runtime reconciliation primitives (#34930, #34952,
and #34957).

The remaining problem is that these pieces do not yet produce one predictable
recovery workflow across plugin projection, CLI/Desktop/IDE runtimes, refresh
failure classification, interactive reauthorization, and login/logout.

This is especially important in enterprise environments where many MCP
servers sit behind corporate SSO, access tokens are intentionally short-lived,
refresh tokens rotate, and several Codex processes or surfaces may share the
same credential authority.

Claude Code documents that MCP OAuth tokens are stored securely and refreshed
automatically. Teams evaluating migrations expect similarly predictable
behavior from Codex; this issue does not require the same implementation, only
equivalent lifecycle reliability:

https://code.claude.com/docs/en/mcp#authenticate-with-remote-mcp-servers

Current upstream state

The observations below were rechecked against main at
62ba648136c7e60b9380c40b60cb553a7d8eb1ab.

Already landed

• Serialize shared MCP OAuth credential stores #30292 and Resolve and pin MCP OAuth credential stores #30293 serialize aggregate stores and pin the selected credential
  store for the client lifecycle.
• #32229 performs a serialized read-refresh-write transaction, rereads the
  authoritative store after locking, adopts a winner from another process,
  persists token rotation before use, and runs refresh before MCP initialize
  and public operations.
• [codex] Surface MCP reauthentication-required startup failures #29877 and #30257 surface authentication-required startup failures through a
  typed reauthenticationRequired reason for the wrappers they recognize.
• #34930, #34952, and #34957 centralize MCP runtime state and provide
  reconciliation, connection reuse, and replacement primitives.

These are substantial improvements. The remaining gaps below should be framed
as coverage and lifecycle integration on top of those foundations, not as if
automatic refresh or reconciliation infrastructure were completely absent.

Remaining lifecycle gaps

1. Do not silently omit plugin MCPs

Managed plugin requirements that do not declare an MCP allowlist should not be
treated as an empty allowlist.

This exact bug is tracked by #34110. The broader silent tool-omission symptom
is also reported in #18527. An explicitly empty allowlist should continue to
deny plugin MCPs; an absent MCP policy should not.

There is a second registry-parity problem in #34859: the running runtime can
materialize an account-synced plugin MCP while a standalone
codex mcp login <name> process cannot resolve the same server. Runtime,
status, and management commands should use the same effective MCP registry.

A configured server should be mounted or expose a precise policy, registry,
authentication, or startup reason. Policy-disabled state must not be presented
as Auth: Unsupported.

2. Preserve the landed automatic-refresh guarantees across every path

The baseline proactive refresh transaction is already implemented by #32229.
The remaining requirement is to ensure that routed/plugin/Desktop paths and
401 recovery do not bypass or retain stale copies of that authority.

Open symptoms include #17265 and #27165. Direct-keyring concurrency regression
coverage is tracked by #33540. Codex-owned one-shot 401 recovery and session
rebuild remain proposed in #30294.

3. Classify refresh failures by remediation

The current refresh path receives RMCP
AuthError::TokenRefreshFailed(String) for both definitive rejection and
transient token-endpoint failures, and currently converts the entire variant
to AuthorizationRequired.

The lifecycle should distinguish at least:

• invalid_grant: the refresh token/grant is invalid, expired, or revoked;
  require a new authorization grant.
• invalid_client: recover or re-register the OAuth client when possible
  before asking for a new user grant; see MCP OAuth: Codex does not re-register (DCR) on invalid_client / expired refresh token — requires manual re-auth #29630.
• network failures, timeouts, HTTP 5xx, and provider-declared temporary
  failures: preserve the durable credential authority, report a retryable
  failure, and do not immediately open OAuth.
• persistence failure after the provider may have rotated the token: treat the
  outcome as unknown, fail closed, reread the authoritative store, and avoid a
  blind replay or silently switching credential stores.

Earlier PRs #26519 and #26237 described part of this distinction but closed
without merge.

Relevant OAuth semantics:

• https://www.rfc-editor.org/rfc/rfc6749.html#section-5.2
• https://www.rfc-editor.org/rfc/rfc9700.html#section-4.14

4. Recognize authentication-required errors through every wrapper

Authentication-required state must survive all RMCP transport/error wrappers
and reach clients as a typed reason.

The current nested classifier recognizes
StreamableHttpError::Auth(AuthError::AuthorizationRequired | TokenExpired)
but not StreamableHttpError::AuthRequired(...).

Related merged work: #29877 and #30257.

5. Provide an actionable reauthorization flow

When a refresh is definitively rejected:

• an interactive surface should offer or open OAuth, wait for the callback,
  and retry startup at most once;
• cancellation or failed login must not create a browser/retry loop;
• a headless or automation surface should return a stable typed result and a
  reconnect action without depending on a browser.

Related issues: #13956 and #29630. Related open work: #30294.

6. Reconcile credentials without requiring an app restart

The expected timing differs by login path:

• For an OAuth callback owned by the running app-server, invalidate and
  reconcile the affected runtime immediately after the credential is
  persisted.
• For codex mcp login <server> running in another process, detect the new
  credential generation through store watching, IPC, or a reread/reconciliation
  boundary no later than the next operation or turn.

In both cases, users should not need to restart Codex or create a new
conversation.

Related issue: #14144. The primitives landed in #34930, #34952, and #34957,
but the successful app-server OAuth callback currently emits a completion
notification without triggering runtime reconciliation.

7. Keep one authoritative credential lifecycle across surfaces

CLI, Desktop, IDE, and automations using the same Codex home should not
overwrite rotated credentials, resurrect logged-out credentials, or retain
stale generations independently.

#32229 substantially addresses concurrent refresh. Login and logout still need
to participate in the same per-credential transaction boundary; that work is
proposed in #30295. The earlier #30416 proposal is functionally represented by
the merged #32229 and should not be counted as a separate missing refresh
implementation.

Credential durability and store selection also need actionable diagnostics.
Related reports include #15122 and the volatile Linux keyring case #34943.

8. Expose actionable lifecycle status

Status APIs and UIs should distinguish:

• no authentication required;
• first login required;
• refreshable credential available;
• reauthentication required;
• retryable provider/network failure;
• ambiguous refresh/persistence outcome;
• policy-disabled;
• configured in runtime but unavailable to management commands.

This prevents policy, projection, registry, storage, and OAuth failures from
collapsing into Auth: Unsupported or a missing tool namespace.

Expected state machine

For each OAuth-backed MCP:

1. Valid access token: initialize normally.
2. Expired or near-expiry access token plus a usable refresh token: run the
   serialized refresh transaction and persist any rotation before exposure.
3. Another process already committed a newer generation: adopt the
   authoritative winner without contacting the provider again.
4. Transient provider/network failure: preserve credentials and report a
   retryable failure without requesting a new grant.
5. Provider refresh succeeded but persistence outcome is uncertain: fail
   closed, reconcile against the authoritative store, and do not blindly
   replay the previous rotating token.
6. invalid_grant: emit typed reauthentication-required state.
7. invalid_client: attempt the appropriate client-registration recovery or
   return a distinct remediation.
8. Interactive surface: offer/launch OAuth and retry startup at most once.
9. Successful in-process callback: reconcile the affected runtime immediately.
10. Successful external CLI login: loaded runtimes adopt the new generation by
    the next operation or turn, without restart.
11. Headless surface: fail deterministically with a stable reconnect action and
    no browser dependency.

Acceptance criteria

• The proactive refresh behavior landed in #32229 works consistently for
  startup, tool calls, routed/plugin servers, and long-lived threads.
• A valid stored refresh token survives access-token expiry without user
  action.
• invalid_grant produces an actionable reconnect flow; timeout or HTTP 5xx
  does not delete credentials or immediately request a new grant.
• Two processes cannot replay or overwrite a rotating refresh token.
• Login, refresh, and logout share the same per-credential transaction
  boundary.
• A successful app-owned OAuth callback repairs the current thread without
  restart.
• A successful external CLI login is adopted by loaded runtimes no later than
  their next MCP operation or turn.
• A plugin MCP is not disabled merely because managed plugin requirements
  exist without an MCP allowlist.
• Runtime and codex mcp list|get|login resolve the same effective plugin MCP
  registry.
• Headless clients receive stable typed remediation rather than a browser
  dependency or silently missing tools.
• Status surfaces expose the actual lifecycle/policy failure reason.

Operational follow-ups

These are useful, but should not be treated as substitutes for automatic
lifecycle recovery:

Multi-server repair

Provide a sequential repair flow such as codex mcp login --all-required or
codex mcp repair. It should operate only on servers that need first login or
reauthorization, skip healthy refreshable credentials and unsupported/static
auth, and never open several browser flows concurrently.

Failed-startup cleanup

If initialize or initial list_tools fails, explicitly shut down the
client/transport when ownership is not already guaranteed to do so. This
should have its own focused regression or resource-leak reproduction rather
than being assumed to be an OAuth root cause.

Non-goals

• Per-session corporate approval or step-up authorization is distinct from
  OAuth token refresh and should retain its own policy/consent semantics.
• The request is not to open a browser for every MCP at startup.
• Static bearer-token and stdio authentication are not OAuth refresh flows.
• This issue does not require Codex to copy Claude Code's internal
  implementation.

Why keep an umbrella issue

The linked issues and PRs correctly address individual layers, but enterprise
users experience the combined failure as one outcome: an MCP that was
previously authorized stops being available and does not recover predictably.

A lifecycle owner and an end-to-end regression suite covering CLI, app-server,
plugin registries, concurrent processes, rotating refresh tokens, transient
provider failures, and active-runtime reconciliation would ensure the landed
pieces compose into a dependable corporate workflow.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Plugin MCPs are disabled when plugin requirements contain no MCP allowlist #34110
• Remote-installed plugin MCP prompts codex mcp login, but the command cannot resolve the server #34859
• MCP OAuth credentials are lost when a volatile GNOME Keyring session restarts #34943

Powered by Codex Action

[publi0]

Upstream update — rechecked against main@95637f705 on July 27, 2026

Since this issue was opened, the following pieces have landed:

• Refresh MCP runtimes when session auth changes #35146 rebuilds MCP runtimes when the session authentication snapshot changes.
• Reconnect MCP servers on explicit refresh #35151 forces existing MCP connections to reconnect on an explicit MCP refresh.
• Refresh MCP runtimes across thread startup #35204 invalidates MCP runtimes after successful server/plugin OAuth login, including threads still starting.
• Route MCP auth discovery through runtime HTTP clients #35239 routes OAuth discovery/status through the same runtime HTTP client and proxy path as the MCP transport.
• Skip plugin MCP filtering when no allowlists are configured #35280 fixes the missing-allowlist case: an omitted plugin mcp_servers policy no longer disables every plugin MCP. Plugin MCPs are disabled when plugin requirements contain no MCP allowlist #34110 is now closed.

This means the first plugin-filtering gap and the app-owned OAuth-callback part of runtime reconciliation are addressed. Registry parity for standalone codex mcp login (#34859), external-process credential adoption, lifecycle diagnostics, and volatile credential durability remain open.

Refresh-token behavior still missing on current main

1. Refresh is expiry-driven only. A provider can reject an access token with 401 while Codex still considers its local expires_at valid (revocation, provider-side invalidation, clock/metadata mismatch). In that case the current path does not force a refresh, rebuild the MCP transport/session, and retry once.
2. AuthError::TokenRefreshFailed(String) currently collapses definitive OAuth rejection and transient token-endpoint failures. Mapping the whole variant to AuthorizationRequired conflates invalid_grant with temporarily_unavailable, HTTP 5xx, timeouts, and network failures, which can turn a temporary outage into a full browser authorization flow.
3. The nested startup classifier recognizes StreamableHttpError::Auth(AuthorizationRequired | TokenExpired) but not StreamableHttpError::AuthRequired(...).
4. Route MCP OAuth recovery through Codex #30294 (Codex-owned transport recovery) and Serialize MCP OAuth login and logout #30295 (serialized login/logout) were closed unmerged on July 26. I found no equivalent replacement for those behaviors in current main.

Locally validated recovery semantics

A focused implementation and regression suite validates:

• startup 401 with an unexpired persisted access token → force serialized refresh, rebuild transport, retry initialize once;
• active-session tools/list 401 → force refresh, rebuild the MCP session, retry the operation once;
• concurrent/newer credential generation → reread under the shared lock and adopt the newer durable credentials instead of replaying a stale rotating refresh token;
• token endpoint invalid_grant → typed reauthorization required;
• token endpoint 503 temporarily_unavailable → preserve durable credentials, return a retryable failure, and do not launch OAuth;
• interactive reauthorization only after definitive rejection, with at most one login/startup retry.

Targeted validation passed: 5/5 Streamable HTTP OAuth startup/session integration tests, 8/8 refresh-transaction tests, and 122/122 codex-mcp tests.

These results narrow lifecycle gaps 2–5: recovery needs both an expiry boundary and a one-shot authentication-failure boundary, while browser reauthorization must remain reserved for definitive grant rejection. A typed RMCP refresh error would be preferable to parsing TokenRefreshFailed(String).

[publi0]

Additional confirmed gap: background SSE refresh bypasses durable persistence

A concrete reproduction now confirms one of the remaining lifecycle gaps described in this issue.

Even with the recently landed serialized refresh transaction, RMCP can autonomously refresh an expired access token during an SSE get_stream reconnect. That refresh happens inside RMCP's AuthClient, outside Codex's guarded OAuthPersistor transaction.

With a provider that rotates refresh tokens on every use, the result is:

durable store: access A0 / refresh R0
RMCP memory:   access A1 / refresh R1
provider:      R0 invalidated after issuing R1

The current process continues using the refreshed in-memory credentials, but a restarted or parallel Codex process reloads R0 and receives:

invalid_grant: The refresh token was already used.

This means the landed concurrency fixes protect Codex-initiated refreshes, but not refreshes initiated autonomously by RMCP's background Streamable HTTP/SSE path.

Detailed timeline, source-level analysis, regression test, and locally validated fix:

• Codex does not auto-refresh routed MCP OAuth tokens even when a refresh token is stored #17265: Codex does not auto-refresh routed MCP OAuth tokens even when a refresh token is stored #17265 (comment)

The end-to-end acceptance criterion should therefore explicitly cover background get_stream/SSE reconnects: every token lookup or refresh must use the same serialized credential transaction, and rotated credentials must be durably persisted before the refreshed access token is exposed to the transport.

[publi0]

Upstream update — rechecked against main@9ea975a2d on July 28, 2026

The latest upstream round resolves one of the concrete lifecycle gaps documented above:

• Upgrade rmcp to 3.0.0-beta.3 #35720 upgrades RMCP to 3.0.0-beta.3 and introduces a typed distinction between AuthError::TokenRefreshRejected and transient TokenRefreshFailed errors. Codex now maps only definitive refresh-token rejection to reauthorization. The local string parser for invalid_grant is no longer necessary, and the upstream regression test confirms that a temporary provider failure preserves credentials without requesting a new grant.
• Route MCP OAuth through configured HTTP clients #35806 routes MCP OAuth through the configured HTTP client path, including the authorization manager used for token refresh. This is important for enterprise proxy/VPN environments and complements the earlier routed discovery work.

This means lifecycle gap 3 ("Classify refresh failures by remediation") is now substantially addressed for invalid_grant versus transient refresh failures.

Gaps still present on current main

1. Background Streamable HTTP/SSE refresh can still bypass durable persistence. The OAuth transport still uses RMCP's AuthClient directly. A refresh initiated autonomously during get_stream can rotate credentials in memory without committing the new refresh token through Codex's serialized OAuthPersistor transaction. The detailed reproduction remains in Codex does not auto-refresh routed MCP OAuth tokens even when a refresh token is stored #17265, and the same behavior has also been independently reproduced after the RMCP 3 upgrade: Codex does not auto-refresh routed MCP OAuth tokens even when a refresh token is stored #17265 (comment)
2. There is still no Codex-owned one-shot recovery after an authenticated operation receives 401 while local expires_at remains valid. Current main does not force a refresh, rebuild the MCP session, and retry the operation once.
3. Authentication-required classification remains incomplete. The startup classifier recognizes StreamableHttpError::Auth(AuthorizationRequired | TokenExpired) but still misses StreamableHttpError::AuthRequired(...).
4. External login adoption and lifecycle serialization remain open. Already-running processes still lack a reliable boundary for adopting credentials written by an external codex mcp login; login/logout do not yet participate in the same refresh transaction; and standalone plugin registry parity remains tracked by Remote-installed plugin MCP prompts codex mcp login, but the command cannot resolve the server #34859.
5. Failed-startup cleanup and actionable status remain open. Initial initialize/list_tools failures still do not explicitly shut down the owned client in that path, and lifecycle states are not yet exposed with the remediation detail described in this issue.

The recent cached-tool, optional-startup-grace, and concurrent-catalog work (#35590, #35742, and #35777) should materially reduce MCP startup and inventory latency. Those are useful operational improvements, but they do not replace the remaining OAuth recovery semantics above.

Rebased local validation

The focused implementation was rebased onto main@9ea975a2d, preserving the new RMCP 3 behavior and the configured HTTP-client routing. The now-redundant invalid_grant parser and duplicate transient-failure test were removed. Only the still-missing behaviors were retained:

• persistent refresh/persistence before Streamable HTTP operations, including SSE reconnects;
• one-shot refresh, session rebuild, and retry after authentication failure;
• complete AuthRequired classification;
• failed-startup transport cleanup;
• structured refresh diagnostics.

Targeted validation after the rebase passed:

• codex-rmcp-client: 204/204 tests;
• codex-mcp: 133/133 tests;
• MCP-specific TUI startup and /mcp status coverage: 28/28 tests.

So the umbrella status is now narrower: typed refresh-failure classification and routed OAuth HTTP behavior have landed upstream, while background refresh durability, authentication-failure recovery, external credential adoption, and end-to-end lifecycle status still need upstream coverage.