Codex CLI integration

OpenAI’s Codex CLI supports MCP servers, giving it access to Oka’s 19 tools for institutional intelligence.

Setup

1. Add to your Codex config

Edit ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[mcp_servers.oka]
command = "npx"
args = ["-y", "@oka-core/reason"]

Caution

Codex uses TOML, not JSON. The key format is [mcp_servers.<name>].

2. Authenticate

In a Codex session, use the login tool:

Use the login tool to authenticate with Oka

This opens your browser to id.oka.so where you sign in or create an account. Your credentials are stored locally and refresh automatically.

CI/CD or headless?

Add an [mcp_servers.oka.env] section with OKA_API_KEY. See API key auth.

3. Verify the connection

codex mcp list

You should see oka listed with its tools.

Codex-specific options

Timeouts

Codex supports per-server timeout configuration:

[mcp_servers.oka]
command = "npx"
args = ["-y", "@oka-core/reason"]
startup_timeout_sec = 15
tool_timeout_sec = 30

Tool filtering

Restrict which Oka tools Codex can use:

[mcp_servers.oka]
command = "npx"
args = ["-y", "@oka-core/reason"]
enabled_tools = ["context", "observe", "decision", "done"]

CLI management

# Add a server
codex mcp add oka -- npx -y @oka-core/reason

# List servers
codex mcp list

# Remove a server
codex mcp remove oka

Tips

• Project-scoped .codex/config.toml only works in trusted projects. Run codex trust in your project root first.
• Set OKA_WORKSPACE in the [mcp_servers.oka.env] section to scope events to your project.
• Use enabled = false to temporarily disable Oka without removing the configuration.