Codex CLI

Configure Cortexa as a tool provider for OpenAI Codex CLI, giving it access to your captured knowledge during code generation tasks.

Prerequisites

• Cortexa desktop app running with the HTTP API enabled (default: http://127.0.0.1:7373)
• Your bearer token from Settings → External in the Cortexa app
• OpenAI Codex CLI installed
• The cortexa-mcp stdio bridge binary (Codex speaks stdio MCP)

Build the stdio Bridge

Codex CLI uses stdio MCP, so you need the standalone bridge:

cargo build -p cortexa-mcp --release

The binary lands at:

Platform	Path
Windows	target\release\cortexa-mcp.exe
macOS / Linux	target/release/cortexa-mcp

Configure Codex

Edit ~/.codex/config.toml (create the file and directory if they don't exist):

Windows

[mcp_servers.cortexa]
command = "C:\\Users\\YourName\\path\\to\\target\\release\\cortexa-mcp.exe"
env = { CORTEXA_URL = "http://127.0.0.1:7373", CORTEXA_TOKEN = "<TOKEN>" }

macOS / Linux

[mcp_servers.cortexa]
command = "/Users/yourname/path/to/target/release/cortexa-mcp"
env = { CORTEXA_URL = "http://127.0.0.1:7373", CORTEXA_TOKEN = "<TOKEN>" }

Replace the path and <TOKEN> with your actual values.

Using the CLI config instead of env vars

If you have already configured the CLI:

cortexa-cli config --url http://127.0.0.1:7373 --token <TOKEN>

Then you can simplify the TOML to just the command:

[mcp_servers.cortexa]
command = "C:\\Users\\YourName\\path\\to\\target\\release\\cortexa-mcp.exe"

The bridge reads credentials from the CLI config file automatically. Environment variables override the config file when set.

Verify the Connection

Launch Codex:

codex

Inside the Codex session, type:

/mcp

The cortexa_* tools should appear in the list.

Available Tools

Once connected, Codex has access to the Cortexa MCP tools (full list in the MCP Tools reference), including:

Tool	Purpose
cortexa_ingest	Capture text into the encrypted store
cortexa_capture	Structured capture with metadata
cortexa_search	Hybrid keyword + semantic search
cortexa_recent	List most recent captures
cortexa_context	Ambient context brief for current work
cortexa_think	Trigger the Deep Think pipeline
cortexa_brief	Retrieve the structured brief
cortexa_health	Confirm the app is reachable
cortexa_sync_context	Generate .cortexa-context.md for zero-prompt context injection

Usage

Once connected, the Codex agent can search your vault, capture decisions, and pull contextual memory just like any other MCP-connected host. Ask it to check for prior decisions, save architectural choices, or pull ambient context for your current task.

Troubleshooting

/mcp shows no servers — Check that ~/.codex/config.toml is valid TOML and the binary path is correct. Restart Codex after editing the config.

"Connection refused" — Make sure the Cortexa desktop app is running.

423 Locked responses — The vault is locked. Unlock the Cortexa app by entering your passphrase.

Project continuity

Enable Search -> Traceable context for agents in Cortexa, then follow the session-start and handoff workflow. Call cortexa_context with the project at session start, verify current state, and leave a structured cortexa_capture handoff before stopping. Captured check results remain caller reports; exported context files are snapshots and should be refreshed before reuse.