Connecting Codex to COORDINATOR (MCP)

Last updated: September 9, 2026

Before you start

You need an MCP key from Settings → Developer → Connect via MCP in COORDINATOR. If you don't have one, read Using COORDINATOR inside other AI apps first — key setup takes a minute.

Codex authenticates to remote MCP servers with a bearer token, which is exactly what a COORDINATOR key is. The CLI, the IDE extension, and the ChatGPT desktop app share the same configuration, so you only set this up once. Two ways to do it — pick one.

ChatGPT desktop app

Unlike Claude, there is no separate connector to add here: the ChatGPT desktop app reads the same Codex MCP configuration, so follow Option A or B below and the desktop app picks it up automatically — no second setup. After configuring, open the desktop app's Settings → MCP servers to confirm COORDINATOR is listed, then Restart from that screen so it connects. In a conversation, /mcp shows connected servers.

You can also add the server from that same screen (Add server → Streamable HTTP → URL), but the bearer token still has to come from the shared config — the in-app Authenticate button is for OAuth servers, and COORDINATOR uses a bearer key instead. The one-command setup below is the reliable path.

Option A — one command (recommended)

Codex can store the token as an environment variable reference, which keeps the secret out of the config file:

export COORDINATOR_API_KEY="your-key-here"
codex mcp add coordinator --url https://api.coordinator.co/mcp --bearer-token-env-var COORDINATOR_API_KEY

This writes the server entry to ~/.codex/config.toml and reads the token from your environment each time it connects. Make sure COORDINATOR_API_KEY is exported in whatever shell launches Codex, or the server will fail to start.

Check it landed:

codex mcp list

In an interactive session, /mcp shows whether the server is connected and which tools are available.

Option B — edit config.toml yourself

Open ~/.codex/config.toml (in the IDE extension: gear menu → Codex Settings → Open config.toml) and add:

[mcp_servers.coordinator]
url = "https://api.coordinator.co/mcp"
bearer_token_env_var = "COORDINATOR_API_KEY"

with COORDINATOR_API_KEY exported in your environment. If you'd rather keep everything in the file (simpler, less secure — never commit this file), use a static header instead:

[mcp_servers.coordinator]
url = "https://api.coordinator.co/mcp"

[mcp_servers.coordinator.http_headers]
Authorization = "Bearer your-key-here"

Restart Codex after editing. Project-scoped .codex/config.toml files also work, but only in projects you've marked trusted.

What Codex can do once connected

Read and ask about your chats, Studio workspaces, library, and groups; check which integrations are connected; draft new documents, sheets, and apps for your approval. The full permission and quota picture is in the overview.

Common issues

Server shows as "not logged in" / suggests codex mcp login

That hint is meant for OAuth servers — COORDINATOR uses bearer-token auth, so ignore the login suggestion. The real cause is almost always the token: the env var isn't exported in Codex's environment, the key was revoked, or it was pasted incompletely. Confirm with codex mcp list --json that the entry points at the right URL and variable, then re-export and restart.

"Auth required" on startup

Same family as above: Codex reached our server but the bearer token was missing or rejected. Check the env var is set (echo $COORDINATOR_API_KEY, non-empty), and that the key still exists under Settings → Developer in COORDINATOR.

Works in CLI but not the IDE extension

Both read the same ~/.codex/config.toml, but the extension inherits a different environment. If you used bearer_token_env_var, the variable must be visible to the IDE process too — set it in your shell profile (or OS environment settings) and restart the IDE, not just the extension panel. The static http_headers form sidesteps this entirely.

Rate limit errors

You're past 60 requests per minute on that key, or two turns are already running. Wait and retry — and don't run parallel Codex sessions against the same key if you keep hitting the concurrency cap.

Contact support

Email [email protected] from the address on your COORDINATOR account with the output of codex mcp list --json (redact the token value itself), the exact error, and when it started. Never send your API key.