Skip to content

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, which you sign in to once with your CyVerse account. See also the sibling pages for Claude Code, Antigravity, and 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.<name>] 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

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 <name> --env K=V -- <command> <args> 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 install1. The result:

# ~/.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; 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.

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.

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:<port>/callback). If the CyVerse page says Invalid parameter: redirect_uri, see Troubleshooting.

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 page.

  1. Codex CLI source, codex mcp add, https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs. ↩

Machine-readable versions of this page: Markdown twin · raw source on GitHub · llms.txt · llms-full.txt (whole site). See For AI agents.