38 Commits

• Keep MCP elicitation routable across runtime refreshes (#30127)

  ## Why
  
  An MCP tool call can still be waiting for an elicitation response when
  an environment update replaces the thread's MCP runtime.
  
  Before this change:
  
  ```text
  runtime A starts a tool call and asks the user
  environment becomes ready, so runtime B is published
  client answers the prompt through runtime B
  runtime B cannot find runtime A's pending responder
  ```
  
  The response is lost and the original tool call stays blocked.
  
  ## What changed
  
  All MCP runtimes for one thread now share a small elicitation router:
  
  ```text
  runtime A ---\
                 shared router: response token -> exact pending responder
  runtime B ---/
  ```
  
  When Codex surfaces an MCP elicitation, it assigns a unique opaque
  response token. The router records which pending request owns that
  token. A replacement runtime reuses the same router, so the latest
  runtime can deliver a response to a request started by the previous
  runtime.
  
  The Codex-owned token also prevents two runtime connections that reuse
  the same MCP server request ID from receiving each other's responses.
  
  This does not retain or search old MCP managers. Only the pending
  responder map is shared.
  
  ## Covered scenario
  
  The integration test exercises the complete failure mode:
  
  1. A thread starts while its selected environment is still unavailable.
  2. A configured MCP server starts a tool call and asks the client for
  input.
  3. The environment becomes ready, causing Codex to publish a replacement
  MCP runtime.
  4. The client answers the original prompt after the replacement.
  5. The original tool call receives that answer and completes.
  
  A focused routing test also creates two runtimes with the same server
  request ID and verifies that each response reaches the exact request
  that emitted its token.
  
  ## Scope
  
  This PR changes only elicitation response routing across MCP runtime
  replacement. It does not change when runtimes are rebuilt, which
  environments contribute MCP configuration, or how environment
  availability is detected.

  jif · 2026-06-26 01:28:14 +00:00
  fb8598df3f
• [codex] Surface MCP reauthentication-required startup failures (#29877)

  ## Summary
  
  - distinguish expired, non-refreshable stored MCP OAuth credentials from
  first-time missing credentials
  - carry a typed `failureReason: "reauthenticationRequired"` on the
  existing `mcpServer/startupStatus/updated` notification only when user
  action is required
  - keep the public MCP auth-status API unchanged and regenerate the
  app-server protocol schemas and documentation
  
  ## Why
  
  An MCP server with an expired access token and no usable refresh token
  currently fails startup without giving clients a reliable, typed
  recovery signal.
  
  The existing startup-status notification is the natural place to carry
  this state. Its nullable `failureReason` keeps the recovery reason
  attached to the failed startup transition without adding a one-off
  notification. Internally, Codex distinguishes first-time login from
  reauthentication and emits the reason only when the startup error itself
  requires authentication.
  
  ## User impact
  
  App clients can prompt an existing user to reconnect an MCP server when
  automatic recovery is impossible by handling a failed
  `mcpServer/startupStatus/updated` notification whose `failureReason` is
  `reauthenticationRequired`. Starting, ready, cancelled, unrelated
  failures, and first-time setup carry no reauthentication reason.
  
  ## Companion app PR
  
  - openai/openai#1069582
  
  ## Validation
  
  - `just test -p codex-app-server-protocol` — 248 passed; schema fixture
  tests passed
  - `cargo check -p codex-app-server -p codex-tui`
  - `just test -p codex-rmcp-client -p codex-mcp` — 184 passed, 2 skipped
  - `just test -p codex-protocol -p codex-app-server-protocol -p
  codex-mcp` — 579 passed
  - `just write-app-server-schema`
  - `just fmt`

  felixxia-oai · 2026-06-25 21:50:36 +00:00
  a6d20ed297
• feat(core, mcp): cache codex_apps tools in memory (#29003)

  ## Description
  
  This makes Codex Apps tool reads use a shared in-memory snapshot instead
  of rereading the disk cache every time `list_all_tools()` runs. Disk
  still seeds the cache on startup and gets updated after successful
  fetches, but it is no longer the live read path.
  
  The core change is that `McpManager` now owns a process-scoped
  `CodexAppsToolsCache`. Codex threads in the same app-server process now
  share this Codex Apps in-memory tools snapshot. The snapshot is keyed by
  the Codex home plus the Codex Apps identity: the active Codex auth
  user/workspace and the effective Codex Apps MCP source config.
  
  There's already code to hard-refresh the cache, so we respect it in this
  PR.
  
  ## Local benchmark
  
  I ran a local steady-state microbenchmark of the exact repeated Codex
  Apps cached-tools read this PR removes, using the same real local cache
  payload in both trees: `3,678,138` bytes and `381` tools. The cache file
  was already warm in the OS page cache, so this measures same-process
  reread/deserialization work rather than cold-disk latency or full turn
  latency. Each run is 25 iterations (mimicking a turn that makes 25
  inference calls).
  
  | Version | Run 1 | Run 2 | Avg |
  |---|---:|---:|---:|
  | `origin/main` disk read + JSON deserialize + `filter_tools` | `50.755
  ms` | `52.894 ms` | `51.825 ms` |
  | This branch in-memory `current_tools` + `filter_tools` | `0.740 ms` |
  `0.778 ms` | `0.759 ms` |
  
  That removes about `51 ms` from each repeated Codex Apps cached-tools
  read on this machine, roughly `68x` faster for that subpath. It is
  useful evidence for the hot path this PR changes, but not a claim that
  every production turn gets `51 ms` faster; end-to-end impact also
  depends on the rest of `list_all_tools()` and tool-payload construction.
  
  This is on my M2 Max macbook, so with a slower disk this would be much
  worse (and indeed we did see this really blew up turn runtime with a
  slow disk).

  Owen Lin · 2026-06-25 20:54:48 +00:00
  703793c22e
• Represent MCP authentication with an enum (#29924)

  ## Why
  
  MCP authentication has distinct OAuth and ChatGPT-session flows.
  Representing that choice as `use_chatgpt_auth` makes one flow implicit
  and allows the configuration model to express the distinction only
  through a boolean.
  
  ChatGPT credential forwarding also needs a first-party trust boundary. A
  configurable `chatgpt_base_url` controls routing, but must not grant an
  MCP server permission to receive session credentials.
  
  This change builds on #29733, where the boolean was introduced.
  
  ## What changed
  
  - Replace `use_chatgpt_auth` with an `auth` field backed by the
  exhaustive `McpServerAuth` enum.
  - Support `auth = "oauth"` and `auth = "chatgpt"`, with OAuth remaining
  the default.
  - Trust only the origin derived from the existing hardcoded
  `CHATGPT_CODEX_BASE_URL` when granting ChatGPT auth to an MCP server.
  - Keep configured bearer tokens and authorization headers ahead of the
  selected authentication flow.
  - Update config writers, schema output, fixtures, and integration-test
  setup to use the enum.
  
  ## Verification
  
  Integration coverage exercises the complete streamable HTTP startup path
  in two independent configurations:
  
  - A directly constructed MCP configuration verifies that matching an
  overridden `chatgpt_base_url` does not grant ChatGPT auth.
  - A persisted `config.toml` containing an attacker-controlled
  `chatgpt_base_url` and `auth = "chatgpt"` verifies the same boundary
  through normal config parsing.
  
  Both tests complete MCP initialization and tool listing and assert that
  the full captured request sequence contains no authorization headers.
  Separate integration coverage verifies that configured authorization
  takes precedence over ChatGPT auth.

  Ahmed Ibrahim · 2026-06-24 19:51:51 -07:00
  f8937b7d86
• Allow ChatGPT-hosted MCP servers to use session auth (#29733)

  ## Why
  
  ChatGPT session authentication was inferred from the reserved Codex Apps
  server name. That couples credential routing to Codex Apps-specific
  behavior and prevents other MCP endpoints hosted by ChatGPT from
  explicitly using the current session.
  
  The opt-in also needs a clear security boundary: an arbitrary MCP
  configuration must not be able to redirect ChatGPT credentials to
  another origin.
  
  ## What changed
  
  - Add `use_chatgpt_auth` to HTTP MCP server configuration, defaulting to
  `false`.
  - Honor the setting only when the parsed server URL has the same HTTP(S)
  origin as the configured `chatgpt_base_url`; otherwise remove the
  capability before startup.
  - Resolve bearer tokens and static or environment-backed authorization
  headers before selecting authentication, with configured authorization
  taking precedence over ChatGPT session auth.
  - Enable the setting for the built-in Codex Apps and hosted plugin
  runtime endpoints while keeping Codex Apps caching and tool
  normalization scoped to the reserved server.
  - Persist the setting through MCP config rewrite paths and expose it in
  the generated config schema.
  - Load the current login state for `codex mcp list` so reported auth
  status matches runtime behavior.
  
  ## Verification
  
  Core integration coverage exercises the complete streamable HTTP MCP
  startup path and verifies that:
  
  - a same-origin opted-in server receives the current ChatGPT access
  token;
  - an explicitly configured authorization header takes precedence;
  - a different-origin server completes MCP initialization and tool
  listing without receiving any ChatGPT authorization header.

  Ahmed Ibrahim · 2026-06-24 19:21:28 -07:00
  4c0706e24a
• Shut down superseded MCP managers on refresh (#29608)

  ## Summary
  
  MCP refresh replaced the published connection manager without shutting
  down the manager it superseded. If another task retained that old
  manager, its stdio MCP processes stayed alive and accumulated across
  refreshes.
  
  Atomically swap in the refreshed manager, then explicitly shut down the
  exact manager returned by the swap. Add a process-level regression test
  that retains the old manager during refresh and verifies its stdio
  process exits while the replacement remains available.
  
  ## Context
  
  Explicit cleanup was lost when manager publication moved to `ArcSwap`.
  Dropping the old manager is not a reliable shutdown boundary because
  active callers can retain its `Arc` and underlying client process
  handles.

  jif · 2026-06-23 18:29:27 +01:00
  8751fd3fcb
• Fix Codex Apps auth elicitation hang (#29615)

  ## Summary
  - Require the reserved Codex Apps MCP server name to be present in the
  connection manager before treating it as host-owned.
  - Update auth elicitation tests to model an installed host-owned Codex
  Apps server without sending startup events to the test session.
  
  ## Why
  PR #29518 replaced the old host-owned flag with a name-only check. That
  made non-host-owned tests with the reserved codex_apps name enter auth
  elicitation and wait forever for a response.

  jif · 2026-06-23 13:45:42 +02:00
  55bc38a22b
• Group Codex Apps client setup (#29583)

  ## Why
  
  `McpConnectionManager::new` classified the Codex Apps server twice: once
  to create its tools cache context and again to select its runtime
  authentication provider. Keeping those decisions separate makes it
  harder to see that they belong to the same server-specific setup path.
  
  ## What changed
  
  - Group Codex Apps cache and authentication setup under one explicit
  branch.
  - Keep regular MCP server setup in the corresponding `else` branch.
  - Limit environment bearer-token inspection to the Codex Apps path where
  it affects runtime authentication.

  Ahmed Ibrahim · 2026-06-23 00:53:17 -07:00
  266dcbfe5b
• Remove redundant Codex Apps cache guard (#29575)

  ## Why
  
  Codex Apps cache writes are already restricted to Codex Apps call paths:
  startup invokes the helper only from the Codex Apps branch, and hard
  refresh operates on the reserved Codex Apps server directly. Rechecking
  the server name inside the cache helper duplicates that classification
  and leaves the helper with an argument that cannot change valid
  behavior.
  
  ## What changed
  
  - Remove the redundant server-name check and parameter from the cache
  writer.
  - Rename the helper to `write_codex_apps_tools_cache` to reflect its
  narrower contract.
  - Update production and test callsites to use the simplified API.

  Ahmed Ibrahim · 2026-06-23 00:31:56 -07:00
  83c4934e45
• Centralize Codex Apps client handling (#29528)

  ## Why
  
  Codex Apps-specific behavior is currently distributed across cache
  helpers, startup, tool conversion, and model-visible annotation. Each
  layer independently checks the reserved server name, which obscures the
  boundary between trusted host-owned connector metadata and regular MCP
  server data.
  
  Classifying the server once when `AsyncManagedClient` is created gives
  the client a single source of truth and makes the two processing paths
  explicit.
  
  ## What changed
  
  - Record whether an `AsyncManagedClient` represents the Codex Apps
  server at construction time.
  - Route startup cache loading, cache persistence, and cache telemetry
  through the Codex Apps branch.
  - Split uncached tool conversion between Codex Apps normalization and
  regular MCP metadata sanitization.
  - Split model-visible schema and plugin provenance handling along the
  same boundary.
  - Remove redundant server-name guards from helpers that are now called
  only from the Codex Apps branch.
  
  ## Verification
  
  - Preserve behavioral coverage that verifies Codex Apps connector
  metadata and the complete converted `ToolInfo` shape.
  
  ## Stack
  
  Depends on #29518.

  Ahmed Ibrahim · 2026-06-23 00:00:25 -07:00
  f0ad028a74
• Remove redundant Codex Apps manager flag (#29518)

  ## Why
  
  Codex Apps server admission is already decided before
  `McpConnectionManager` is constructed. `effective_mcp_servers` and
  `effective_mcp_servers_from_configured` remove the server when the apps
  feature or required authentication is unavailable, so storing the same
  decision on the manager duplicates state that can drift from the
  effective server map.
  
  ## What changed
  
  - Remove `host_owned_codex_apps_enabled` from `McpConnectionManager` and
  its constructor.
  - Identify the host-owned Codex Apps server by its reserved server name
  once it is present in the effective server map.
  - Remove the now-unused flag calculations and constructor arguments from
  production and test callsites.

  Ahmed Ibrahim · 2026-06-22 23:19:42 -07:00
  a22e3d0b82
• Add config toggles for orchestrator skills and MCP (#28942)

  ## Why
  
  Orchestrator-provided skills and Codex Apps MCP tools add model-visible
  instructions, resources, and tools beyond the local workspace. Hosts
  need config-level switches to disable those orchestrator-owned surfaces
  independently, without disabling regular skills or regular MCP servers.
  
  ## What changed
  
  - Adds `[orchestrator.skills].enabled` and `[orchestrator.mcp].enabled`
  config entries, both defaulting to `true`.
  - Includes the new settings in `config.schema.json` and in the config
  lock so resolved thread configuration preserves the same orchestrator
  exposure decisions.
  - Threads `orchestrator.skills.enabled` through the app-server skills
  extension so disabled orchestrator skills do not expose the `skills`
  namespace or inject orchestrator skill context.
  - Gates Codex Apps MCP exposure, app instructions, and app auth
  eligibility on `orchestrator.mcp.enabled` while leaving non-Codex-Apps
  MCP tools available.
  - Updates the thread-manager sample config to disable both
  orchestrator-owned surfaces.
  
  ## Verification
  
  - Added config parsing, loading, defaulting, and schema coverage for the
  new settings.
  - Added MCP exposure coverage that `orchestrator.mcp.enabled = false`
  removes Codex Apps tools while preserving regular MCP tools.
  - Added app-server coverage that `orchestrator.skills.enabled = false`
  prevents orchestrator skill tools, prompts, and resource reads from
  reaching the model turn.

  jif · 2026-06-19 14:42:26 +02:00
  81b000421d
• Support openai/form extended form elicitations (#27500)

  # Summary
  Allow App Server clients to opt into `openai/form` MCP elicitations.

  Gabriel Peal · 2026-06-18 11:54:49 -07:00
  21a599fa56
• Scope MCP sandbox metadata to server environment (#28914)

  Scope MCP sandbox metadata to the MCP server's owning environment.
  
  Previously, `codex/sandbox-state-meta` always used the turn's primary
  cwd and rebuilt a legacy sandbox policy from that cwd. That can be wrong
  for MCP servers owned by a different execution environment.
  
  This now sends the owning environment cwd as a `file:` URI in
  `sandboxCwd`, keeps `permissionProfile` as the permission source of
  truth, and omits sandbox-state metadata when a non-default server
  environment is not selected for the turn. Local/default MCP servers keep
  the existing fallback cwd behavior.
  
  Tests:
  - `just fmt`
  - `just bazel-lock-update`
  - `just bazel-lock-check`
  - `just test -p codex-mcp`
  - `just test -p codex-core mcp_sandbox_cwd`
  - `cargo build -p codex-rmcp-client --bin test_stdio_server`
  - `just test -p codex-core
  stdio_mcp_tool_call_includes_sandbox_state_meta`

  jif · 2026-06-18 19:31:07 +02:00
  790213ded0
• Add selected-plugin precedence and attribution to the MCP catalog (#27884)

  ## Why
  
  **In short:** this PR resolves already-discovered MCP registrations. It
  does not read selected plugins or discover their MCP servers.
  
  The resolved MCP catalog currently builds config and auto-discovered
  plugin registrations before runtime contributors are applied. A
  thread-selected plugin needs a distinct precedence tier in that same
  initial resolution pass: otherwise a disabled lower-precedence winner
  can leave stale name-level state behind, and the winning MCP tools
  cannot be attributed to the selected package reliably.
  
  This PR adds that catalog boundary before executor discovery is
  connected.
  
  ## What changed
  
  - Added an explicit selected-plugin registration tier between
  auto-discovered plugins and explicit config.
  - Collected selected-plugin contributions before the initial catalog
  build, while leaving compatibility and generic extension overlays in
  their existing runtime phase.
  - Retained the winning plugin ID and display name directly on
  plugin-owned catalog registrations.
  - Derived MCP tool provenance from the winning catalog entry instead of
  joining against local-only plugin summaries.
  - Retained the winning selected server's tool approval policy in the
  running connection manager, so a selected registration cannot inherit
  approval behavior from a losing local plugin.
  - Kept remembered approval session-scoped for selected plugins until
  there is an authority-aware persistence contract; Codex will not write
  approval back to an unrelated local plugin.
  - Preserved existing name-level disabled vetoes for discovered plugins
  and config, while keeping a selected package's own disabled registration
  scoped to that registration.
  - Preserved deterministic selection order and existing config,
  compatibility, and extension precedence.
  
  The resulting order is:
  
  ```text
  auto-discovered plugin
    < selected plugin
    < explicit config
    < compatibility registration
    < extension overlay
  ```
  
  ## Behavior and scope
  
  This is a catalog and provenance change only. No production host
  contributes selected-plugin MCP registrations yet, so existing local MCP
  behavior remains unchanged.
  
  The stacked follow-up, #27870, installs the executor plugin provider
  that produces these registrations. App-server activation remains a
  separate final step.
  
  ## Verification
  
  Focused tests cover precedence, deterministic selected-plugin conflicts,
  disabled-veto behavior across catalog phases, managed requirements
  before selected-plugin resolution, winning-server approval policy, and
  attribution when local and selected packages share an ID or server name.
  CI owns execution of the test suite.

  jif · 2026-06-15 11:10:51 +02:00
  c3a479620f
• feat: use encrypted local secrets for MCP OAuth (#27541)

  ## Summary
  
  - store MCP OAuth credentials in the configured auth credential backend
  - support encrypted-local OAuth storage, including legacy keyring
  migration
  - propagate the credential backend through MCP refresh, session, CLI,
  and app-server paths
  
  ## Stack
  
  1. #27504 — config and feature flag
  2. #27535 — auth-specific secret namespaces
  3. #27539 — encrypted CLI auth storage
  4. this PR — encrypted MCP OAuth storage
  
  This is a parallel review stack; the original #17931 remains unchanged.
  
  ## Tests
  
  - `just test -p codex-rmcp-client` (the transport round-trip test passed
  after building the required `codex` binary and retrying)
  - `just test -p codex-mcp`
  - `just test -p codex-app-server
  refresh_config_uses_latest_auth_keyring_backend`
  - `just test -p codex-core
  refresh_mcp_servers_is_deferred_until_next_turn`
  - `just test -p codex-cli mcp`
  - `just fix -p codex-rmcp-client -p codex-mcp -p codex-core -p codex-cli
  -p codex-app-server -p codex-protocol`
  - `just bazel-lock-check`

  Celia Chen · 2026-06-12 22:03:51 +00:00
  9915d34684
• skills: make backend plugin skills invocable without an executor (#27387)

  ## Why
  
  #27198 made the extension-owned `codex_apps` MCP connection the hosted
  plugin runtime, but its `mcp/skill` resources still bypassed the skills
  extension. App-server could list and read those resources through
  generic MCP APIs, but a thread with no selected environment did not
  expose them in the model's skills catalog or load their `SKILL.md`
  through `$skill`.
  
  Hosted skills should stay remote while using the same typed catalog,
  source authority, deduplication, bounded contextual catalog, and
  selected-skill prompt injection as host and executor skills. They should
  not be downloaded or exposed as ambient filesystem paths.
  
  ## What changed
  
  - Add a session-scoped `McpResourceClient` over the replaceable MCP
  connection manager so resource list/read calls follow startup and
  refresh replacements.
  - Add a `BackendSkillProvider` that pages `codex_apps` resources,
  accepts bounded and validated `mcp/skill` entries, and reads a selected
  skill's `SKILL.md` through the same MCP connection.
  - Register the remote provider in app-server and include it in the
  skills catalog even when a thread has no selected capability roots or
  executor.
  - Contribute hosted skill metadata through the bounded
  `AvailableSkillsInstructions` developer-context path, exclude remote
  entries from per-turn catalog injection, and classify `<skills>`
  messages as contextual developer content so rollback can trim and
  rebuild them correctly.
  
  ## Testing
  
  - Extend the app-server MCP resource integration test with
  `environments: []` to exercise two-page discovery, filter a
  non-`mcp/skill` resource, verify the escaped developer catalog entry and
  user-role `<skill>` fragment containing the fetched `SKILL.md`, and
  preserve generic MCP resource reads.
  - Add core event-mapping coverage that classifies `<skills>` developer
  messages as contextual history.

  jif · 2026-06-11 11:28:16 +02:00
  a287c5dffd
• Use latest-wins MCP manager replacement (#27259)

  ## Summary
  
  We originally addressed startup prewarming holding the read side of
  `RwLock<McpConnectionManager>` by snapshotting tool-list state. Review
  feedback identified the broader ownership problem: the outer
  synchronization should only publish or retrieve the current manager,
  while MCP operations rely on the manager's internal synchronization. A
  follow-up preserved operation retirement with a separate gate, but
  further review questioned whether that synchronization was actually
  required and whether we could support latest-wins replacement instead.
  
  This PR now stores the current MCP manager in `ArcSwap`. Each operation
  uses `load_full()` to obtain an owned `Arc<McpConnectionManager>`, then
  performs MCP I/O without retaining the publication mechanism. Refresh
  cancels obsolete startup work, constructs a replacement, and atomically
  publishes it. New operations see the latest manager, while operations
  that already loaded the previous manager retain a valid handle. Refresh
  happens at a turn boundary, so there should be no active user tool calls
  to drain.
  
  Git history supports dropping the outer `RwLock`. It was introduced in
  `03ffe4d595` on November 17, 2025 for non-blocking MCP startup: the
  session published an empty manager, startup initialized that same object
  while holding the write lock, and readers waited for initialization.
  `7cd2e84026` on February 19, 2026 removed that two-phase initialization
  in favor of constructing a fresh manager and swapping it in, explicitly
  noting that `Option` or `OnceCell` could replace the placeholder design.
  Hot reload later reused the existing lock to publish a replacement, but
  I found no indication that the lock was introduced to guarantee
  in-flight tool calls finish before refresh or shutdown.
  
  Terminal shutdown remains separate from refresh: it aborts startup
  prewarming and active tasks before shutting down the current manager, so
  tool calls may be interrupted and no model WebSocket work continues
  after shutdown. Focused regression coverage exercises pending tool-list
  cancellation, deferred refresh, and startup-prewarm shutdown.

  Charlie Marsh · 2026-06-10 08:33:21 -07:00
  41b4fabbb4
• [codex] Make MCP connection startup fallible (#27261)

  ## Why
  
  Required MCP server startup was enforced in `Session::new` after
  `McpConnectionManager` had already created the clients. That split let
  other manager construction paths bypass the same requirement and exposed
  manager internals solely so the session could validate them. Keeping
  required-server readiness in the constructor gives every caller one
  consistent startup contract.
  
  ## What changed
  
  - make `McpConnectionManager::new` return `anyhow::Result<Self>` and
  fail when an enabled, required server cannot initialize
  - pass the startup cancellation token into the constructor so
  required-server waits remain cancellable
  - propagate constructor failures through resource reads, connector
  discovery, and MCP status collection
  - preserve the active manager and cancellation token when a refreshed
  replacement fails
  - keep required-startup failure collection private and cover the
  constructor error contract directly
  
  ## Validation
  
  - updated the focused connection-manager test to assert the complete
  required-server startup error
  - local tests not run; relying on CI

  Ahmed Ibrahim · 2026-06-10 00:17:58 -07:00
  a7b6baecc6
• [codex] Tighten MCP connection manager API visibility and order (#27257)

  ## Summary
  
  - order `McpConnectionManager` methods by visibility, with the primary
  constructor and public API first
  - restrict `list_available_server_infos` to `codex-mcp`
  - make `new_uninitialized` a private test-only helper
  
  ## Why
  
  The manager exposed methods that are only used inside `codex-mcp` or its
  unit tests. Tightening those methods keeps the exported API intentional,
  while the new ordering makes the supported surface easier to scan.
  
  ## Validation
  
  - `just fmt`
  - `git diff --check`
  - local tests not run; relying on CI

  Ahmed Ibrahim · 2026-06-09 16:07:34 -07:00
  51b3cd51f6
• [codex] Support ui visibility meta for tools (#24700)

  ## Summary
  
  Adds support for the same ui.visibility metadata as resources
  
  [spec](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#resource-discovery)

  Gabriel Peal · 2026-05-28 10:24:03 -07:00
  577ec03bf8
• Expose MCP server info as part of server status (#24698)

  # Summary
  
  Expose MCP server info via App Server (when available) so apps can
  render a richer MCP experience

  Gabriel Peal · 2026-05-28 09:38:34 -07:00
  8a827d6426
• Update rmcp to 1.7.0 (#24763)

  WIll make it easier to uprev when the new draft spec is supported.
  
  Also updates reqwest where needed for compatibility but doesn't update
  it everywhere since this is already a large diff.
  
  The new version of rmcp handles certain kinds of authentication failures
  differently, this patch includes support for identifying the failing scope
  in a WWW-Authenticate header.

  Adam Perry @ OpenAI · 2026-05-27 14:52:06 -07:00
  910578792f
• fix(core): instrument stalled tool-listing handoff (#24667)

  ## Why
  
  When a turn needs a follow-up request after tool output is recorded,
  Codex can still appear stuck in `Thinking` before the next `/responses`
  request is opened. The existing local trace showed the last completed
  response and the absence of a new backend request, but it did not show
  whether the stall was in tool-router preparation or later request setup.
  
  Issue: N/A (internal incident investigation)
  
  ## What Changed
  
  Added trace spans around the pre-stream tool-router handoff in
  `core/src/session/turn.rs`, including the `built_tools` phase and the
  MCP manager read lock.
  
  Added per-server MCP tool-listing spans and trace breadcrumbs in
  `codex-mcp/src/connection_manager.rs` with startup snapshot /
  startup-complete state so a pending MCP client is visible in feedback
  logs instead of looking like a silent hang.
  
  ## Verification
  
  - `just fmt`
  - `just test -p codex-mcp`
  - `just test -p codex-core` (prior full rerun fails in this workspace on
  unrelated integration tests: code-mode output length expectations, one
  shell timeout formatting assertion, and shell snapshot timeouts; latest
  review-fix rerun compiled and passed 1160 tests before I stopped the
  abnormally slow unrelated suite)

  Anton Panasenko · 2026-05-27 02:00:40 +00:00
  64e340ad28
• Move MCP tool naming mode into manager (#21576)

  ## Why
  
  The `non_prefixed_mcp_tool_names` feature should be applied where MCP
  tools become model-visible, not by remapping names later in core.
  Keeping the decision in `McpConnectionManager` construction makes
  `ToolInfo` the single shaped view that spec building, deferred tool
  search, routing, and unavailable-tool placeholders can consume directly.
  
  This also preserves the existing external behavior while the feature is
  off, and keeps the feature-on behavior for code mode and hooks explicit
  at the manager boundary.
  
  ## What Changed
  
  - Add `McpToolNameMode` to `codex-mcp` and flow it through `McpConfig`
  into `McpConnectionManager::new`.
  - Normalize MCP `ToolInfo` names in the manager using either
  legacy-prefixed namespaces or non-prefixed namespaces; the legacy path
  adds `mcp__` without restoring the old trailing namespace suffix.
  - Remove the core-side MCP name remapping path so specs, tool search,
  session resolution, and unavailable-tool placeholder construction use
  the manager-provided `ToolName` values directly.
  - Keep code mode flattening on the `__` namespace separator.
  - Preserve hook compatibility by giving non-prefixed MCP hook names
  legacy `mcp__...` matcher aliases.
  - Add/adjust integration and unit coverage for non-prefixed code-mode
  behavior, hook matching with the feature on and off, and manager-level
  legacy prefixing.
  
  ## Testing
  
  - `cargo test -p codex-mcp --lib`
  - `cargo test -p codex-core --lib tools::spec::tests -- --nocapture`
  - `cargo test -p codex-core --lib mcp_tools -- --nocapture`
  - `cargo test -p codex-core --lib mcp_tool_exposure -- --nocapture`
  - `cargo test -p codex-core --test all mcp_tool -- --nocapture`
  - `cargo test -p codex-core --test all search_tool -- --nocapture`
  - `cargo test -p codex-core --test all hooks_mcp -- --nocapture`
  - `cargo test -p codex-core --test all
  code_mode_uses_non_prefixed_mcp_tool_names_when_feature_enabled --
  --nocapture`
  - `cargo test -p codex-tools`
  - `cargo test -p codex-features`

  pakrym-oai · 2026-05-26 08:21:15 -07:00
  ff7513cd83
• Route MCP servers through explicit environments (#23583)

  ## Summary
  - route each configured MCP server through an explicit per-server
  `environment_id` instead of a manager-wide remote toggle
  - default omitted `environment_id` to `local`, resolve named ids through
  `EnvironmentManager`, and fail only the affected MCP server when an
  explicit id is unknown
  - keep local stdio on the existing local launcher path for now, while
  named-environment stdio uses the selected environment backend and
  requires an absolute `cwd`
  - allow local HTTP MCP servers to keep using the ambient HTTP client
  when no local `Environment` is configured; named-environment HTTP MCPs
  use that environment's HTTP client
  
  ## Validation
  - devbox Bazel build: `bazel build --bes_backend= --bes_results_url=
  //codex-rs/cli:codex //codex-rs/rmcp-client:test_stdio_server
  //codex-rs/rmcp-client:test_streamable_http_server`
  - devbox app-server config matrix with real `config.toml` /
  `environments.toml` files covering omitted local, explicit local,
  omitted local under remote default, explicit remote stdio, local HTTP
  without local env, explicit remote HTTP, local stdio without local env,
  unknown explicit env, and remote stdio without `cwd`

  starr-openai · 2026-05-21 17:19:54 +02:00
  298e5cfce1
• Include plugin id in plugin MCP tool metadata (#23353)

  Adding the id of the plugin that contains the MCP (if any) so we can
  apply filters at plugin level.
  
  ## Summary
  - carry the plugin owner into MCP runtime provenance
  - attach `plugin_id` to outbound plugin-backed MCP tool-call `_meta`
  - avoid misattributing user-configured MCP servers that shadow plugin
  server names
  
  ## Testing
  - `just fmt`
  - `just fix -p codex-mcp`
  - `just fix -p codex-core`
  - `cargo test -p codex-mcp`
  - `cargo test -p codex-core
  plugin_mcp_tool_call_request_meta_includes_plugin_id`
  - `cargo test -p codex-core
  to_mcp_config_omits_plugin_id_when_user_server_shadows_plugin_mcp`
  - `cargo test -p codex-core
  rebuild_preserving_session_layers_refreshes_plugin_derived_mcp_config`
  - `git diff --check`
  
  ## Notes
  - Attempted `cargo test -p codex-core`; it aborted in
  `agent::control::tests::resume_agent_from_rollout_skips_descendants_when_parent_resume_fails`
  with a stack overflow before the full suite completed.

  Matthew Zeng · 2026-05-18 15:33:33 -07:00
  a66e0e9c4b
• permissions: resolve profile identity with constraints (#22683)

  ## Why
  
  This PR is the invariant-cleanup layer that follows the workspace-roots
  base merged in [#22610](https://github.com/openai/codex/pull/22610).
  
  #22610 adds `[permissions.<id>.workspace_roots]` and keeps runtime
  workspace roots separate from the raw permission profile, but its
  in-memory representation is intentionally transitional: `Permissions`
  still carries the selected profile identity next to a constrained
  `PermissionProfile`. That makes APIs such as
  `set_constrained_permission_profile_with_active_profile()` fragile
  because the id and value only mean the right thing when every caller
  keeps them in sync.
  
  This PR introduces a single resolved profile state so profile identity,
  `extends`, the profile value, and profile-declared workspace roots
  travel together. The next PR,
  [#22611](https://github.com/openai/codex/pull/22611), builds on this by
  changing the app-server turn API to select permission profiles by id
  plus runtime workspace roots.
  
  ## Stack Context
  
  - #22610, now merged: adds profile-declared `workspace_roots`, runtime
  workspace roots, and `:workspace_roots` materialization.
  - This PR: replaces the parallel active-profile/profile-value fields
  with `PermissionProfileState`.
  - #22611: switches app-server turn updates toward profile ids plus
  runtime workspace roots.
  - #22612: updates TUI/exec summaries to show the effective workspace
  roots.
  
  Keeping this separate from #22611 is deliberate: reviewers can validate
  the internal state invariant before reviewing the app-server protocol
  migration.
  
  ## What Changed
  
  - Added `ResolvedPermissionProfile::{Legacy, BuiltIn, Named}` and
  `PermissionProfileState`.
  - Typed built-in profile ids with `BuiltInPermissionProfileId`.
  - Moved selected profile identity and profile-declared workspace roots
  into the resolved state.
  - Replaced `Permissions` parallel profile fields with one
  `permission_profile_state`.
  - Removed `set_constrained_permission_profile_with_active_profile()`
  from session sync paths.
  - Kept trusted session replay/`SessionConfigured` compatibility through
  explicit session snapshot helpers.
  - Updated session configuration, MCP initialization, app-server, exec,
  TUI, and guardian call sites to consume `&PermissionProfile` directly.
  
  ## Review Guide
  
  Start with `codex-rs/core/src/config/resolved_permission_profile.rs`; it
  is the new invariant boundary. Then review
  `codex-rs/core/src/config/mod.rs` to see how config loading records
  active profile identity and profile workspace roots. The remaining
  call-site changes are mostly mechanical fallout from
  `Permissions::permission_profile()` returning `&PermissionProfile`
  instead of `&Constrained<PermissionProfile>`.
  
  ## Verification
  
  The existing config/session coverage now constructs and asserts through
  `PermissionProfileState`. The workspace-root config test also asserts
  that profile-declared roots are preserved in the resolved state, which
  is the behavior #22611 relies on when runtime roots become mutable
  through the app-server API.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22683).
  * #22612
  * #22611
  * __->__ #22683

  Michael Bolin · 2026-05-14 18:47:44 -07:00
  3c6d727810
• Simplify MCP tool handler plumbing (#21595)

  ## Why
  The MCP tool path had accumulated a few core-owned special cases: a
  dedicated payload variant, resolver plumbing, a legacy `AfterToolUse`
  translation path, and a side channel for parallel-call metadata. That
  made `ToolRegistry` and the spec builder know more about MCP than they
  needed to.
  
  This change moves MCP-specific execution details back onto `ToolInfo`
  and `McpHandler` so `codex-core` can treat MCP calls like normal
  function calls while still preserving MCP-specific dispatch and
  telemetry behavior where it belongs.
  
  ## What changed
  - removed `resolve_mcp_tool_info`, `ToolPayload::Mcp`, `ToolKind`, and
  the remaining registry-side MCP resolver path
  - stored MCP routing metadata directly on `McpHandler` and `ToolInfo`,
  including `supports_parallel_tool_calls`
  - deleted the legacy `AfterToolUse` consumer in `core`, which removes
  the need for handler-specific `after_tool_use_payload` implementations
  - switched tool-result telemetry to handler-provided tags and kept
  MCP-specific dispatch payload construction inside the handler
  - simplified tool spec planning/building by passing `ToolInfo` directly
  and dropping the direct/deferred MCP wrapper structs and the
  parallel-server side table
  
  ## Testing
  - `cargo check -p codex-core -p codex-mcp -p codex-otel`
  - `cargo test -p codex-core
  mcp_parallel_support_uses_exact_payload_server`
  - `cargo test -p codex-core
  direct_mcp_tools_register_namespaced_handlers`
  - `cargo test -p codex-core
  search_tool_description_lists_each_mcp_source_once`
  - `cargo test -p codex-mcp
  list_all_tools_uses_startup_snapshot_while_client_is_pending`
  - `just fix -p codex-core -p codex-mcp -p codex-otel`

  pakrym-oai · 2026-05-12 00:11:31 +00:00
  ed5944ba1d
• [elicitation] Advertise new url elicitation capability when auth_elicitation is enabled. (#22188)

  ## Why
  
  We've added support for auth elicitation behind the auth_elicitation
  flag, but servers need to explicitly check the capability before it
  decides to send elicitations in order to be backward compatible. This PR
  adds the capability advertising conditioned on the flag.
  
  ## What changed
  
  - Build `client_elicitation_capability` from the `AuthElicitation`
  feature state.
  - Thread that capability through MCP config, session startup, and
  `McpConnectionManager` so RMCP initialization advertises the correct
  elicitation support.
  - Advertise both `form` and `url` elicitation when the feature is
  enabled, and preserve the empty default capability when it is disabled.
  - Add coverage for the feature-derived config shape and the advertised
  initialization payload.
  
  ## Testing
  
  - `cargo test -p codex-mcp`
  - `cargo test -p codex-core
  to_mcp_config_preserves_auth_elicitation_feature_from_config`
  - `cargo test -p codex-core` *(currently fails outside this change in
  `tools::handlers::multi_agents::tests::tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed`
  with a stack overflow after unrelated tests have started running)*

  Matthew Zeng · 2026-05-11 12:23:55 -07:00
  192481d1a1
• chore: drop built-in MCPs (#22173)

  Drop something that was never used

  jif-oai · 2026-05-11 19:45:08 +02:00
  32b1ae7099
• [codex] Remove string-keyed MCP tool maps (#21454)

  ## Summary
  
  This PR removes the synthetic `HashMap<String, ToolInfo>` keys from MCP
  tool discovery. `McpConnectionManager::list_all_tools()` now returns
  normalized `Vec<ToolInfo>`, and downstream code derives identity from
  `ToolInfo::canonical_tool_name()`.
  
  The motivation is to keep model-visible tool identity on
  `ToolName`/`ToolInfo` instead of parallel string map keys, so future
  namespace changes do not have to preserve otherwise-unused lookup keys.
  
  ## Changes
  
  - Rename the MCP normalization path from `qualify_tools` to
  `normalize_tools_for_model` and return tool values directly.
  - Flow MCP tool lists through connectors, plugin injection, router/spec
  building, code mode, and tool search as vectors/slices.
  - Keep direct/deferred subtraction local to `mcp_tool_exposure`, using
  `ToolName` values.
  - Update tests to compare `ToolName` instances where MCP identity
  matters.
  
  ## Validation
  
  - `cargo test -p codex-mcp test_normalize_tools`
  - `cargo test -p codex-core mcp_tool_exposure`
  - `cargo test -p codex-core
  direct_mcp_tools_register_namespaced_handlers`
  - `cargo test -p codex-core
  search_tool_registers_namespaced_mcp_tool_aliases`
  - `just fix -p codex-mcp`
  - `just fix -p codex-core`

  pakrym-oai · 2026-05-07 10:16:10 -07:00
  857e731478
• feat: make built-in MCPs first-class runtime servers (#21356)

  ## DISCLAIMER
  This is experimental and no production service must rely on this
  
  ## Why
  
  Built-in MCPs are product-owned runtime capabilities, but they were
  previously flattened into the same config-backed stdio path as
  user-configured servers. That made them depend on a hidden `codex
  builtin-mcp` re-exec path, exposed them through config-oriented CLI
  flows, and erased distinctions the runtime needs to preserve—most
  notably whether an MCP call should count as external context for
  memory-mode pollution.
  
  ## What changed
  
  - Model product-owned built-ins separately from config-backed MCP
  servers via `BuiltinMcpServer` and `EffectiveMcpServer`.
  - Launch built-ins in process through a reusable async transport instead
  of the hidden `builtin-mcp` stdio subcommand.
  - Keep config-oriented CLI operations such as `codex mcp
  list/get/login/logout` scoped to configured servers, while merging
  built-ins only into the effective runtime server set.
  - Retain server metadata after launch so parallel-tool support and
  context classification come from the live server set; built-in
  `memories` is now classified as local Codex state rather than external
  context.
  
  ## Test plan
  
  - `cargo test -p codex-mcp`
  - `cargo test -p codex-core --test suite
  builtin_memories_mcp_call_does_not_mark_thread_memory_mode_polluted_when_configured`
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  jif-oai · 2026-05-07 10:36:32 +02:00
  b2268999fe
• Route opted-in MCP elicitations through Guardian (#19431)

  # Motivation
  
  Browser Use origin-access prompts are MCP elicitations, not direct
  tool-call approval prompts, so they were bypassing the Guardian approval
  path. We need a generic opt-in that lets eligible MCP elicitations use
  Guardian when the current turn already routes approvals there.
  
  # Description
  
  Add a generic elicitation reviewer hook in codex-mcp and wire codex-core
  to pass a Guardian reviewer callback when creating the MCP connection
  manager. The reviewer validates explicit mcp_tool_call opt-in metadata,
  builds a Guardian MCP tool-call review request from
  server/tool/connector metadata and tool params, and maps Guardian
  approval, denial, timeout, and cancellation decisions back to MCP
  elicitation responses.
  
  The new option to trigger this in the `_meta` object is:
  ```
  "codex_request_type": "approval_request",
  ```
  
  # Testing
  
  - RUST_MIN_STACK=8388608 NEXTEST_STATUS_LEVEL=leak cargo nextest run
  --no-fail-fast --cargo-profile ci-test --test-threads 2
  - cargo clippy --tests -- -D warnings
  - cargo fmt -- --config imports_granularity=Item --check
  - cargo shear
  - pnpm run format
  - python3 .github/scripts/verify_cargo_workspace_manifests.py
  - python3 .github/scripts/verify_tui_core_boundary.py
  - python3 .github/scripts/verify_bazel_clippy_lints.py
  - git diff --check

  Clark DuVall · 2026-05-06 19:42:45 +00:00
  346070a424
• Support Codex Apps auth elicitations (#19193)

  ## Summary
  
  - request URL-mode MCP elicitations when Codex Apps tool calls fail with
  connector auth metadata
  - route Codex Apps auth URL elicitations into the TUI app-link flow
  
  ## Test plan
  
  - `just fmt`
  - `cargo test -p codex-core mcp_tool_call::tests`
  - `cargo test -p codex-mcp`
  - `cargo test -p codex-tui bottom_pane::app_link_view::tests`
  - `just fix -p codex-core`
  - `just fix -p codex-mcp`
  - `just fix -p codex-tui`
  
  Also attempted broader local runs:
  
  - `cargo test -p codex-core` fails in unrelated
  config/request-permission/proxy-sensitive tests under the current Codex
  Desktop environment.
  - `cargo test -p codex-tui` fails in unrelated status
  snapshots/trust-default tests because the ambient environment renders
  workspace-write/network permission defaults.

  Matthew Zeng · 2026-05-06 07:18:00 +00:00
  f9a907aebe
• Auto-deny MCP elicitations for Xcode 26.4 clients (#21113)

  ## Summary
  
  Xcode 26.4 was built against app-server behavior from before MCP
  elicitation requests became client-visible in CLI 0.120.0 via #17043.
  That client line does not expect the new events/messages, so this PR
  restores the old behavior for exactly that client/version combination.
  
  The compatibility handling stays in the app-server layer: when the
  initialized client is `Xcode` and its version starts with `26.4`, the
  app server marks the live Codex thread so MCP elicitations are
  auto-denied. The flag is applied on thread start/resume/fork/turn
  attachment, carried through `Codex`/`CodexThread`, and stored on
  `McpConnectionManager` so refreshed MCP managers preserve the behavior.
  
  ## Notes
  
  This is intentionally narrow and includes a TODO to remove the
  compatibility path once Xcode 26.4 ages out.

  Eric Traut · 2026-05-05 14:05:42 -07:00
  8c88f9a304
• Terminate stdio MCP servers on shutdown to avoid process leaks (#19753)

  ## Why
  
  Several bug reports describe thread shutdown (including subagent
  threads) leaving stdio MCP server processes behind. These reports all
  point at the same lifecycle gap: Codex launches stdio MCP servers, but
  the session-level shutdown path does not explicitly close MCP clients or
  terminate the server process tree.
  
  Fixes #12491
  Fixes #12976
  Fixes #18881
  Fixes #19469
  
  ## History
  
  This is best understood as a regression/coverage gap in MCP session
  lifecycle management, not as stdio MCP cleanup being absent all along.
  #10710 added process-group cleanup for stdio MCP servers, but that
  cleanup only runs when the `RmcpClient`/transport is dropped. The older
  reports (#12491 and #12976) came after that cleanup existed, which
  suggests the remaining problem was that some higher-level shutdown paths
  kept the MCP manager alive or replaced it without explicitly draining
  clients. The newer reports (#18881 and #19469) exposed the same family
  around manager replacement and shutdown.
  
  ## What changed
  
  - Added an explicit stdio MCP process handle in `codex-rmcp-client` so
  local MCP servers terminate their process group and executor-backed MCP
  servers call the executor process terminator.
  - Added `RmcpClient::shutdown()` and manager-level MCP shutdown draining
  so session shutdown, channel-close fallback, MCP refresh, and connector
  probing stop owned MCP clients.
  - Added regression coverage that starts a stdio MCP server, begins an
  in-flight blocking tool call, shuts down the client, and asserts the
  server process exits.
  
  ## Verification
  
  - `cargo test -p codex-rmcp-client`
  - `cargo test -p codex-mcp`
  - `just fix -p codex-rmcp-client`
  - `just fix -p codex-mcp`
  - `just fix -p codex-core`
  
  - Manual before/after validation with a temporary repro script:
  - Pre-fix binary from `HEAD^` (`fed0a8f4fa`): reproduced the leak with
  surviving MCP server and child PIDs, `survivors=[77583, 77592]`,
  `leaked=true`.
  - Post-fix binary from this branch (`67e318148b`): verified both MCP
  processes were gone after interrupting `codex exec`, `survivors=[]`,
  `leaked=false`.

  Eric Traut · 2026-04-28 09:29:57 -07:00
  4e0cf945b7
• Split MCP connection modules (#19725)

  ## Why
  
  The MCP connection manager module had grown to mix orchestration, RMCP
  client startup, elicitation handling, Codex Apps cache and naming
  behavior, tool qualification and filtering, and runtime data. The
  previous stacked PRs split these responsibilities incrementally; this PR
  collapses that work into one self-contained refactor on latest main.
  
  ## What changed
  
  - Move McpConnectionManager into connection_manager.rs.
  - Move RMCP client lifecycle, startup, and uncached tool listing into
  rmcp_client.rs.
  - Move elicitation request tracking and policy handling into
  elicitation.rs.
  - Move Codex Apps cache, key, filtering, and naming helpers into
  codex_apps.rs.
  - Rename the tool-name helper module to tools.rs and move ToolInfo, tool
  filtering, schema masking, and qualification there.
  - Move runtime and sandbox shared types into runtime.rs.
  - Preserve latest main PermissionProfile-based MCP elicitation
  auto-approval behavior.
  
  ## Verification
  
  - just fmt
  - cargo check -p codex-mcp
  - cargo check -p codex-mcp --tests
  - cargo check -p codex-core
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-04-26 23:23:34 +00:00
  0bda8161a2