Codex

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)
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.

Quick install: Run npx @codealive/installer to automatically configure CodeAlive for Codex. See the Installation Guide for details.

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 below.

Prerequisites

Any of: Codex CLI, Codex App, or Codex IDE Extension
CodeAlive account (Sign up here)
Indexed repositories in your CodeAlive dashboard

Setup

HTTP with browser OAuth (Recommended)
HTTP with API key
Docker (STDIO)
Manual HTTP with static header

Run this in your terminal:

codex mcp add codealive --url https://mcp.codealive.ai/api

Authenticate once in your browser:

codex mcp login codealive

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

API-key authentication remains supported for existing setups:

[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:

export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"

Add to ~/.codex/config.toml:

[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:

export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"

env_vars forwards values from the parent shell — safer than embedding the key in args.

If you can’t use OAuth or an environment variable, use a static header:

[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
headers = { Authorization = "Bearer YOUR_API_KEY_HERE" }

Verify the entry was registered:

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

# .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):

[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:

AGENTS.md — CodeAlive section

## 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 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

"Find all error handling patterns in the payment service"
"Explain how the user registration flow works"
"Search for database migration code"

Troubleshooting

MCP server not detected

Run codex mcp list to confirm Codex sees the entry
Verify the config file is at ~/.codex/config.toml (or project-level .codex/config.toml)
Check TOML syntax (use a TOML validator)
Restart Codex (CLI, App, or reload the IDE extension)

HTTP transport not working

Confirm the URL is exactly https://mcp.codealive.ai/api
Run codex mcp login codealive and complete the browser redirect
Run codex mcp get codealive to inspect the stored configuration

Authentication errors

Run codex mcp logout codealive, then codex mcp login codealive
Confirm the browser shows the expected CodeAlive consent screen and callback host
If you intentionally use the API-key fallback, verify CODEALIVE_API_KEY is exported in the shell that launched Codex

For more solutions, see the Troubleshooting Guide.

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.

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

Overview

Prerequisites

Setup

Codex App: Setup via UI

Codex IDE Extension

Project-level Config

Optional Fields

Instructing Codex via AGENTS.md

Usage

Troubleshooting

Instruct Your Agent

​Overview

​Prerequisites

​Setup

​Codex App: Setup via UI

​Codex IDE Extension

​Project-level Config

​Optional Fields

​Instructing Codex via AGENTS.md

​Usage

​Troubleshooting

​Related Resources

​Instruct Your Agent

Overview

Prerequisites

Setup

Codex App: Setup via UI

Codex IDE Extension

Project-level Config

Optional Fields

Instructing Codex via AGENTS.md

Usage

Troubleshooting

Related Resources

Instruct Your Agent