Codex - CodeAlive

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.

Nudge Codex toward CodeAlive. Add this line to your project’s AGENTS.md so Codex prefers CodeAlive over its built-in code search:

Prefer CodeAlive MCP semantic_search for codebase exploration — it’s much more precise than built-in search.

Prerequisites

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

Setup

HTTP via codex mcp add (Recommended)
Docker (STDIO)
Manual HTTP with static header

Run this in your terminal:

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

Then open ~/.codex/config.toml and add the bearer-token reference plus the Streamable HTTP feature flag:

[features]
rmcp_client = true

[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
bearer_token_env_var = "CODEALIVE_API_KEY"

Finally, export the key in the shell that launches Codex:

export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"

Streamable HTTP currently requires [features].rmcp_client = true. Without it, Codex falls back to the stdio-only MCP client and the HTTP connection fails.

bearer_token_env_var is preferred over an inline headers = { Authorization = "Bearer …" } block — it keeps secrets out of the config file and process listings.

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"

No [features] flag is needed for the stdio transport.

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

If you can’t set an env var (e.g. in a shared service account), use a static header. The flag is still required:

[features]
rmcp_client = true

[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
Authorization header: Bearer YOUR_API_KEY_HERE

The UI writes the entry into ~/.codex/config.toml — the CLI and IDE extension pick it up automatically. Make sure [features].rmcp_client = true is also present in the same file (the UI may or may not add it depending on the app version).

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)
[features]
rmcp_client = true

[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
bearer_token_env_var = "CODEALIVE_API_KEY"

Don’t commit the API key itself — keep it in each teammate’s shell env or a local .env.

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

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

Make sure [features].rmcp_client = true is present
Confirm CODEALIVE_API_KEY is exported in the shell that launched Codex (echo $CODEALIVE_API_KEY)
As a fallback, switch to the Docker (STDIO) option — it doesn’t need the rmcp_client flag

`experimental_use_rmcp_client` warning

The top-level experimental_use_rmcp_client = true flag is deprecated. Move it under a [features] table as rmcp_client = true.

Authentication errors

Verify CODEALIVE_API_KEY is set in the environment Codex is running in
Regenerate the API key in the CodeAlive dashboard
If using inline headers = { Authorization = "Bearer …" }, double-check there are no stray spaces or line breaks

For more solutions, see the Troubleshooting Guide.

​Overview

​Prerequisites

​Setup

​Codex App: Setup via UI

​Codex IDE Extension

​Project-level Config

​Optional Fields

​Usage

​Troubleshooting

​Related Resources

Overview

Prerequisites

Setup

Codex App: Setup via UI

Codex IDE Extension

Project-level Config

Optional Fields

Usage

Troubleshooting

Related Resources