Codex

Connect OpenAI Codex, the CLI and the IDE extension, to OrbitOrca with a few lines of config.toml.

Codex reads MCP servers from ~/.codex/config.toml. The Codex CLI and the IDE extension share that file, so one entry covers both.

Get a token

Open the dashboard's Connect an agent page and create a token. Read & write is the recommended choice — it lets the agent deploy, restart, and manage your apps hands-free. Pick read-only if the agent should only look. The full token is shown once, at creation — copy it now.

Add the server

Add this table to ~/.codex/config.toml (create the file if it doesn't exist), with your token in place of {{token}}:

[mcp_servers.orbitorca]
url = "https://api.orbitorca.com/mcp"
http_headers = { "Authorization" = "Bearer {{token}}" }

Run codex mcp list to check that orbitorca is listed. Inside Codex, /mcp shows the servers that are active.

Try it

Ask Codex to "list my OrbitOrca apps". If it comes back with your apps, you're connected.

Keep the token out of the file

Instead of http_headers, Codex can read the token from an environment variable and send it as the bearer token:

[mcp_servers.orbitorca]
url = "https://api.orbitorca.com/mcp"
bearer_token_env_var = "ORBITORCA_TOKEN"

Then set ORBITORCA_TOKEN in the environment Codex starts from, for example in your shell profile.

Approvals

Set default_tools_approval_mode in the server's table to decide when Codex asks before calling a tool. We recommend "writes":

[mcp_servers.orbitorca]
# url and http_headers as above
default_tools_approval_mode = "writes"

With "writes", Codex asks only for tools that aren't marked read-only. Every OrbitOrca read tool is marked read-only, so lookups like status and logs run straight away, while anything that deploys or changes your apps waits for your approval. See Codex's MCP docs for the other modes and per-tool overrides.

OAuth instead of a token

Codex can also connect over OAuth. Add the table with only the url line, then run:

codex mcp login orbitorca

Codex opens the OrbitOrca consent screen in your browser. The consent screen offers write access only when the connecting app asks for it — if it doesn't, the connection is read-only. Use a token when you want the agent to deploy and change apps.

The dashboard's Connect an agent page generates the token table with your token already filled in — copy it from there if you'd rather not edit by hand.

Next: what a token can and can't do.