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

# Codex

> Connect CodeAlive with OpenAI Codex CLI, Desktop App, and IDE Extension

## Overview

OpenAI's Codex ships in three form-factors that share the same configuration file:

* **Codex CLI** — terminal agent (`npm install -g @openai/codex` or `brew install --cask codex`)
* **Codex App** — native macOS / Windows desktop app ([openai.com/codex](https://openai.com/codex/get-started/))
* **Codex IDE Extension** — VS Code (`openai.chatgpt`) and JetBrains (IntelliJ, PyCharm, WebStorm, Rider; 2025.3+)

All three read `~/.codex/config.toml`, so one snippet wires CodeAlive into every Codex surface.

<Tip>
  **Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Codex.
  See the [Installation Guide](/installation) for details.
</Tip>

<Info>
  **Codex defaults to shell-based search (grep/rg) for exploration.** Connecting the MCP server alone won't change that — add routing rules to your project's `AGENTS.md`. See [Instructing Codex via AGENTS.md](#instructing-codex-via-agents-md) below.
</Info>

<Note />

## Prerequisites

* Any of: [Codex CLI](https://github.com/openai/codex), [Codex App](https://openai.com/codex/get-started/), or [Codex IDE Extension](https://developers.openai.com/codex/ide)
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard

## Setup

<Tabs>
  <Tab title="HTTP with browser OAuth (Recommended)">
    Run this in your terminal:

    ```bash theme={null}
    codex mcp add codealive --url https://mcp.codealive.ai/api
    ```

    Authenticate once in your browser:

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

    <Tip>
      Codex uses OAuth 2.1 with PKCE, stores the resulting credential, and refreshes it automatically. No CodeAlive API key belongs in `config.toml`.
    </Tip>
  </Tab>

  <Tab title="HTTP with API key">
    API-key authentication remains supported for existing setups:

    ```toml theme={null}
    [mcp_servers.codealive]
    url = "https://mcp.codealive.ai/api"
    bearer_token_env_var = "CODEALIVE_API_KEY"
    ```

    Export the key in the shell that launches Codex:

    ```bash theme={null}
    export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
    ```
  </Tab>

  <Tab title="Docker (STDIO)">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.codealive]
    command = "docker"
    args = ["run", "--rm", "-i", "ghcr.io/codealive-ai/codealive-mcp:main"]
    env_vars = ["CODEALIVE_API_KEY"]
    ```

    Then export the key in the shell that launches Codex:

    ```bash theme={null}
    export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
    ```

    <Tip>
      `env_vars` forwards values from the parent shell — safer than embedding the key in `args`.
    </Tip>
  </Tab>

  <Tab title="Manual HTTP with static header">
    If you can't use OAuth or an environment variable, use a static header:

    ```toml theme={null}
    [mcp_servers.codealive]
    url = "https://mcp.codealive.ai/api"
    headers = { Authorization = "Bearer YOUR_API_KEY_HERE" }
    ```
  </Tab>
</Tabs>

Verify the entry was registered:

```bash theme={null}
codex mcp list
```

Then restart Codex (CLI, App, or reload the IDE extension) and try in chat:

* "What CodeAlive repositories are available?"
* "Find authentication code in my codebase"

## Codex App: Setup via UI

Codex App (macOS / Windows) lets you manage MCP servers from **Settings → MCP Servers → Add Server**. Fill in:

* **Name**: `codealive`
* **URL**: `https://mcp.codealive.ai/api`
* **Authentication**: Choose browser OAuth when prompted; use an Authorization header only for the API-key fallback

The UI writes the entry into `~/.codex/config.toml`; the CLI and IDE extension pick it up automatically.

## Codex IDE Extension

The Codex extension for VS Code (`openai.chatgpt`) and JetBrains (2025.3+) shares `~/.codex/config.toml` with the CLI and App — there is no separate config surface. In VS Code, open the Codex panel → settings (⚙) → **MCP settings → Open config.toml**.

## Project-level Config

Codex now supports a per-project `.codex/config.toml` at the repository root (for trusted projects). Useful when:

* The whole team should share the same MCP server set
* Different projects need different CodeAlive workspaces

```toml theme={null}
# .codex/config.toml (committed to the repo)
[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
```

Each teammate runs `codex mcp login codealive` and receives their own CodeAlive authorization; no shared credential is committed.

## Optional Fields

The `[mcp_servers.codealive]` table accepts several extras:

| Key                   | Purpose                                                              |
| --------------------- | -------------------------------------------------------------------- |
| `enabled`             | Set to `false` to keep the entry but disable the server              |
| `startup_timeout_sec` | Override the default 10s startup timeout                             |
| `tool_timeout_sec`    | Override the default 60s per-tool timeout                            |
| `tool_allowlist`      | Restrict which tools Codex is allowed to call                        |
| `startup_required`    | If `true`, Codex refuses to start if the server can't initialize     |
| `cwd`                 | Working directory (stdio only)                                       |
| `env_vars`            | List of env-var names to forward into the child process (stdio only) |

Example with a larger tool timeout (useful when relying on the slower `chat` tool):

```toml theme={null}
[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
bearer_token_env_var = "CODEALIVE_API_KEY"
tool_timeout_sec = 120
```

## Instructing Codex via AGENTS.md

Codex reads `AGENTS.md` from the repository root on every run, plus a global `~/.codex/AGENTS.md` that applies to all projects. Repo-root instructions win on conflict; keep org-wide defaults global and project specifics in the repo.

Without instructions, Codex explores with shell search (grep/rg) over the local checkout. Add a CodeAlive section that names that habit explicitly:

```markdown title="AGENTS.md — CodeAlive section" theme={null}
## CodeAlive context engine

CodeAlive MCP tools search server-side indexes of all our repositories —
cross-repo, always in sync with the default branch.

- For exploration questions — "how does X work", "where is Y implemented",
  "what calls Z" — use CodeAlive `semantic_search` FIRST. Do NOT reach for
  shell grep/rg or directory listings for these questions unless CodeAlive
  has returned nothing useful twice.
- Phrase `semantic_search` as a full English sentence, never bare keywords.
  Keep exact identifiers verbatim.
- Use CodeAlive `grep_search` for exact symbol names, literals, error
  messages, config keys, and acronyms — pass the literal text, not a question.
- Read returned artifact identifiers with `fetch_artifacts`; map callers and
  callees with `get_artifact_relationships` before claiming how code flows.
- Shell tools remain correct for files you are actively editing in the
  working tree.
```

Two Codex-specific notes:

* **The MCP server's own instructions help too.** At initialization Codex reads the server-provided `instructions` field, and the CodeAlive server ships tool-usage guidance there. That covers *how* to call the tools; `AGENTS.md` is still needed to set *precedence* over Codex's built-in shell search.
* **`AGENTS.md` is cross-agent.** Claude Code, Cursor's CLI, and most modern agents read the same repo-root file, so this one section covers teammates on other tools. See [Instructing Coding Agents](/guides/instructing-agents) for the general patterns.

## Usage

Once connected, Codex can:

* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services

```text theme={null}
"Find all error handling patterns in the payment service"
"Explain how the user registration flow works"
"Search for database migration code"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not detected">
    1. Run `codex mcp list` to confirm Codex sees the entry
    2. Verify the config file is at `~/.codex/config.toml` (or project-level `.codex/config.toml`)
    3. Check TOML syntax (use a TOML validator)
    4. Restart Codex (CLI, App, or reload the IDE extension)
  </Accordion>

  <Accordion title="HTTP transport not working">
    1. Confirm the URL is exactly `https://mcp.codealive.ai/api`
    2. Run `codex mcp login codealive` and complete the browser redirect
    3. Run `codex mcp get codealive` to inspect the stored configuration
  </Accordion>

  <Accordion title="Authentication errors">
    1. Run `codex mcp logout codealive`, then `codex mcp login codealive`
    2. Confirm the browser shows the expected CodeAlive consent screen and callback host
    3. If you intentionally use the API-key fallback, verify `CODEALIVE_API_KEY` is exported in the shell that launched Codex
  </Accordion>
</AccordionGroup>

<Tip>
  For more solutions, see the [Troubleshooting Guide](/troubleshooting).
</Tip>

## Related Resources

* [Instructing Coding Agents](/guides/instructing-agents)
* [CodeAlive & 1С (1C:Enterprise specifics)](/guides/1c-agents)
* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)
* [Codex MCP Documentation (OpenAI)](https://developers.openai.com/codex/mcp)
* [Codex Config Reference (OpenAI)](https://developers.openai.com/codex/config-reference)

## Instruct Your Agent

Connecting CodeAlive makes its tools available, but the agent may still default to its built-in search. For reliable results, add a short instruction in the agent's native format telling it to prefer `semantic_search` and `grep_search` when exploring indexed code. See [Instructing Coding Agents](https://docs.codealive.ai/guides/instructing-agents).