# Codex

Source: /docs/mcp/connect/codex

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 [#get-a-token]

Open the dashboard's [Connect an agent](https://app.orbitorca.com/mcp) 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-the-server]

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

```toml
[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 [#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 [#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:

```toml
[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 [#approvals]

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

```toml
[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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) for the other modes and per-tool overrides.

## OAuth instead of a token [#oauth-instead-of-a-token]

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

```bash
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](https://app.orbitorca.com/mcp) 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](/docs/mcp/scopes-and-safety).