Codex

Sign in

1. Add the server:

   codex mcp add korala --url https://api.korala.ai/mcp

2. Open ~/.codex/config.toml and add two lines to the block the command wrote:

   [mcp_servers.korala]
   url = "https://api.korala.ai/mcp"
   required = true
   startup_timeout_sec = 60

3. Sign in:

   codex mcp login korala

4. Approve the connection on Korala’s consent page. See Permissions and safety.

Why required = true matters

Codex builds each turn’s tools from the MCP servers that have finished connecting. It waits about one second for a server that is not marked required, then leaves out any server still connecting. Korala takes about two seconds to connect, so without required = true Korala’s tools are there in some turns and missing in others.

required = true makes Codex wait for Korala. startup_timeout_sec = 60 gives the connection time on a slow network. The cost: codex exec stops with an error when Korala cannot connect, for example before you run codex mcp login korala.

Install the plugin instead

The Korala plugin for Codex bundles the same server, with required and the timeout already set, and a skill that tells Codex how to draft, prepare, send and track documents.

codex plugin marketplace add korala-ai/codex-plugins
codex plugin add korala@korala
codex mcp login korala

Use the plugin or codex mcp add, not both. Both name the server korala.

API key alternative

For machines where nobody can open a browser, run the local @korala/mcp package with an API key:

codex mcp add korala-local \
  --env KORALA_API_KEY_ID=your-key-id \
  --env KORALA_API_SECRET=your-secret \
  -- npx -y @korala/mcp

npx downloads the package on first run, which can take longer than Codex waits, so add required = true under [mcp_servers.korala-local] too.

API key (CI and headless) lists the environment variables and explains what a test-mode key can reach.