--- type: Integration Guide title: Codex CLI integration description: How MESA registers its MCP servers with the OpenAI Codex CLI, and how to manage them there. tags: - codex - mcp - registration - config-toml generated: by: "claude-code/2.1.294" at: "2026-10-08T00:00:00Z" sources: - id: codex-mcp resource: "https://developers.openai.com/codex/mcp" title: "Codex MCP documentation" author: "team:openai" - id: install-sh resource: "https://github.com/idss-mesa/docs/blob/main/install.sh" title: "MESA install.sh" author: "team:idss-mesa" - id: codex-source resource: "https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs" title: "Codex CLI source: mcp add / login / logout" author: "team:openai" - id: formation resource: "https://github.com/cyverse-de/formation" title: "Formation source repository (README)" author: "team:cyverse-de" status: stable stale_after: "2027-04-08T00:00:00Z" --- # Codex CLI integration MESA registers `mesa-mcp` and `irods` as **local stdio** MCP servers via `codex mcp add`: Codex launches each binary as a subprocess and talks to it over standard input/output. It registers `formation` as a **streamable HTTP** server pointing at CyVerse's hosted [Formation](https://idss-mesa.github.io/docs/servers/formation-mcp/), which you sign in to once with your CyVerse account. See also the sibling pages for [Claude Code](https://idss-mesa.github.io/docs/claude-code/), [Antigravity](https://idss-mesa.github.io/docs/antigravity/), and [OpenCode](https://idss-mesa.github.io/docs/opencode/). ## Scope Codex has **no scope flag** — every registration is global, stored in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) under a `[mcp_servers.]` table: `command`, `args`, and `env` keys for a local server, `url` for a remote one. Unlike Claude Code there is no project or local scope; the installer's `MCP_SCOPE` variable is ignored for Codex. ## Managing the servers ```bash codex mcp list # show all servers, with their sign-in status codex mcp get mesa-mcp # show one server's config codex mcp remove mesa-mcp codex mcp login formation # sign in to Formation (add --no-browser on a remote machine; Codex 0.156+) codex mcp logout formation # sign out; run it before removing formation, it needs the entry ``` Inside a Codex TUI session, run `/mcp` to verify the servers and their tools loaded. Registration changes are read at startup — **restart the session** to pick them up. ## The registration MESA creates The installer runs `codex mcp add --env K=V -- ` for each local server. For `formation` it writes the table itself, because `codex mcp add --url` starts the browser sign-in straight away, which would stall an unattended install[^codex-source]. The result: ```toml # ~/.codex/config.toml [mcp_servers.mesa-mcp] command = "/home/you/.mesa/.venv/bin/mesa-mcp" args = ["--transport", "stdio"] env = { MESA_MCP_IRODS__USER = "you", MESA_MCP_IRODS__PASSWORD = "••••••" } [mcp_servers.irods] command = "/home/you/.mesa/bin/irods-mcp-server" args = ["-c", "/home/you/.mesa/repos/irods-mcp-server/config-stdio.yaml"] [mcp_servers.formation] url = "https://de.cyverse.org/formation/mcp" tool_timeout_sec = 600 ``` The `env` table on `mesa-mcp` only appears when you installed with [credentials](https://idss-mesa.github.io/docs/credentials/); anonymous installs omit it. `formation` never takes credentials. `tool_timeout_sec = 600` lets `launch_app_and_wait` wait for an app for up to the 9 minutes Formation allows. Codex's default limit is 300 seconds from Codex 0.141, and 60 or 120 seconds in older releases, which can be shorter than a VICE app takes to start. !!! note "mesa-ducklake is not listed here" `mesa-ducklake` is a **library** imported by `mesa-mcp`, not a separate MCP server. Its capabilities surface through `mesa-mcp`'s `mesa_ducklake_*` tools. See [its page](https://idss-mesa.github.io/docs/servers/mesa-ducklake/). ## Signing in to Formation Run `codex mcp login formation`. Codex opens the CyVerse sign-in page in your browser. On Codex 0.156 or newer, `--no-browser` prints the address instead and takes back the address your browser lands on; with an older Codex, update it first with `npm install -g @openai/codex@latest`. Until you sign in, Codex tells you at startup to run `codex mcp login formation`. Remote servers with OAuth sign-in need Codex 0.77 or newer; the installer skips `formation` for an older Codex and says so. CyVerse has not confirmed that its sign-in accepts Codex's callback address (`http://127.0.0.1:/callback`). If the CyVerse page says `Invalid parameter: redirect_uri`, see [Troubleshooting](https://idss-mesa.github.io/docs/troubleshooting/#formation-sign-in-and-connection). To add Formation by hand instead of through the installer, paste the `[mcp_servers.formation]` table above into `~/.codex/config.toml` and run `codex mcp login formation`. Or run `codex mcp add formation --url https://de.cyverse.org/formation/mcp` (it starts the sign-in straight away) and add `tool_timeout_sec = 600` under the `[mcp_servers.formation]` table it writes, because the command does not set a timeout. ## Troubleshooting notes - Servers not visible in a session → restart Codex (config is read at startup), then check `/mcp`. - `/mcp` shows nothing → `codex mcp list`, then inspect `~/.codex/config.toml`. - Re-running the installer updates the entries in place (it removes and re-adds each server), so a stale path after moving `~/.mesa` is fixed by a re-run. It also replaces the local `formation` entry older installs created with the hosted one, and keeps your Formation sign-in. - `formation` needs sign-in → `codex mcp login formation`. More in the general [Troubleshooting](https://idss-mesa.github.io/docs/troubleshooting/) page. [^codex-source]: https://idss-mesa.github.io/docs/Codex CLI source, `codex mcp add`, .