Codex .mcp.json: MCP OAuth Refresh, /app Desktop Handoff

OpenAI shipped Codex rust-v0.138.0 on June 8, 2026. The release is notable less for a single headline feature than for a cluster of operator-facing changes that make Codex significantly more scriptable, more reliable in fleet deployments, and better suited to workflows where expired credentials or mis-resolved workspace roots have historically caused silent failures.

What changed

Plugin JSON automation — operator plugin JSON API. The codex plugin add, codex plugin remove, and marketplace commands now accept and return structured --json output. Plugin list JSON includes the marketplace source for each plugin, and plugin detail payloads now expose default prompts, remote MCP servers, and unavailable app templates. For teams managing Codex plugin configurations across a developer fleet, this makes it practical to automate plugin state with shell scripts or CI tooling rather than relying on interactive TUI sessions.

/app CLI-to-Desktop handoff. A new /app command hands off the current CLI thread into Codex Desktop on macOS and native Windows. Windows workspace launches can also open directly into Desktop instead of stopping at a manual prompt. This matters for teams that run initial setup or CI-triggered sessions from the CLI but want developers to continue in the richer Desktop UX without losing session context.

MCP OAuth credential pre-refresh. Startup now pre-refreshes expired OAuth-backed MCP credentials before the session begins. Previously, an OAuth-secured MCP server with a stale token would fail at first invocation — often mid-session — requiring a manual re-auth that broke the agent's flow. Pre-refresh means Codex validates and renews credentials during startup, so the first actual tool call succeeds.

AGENTS.md loading fix for remote and symlinked workspaces. Workspace instruction loading is now accurate for remote repositories and symlinked workspace roots. Previously, Codex would pick up the wrong AGENTS.md — or no AGENTS.md at all — when the workspace root was a symlink or a remotely cloned path. This fix is significant for teams using monorepo structures, shared NFS/SMB mounts, or container volume mounts where symlinks are common.

Account token usage API. App-server integrations can now read account-level token usage through the API. This enables cost-attribution tooling built on top of Codex's app-server protocol to query token consumption per session or per account without relying on separate OpenAI API usage endpoints.

Startup and reliability improvements. TUI startup now reuses plugin discovery results and loads only hook metadata on the critical path, reducing startup latency. /usr/bin/bash support and shorter Linux proxy socket paths improve compatibility across constrained environments. resume --last finds the newest matching session through the state DB rather than scanning full history on disk, which speeds up restore on large local session stores. Large MCP/Ollama streams and long message histories are now scanned significantly faster.

Why it matters for AI engineering teams

The plugin JSON automation changes matter most to teams that manage Codex at scale. If your organization maintains a standard plugin set across a developer fleet, scripting plugin state via codex plugin add --json and codex plugin list --json is now practical. You can pipe output to a validation script, diff it against a desired-state manifest, or integrate it into MDM/configuration-management workflows.

The MCP OAuth pre-refresh addresses a category of failure that disproportionately affects longer or unattended Codex sessions. OAuth tokens typically expire on hour-long windows. An agent running a multi-hour coding task would hit a stale token mid-run, fail silently or with a confusing error, and leave work incomplete. Pre-refresh at startup closes that gap for sessions started fresh, though very long sessions may still need a strategy for mid-session credential renewal.

The AGENTS.md symlink fix directly affects teams using containerized development environments, dev containers, or monorepo layouts where the workspace root is not a canonical local path. A wrong AGENTS.md pick-up means Codex picks up the wrong system prompt — the agent gets the wrong context for the whole session. This is the kind of failure that's hard to diagnose because everything appears to start normally.

The router and operator angle

Plugin JSON automation and the token usage API together enable a pattern that matters for routing layer operators: automated Codex session auditing. An operator running multiple Codex instances through a shared routing gateway can now script plugin state validation and per-session token consumption queries without manual inspection. Combined with the operator governance controls available at the gateway level, this gives engineering platform teams two complementary data sources — gateway-level routing telemetry and Codex-native token usage — for cost attribution and compliance.

The AGENTS.md fix is also relevant to operators who deliver workspace instructions through shared mounts or containerized environments. If your fleet provisions Codex workspaces via container volume mounts with symlinked roots, the fix means Codex will now correctly pick up your fleet-wide AGENTS.md, which is often where routing gateway URL, provider config, or team-specific tool approvals are specified.

What to watch

The plugin JSON roadmap appears to be heading toward full machine-readability of plugin state — default prompts, remote MCP servers, and app templates are now visible in detail payloads, which is groundwork for configuration-management tooling. If your organization manages custom Codex plugins, this is the right time to start building automation around the JSON output before the schema stabilizes further.

The MCP OAuth pre-refresh is specifically for OAuth-backed MCP servers (streamable HTTP). Teams using stdio-based MCP servers are unaffected by this change but should verify whether their auth method is covered.

For teams routing Codex through a proxy or intermediary layer such as TheRouter, note that openai_base_url remains a project-config-restricted key — it cannot be set in project-local .codex/config.toml. Routing through a custom base URL must be configured at the user or app-server level, not pushed via project files. This is documented in the Codex advanced configuration reference.