> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colacloud.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI and IDE Setup

> Connect Codex CLI and IDE to COLA Cloud through remote MCP OAuth or API-key Bearer auth.

## Choose a Codex Path

| Path                      | Authentication                          | Best for                                          | Status                   |
| ------------------------- | --------------------------------------- | ------------------------------------------------- | ------------------------ |
| Codex OAuth login         | COLA Cloud OAuth through WorkOS/AuthKit | Interactive Codex CLI or IDE setup                | Preferred when available |
| Codex API-key Bearer auth | COLA Cloud API key in `Authorization`   | Non-interactive setup, CI, and fallback workflows | Supported                |

COLA Cloud's MCP server advertises OAuth discovery for connector clients.
Codex also supports Bearer-token auth for streamable HTTP MCP servers.

## Codex with OAuth

Add the COLA Cloud remote MCP server to your Codex config:

```toml theme={null}
[mcp_servers.colacloud]
url = "https://mcp.colacloud.us/mcp"
```

Then start the OAuth flow:

```bash theme={null}
codex mcp login colacloud
```

Complete the COLA Cloud sign-in in the browser. After login, use `/mcp` in the
Codex UI to confirm the server is connected, then ask Codex to use COLA Cloud.

## Codex with API-Key Bearer Auth

Create a COLA Cloud API key in **Dashboard > API Keys**, then configure Codex to
read it from your environment:

```toml theme={null}
[mcp_servers.colacloud]
url = "https://mcp.colacloud.us/mcp"
bearer_token_env_var = "COLA_API_KEY"
```

Start Codex from a shell that has the key available:

```bash theme={null}
export COLA_API_KEY=cola_xxxx
codex
```

Use prompts like:

* "Use COLA Cloud to find recent bourbon approvals from Kentucky."
* "Fetch details for the most relevant COLA records and include links."
* "Search permittees in New York matching importer."

## Troubleshooting

| Symptom                                                                   | What to check                                                                                                                          |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `codex mcp login colacloud` is not available                              | Use API-key Bearer auth for that Codex version or surface.                                                                             |
| OAuth login succeeds but tool calls fail with `oauth_connection_required` | The OAuth subject is not linked to an active COLA Cloud account. Contact [help@colacloud.us](mailto:help@colacloud.us).                |
| Tools do not appear                                                       | Confirm the config table is `[mcp_servers.colacloud]`, the URL is `https://mcp.colacloud.us/mcp`, and the server is enabled in `/mcp`. |
| API-key setup fails                                                       | Confirm `COLA_API_KEY` is exported in the same shell that starts Codex and that the value starts with `cola_`.                         |