Skip to content

Connecting CodeNavi to OpenAI Codex CLI

Codex CLI talks to CodeNavi over MCP. The integration ships as a bundle, plugins/codex/ (included in every air-gapped package, MIT-licensed). It has two parts because Codex separates them:

  1. The MCP server → ~/.codex/config.toml. This is what gives Codex the 33 tools (41 with the crawler). By default the server advertises an 11-tool core — search/browse/read plus reindex_incremental, reindex_status, index_stats — and loads the rest on demand: reveal_tools() lists the hidden groups, reveal_tools(call="<tool>", args='{…}') reveals and runs one in a single step.
  2. The using-codenavi skill → an installable Codex plugin so Codex prefers semantic search over grep.

Codex ≠ Claude Code. Codex reads ~/.codex/config.toml; it does not read Claude Code's .mcp.json. Wiring one does nothing for the other.

Fast path

cd plugins/codex
./connect-codenavi.sh --env-file ../../.env

connect-codenavi.sh is idempotent: it backs up config.toml, writes the [mcp_servers.codenavi] block, writes the CodeNavi usage rules into ~/.codex/AGENTS.md (see Usage rules below), checks the auth token, and verifies an authenticated tools/list against the exact URL before declaring success. Then export the token and restart Codex:

echo 'export CODENAVI_AUTH_TOKEN=$(grep "^CODENAVI_AUTH_TOKEN=" /path/to/install/.env | cut -d= -f2-)' >> ~/.bashrc
source ~/.bashrc
# restart Codex, then run /mcp — 'codenavi' should be listed

Install the skill bundle (offline):

codex plugin marketplace add ./plugins/codex
# in Codex:  /plugins install codenavi@codenavi

Codex on another machine than the server? The server hands the bundle out itself, no token needed: git clone http://<server-ip>:8765/plugins/codex.git && cd codex (no git? curl -O http://<server-ip>:8765/plugins/codex.zip, which unpacks to codenavi-plugin-codex/). Then export CODENAVI_AUTH_TOKEN=<token> and run ./connect-codenavi.sh --host <server-ip> --port 8765 — there is no .env on the client, so no --env-file.

Usage rules (AGENTS.md)

config.toml wires the MCP server, but Codex does not inject config keys like instructions= / user_instructions= into the model-visible prompt (confirmed via codex debug prompt-input) — so on its own, Codex only reaches for CodeNavi when you name a tool explicitly. connect-codenavi.sh therefore also writes a compact, sentinel-delimited block of CodeNavi usage rules into ~/.codex/AGENTS.md, the durable behavioral surface. Re-runs replace only that block; the rest of your AGENTS.md is left untouched (it also warns if an AGENTS.override.md sits alongside it).

  • --no-agents-md — skip this step (wire the MCP server only).
  • --project — write the rules to a repo-local ./AGENTS.md instead of the global ~/.codex/AGENTS.md, when you only want this one project to get CodeNavi-aware behavior.
  • --agents-file PATH — target a specific file (override for testing).

Manual config.toml

If you'd rather not run the script, append plugins/codex/mcp/config.toml.snippet to ~/.codex/config.toml. The minimal block:

[mcp_servers.codenavi]
url = "http://localhost:8765/mcp"
bearer_token_env_var = "CODENAVI_AUTH_TOKEN"

The three things that bite people

  1. bearer_token_env_var is the NAME of an env var, not the token. Paste the token value and Codex fails at startup with "Environment variable <token> for MCP server 'codenavi' is not set." Keep CODENAVI_AUTH_TOKEN and export it.
  2. Use the unscoped /mcp path unless you know the codebase name. /mcp/<name> returns "Unknown codebase ''" (404) unless <name> is configured — a single-codebase install is usually named default. Check with list_codebases.
  3. Edit config.toml, not .mcp.json. The latter is Claude Code's.

Tool approvals

connect-codenavi.sh auto-approves the read-only query tools (semantic_search, symbol_search, find_callers, impact_analysis, find_references, read_file, …) by writing [mcp_servers.codenavi.tools.<tool>] approval_mode = "approve". Without this, Codex prompts on every call (interactive) or auto-cancels it (non-interactive codex exec) — which silently kills the structural tools and makes CodeNavi look broken. The mutating tools (reindex*, crawl, backup, restore, submit_feedback) are deliberately left gated — a destructive or outbound action should stay a conscious approval.

Under the default lean tool profile the call-graph tools (find_callers, impact_analysis, find_references, graph_neighborhood) arrive through reveal_tools(), and that meta-tool is not auto-approved because it can also run the mutating tools. So the first reveal_tools(call=…) in a session prompts once. Running codex exec non-interactively? Add [mcp_servers.codenavi.tools.reveal_tools] approval_mode = "approve" yourself, knowing it lifts the gate for whatever reveal_tools calls.

Statusline

Codex's /statusline is a built-in segment picker (model, context %, git, tokens, …) with no external-command support yet, so the CodeNavi index-coverage badge from the Claude Code plugin can't be reproduced on Codex today. Upstream: openai/codex#20043, #20244.

The Codex IDE extension

The Codex extension for VS Code, Cursor, Windsurf and JetBrains reads the same ~/.codex/config.toml as the CLI — not the editor's own MCP settings. Wiring the CLI (the script above or codex mcp add) wires both; reload the extension if servers don't appear. The per-editor configs in connecting-vscode.md are for those editors' native MCP clients, not for Codex.

Other MCP clients

Cursor, Windsurf, VS Code, and other MCP-capable clients connect to the same http://localhost:8765/mcp endpoint, but the config shape differs per client (Windsurf uses serverUrl, Cursor needs no type, VS Code uses servers). See connecting-vscode.md for the exact per-client config.