Setup · Codex CLI

Mako, meet Codex CLI.

How to add an MCP server to OpenAI's Codex CLI

agentmako is a local-first MCP server that wires into Codex CLI through a single TOML block in ~/.codex/config.toml. One block, one restart, and Mako tools are in codex and codex exec.

Prerequisites

  • Node.js 20 or newer
  • Codex CLI installed (codex --version)
  • agentmako on PATH
// install & attach 
$ npm install -g agentmako
$ cd /path/to/your/project
$ agentmako connect . --no-db
$ agentmako doctor

Add to config.toml

Codex looks for MCP servers in ~/.codex/config.toml (Linux/macOS) or %USERPROFILE%\.codex\config.toml (Windows). Append this block:

// ~/.codex/config.toml 
[mcp_servers.mako-ai]
command = "agentmako"
args = ["mcp"]
Windows note If agentmako is a shim (agentmako.cmd), you may need to point Codex at the full path. Run where agentmako in PowerShell to find it, then use that absolute path as command.

Verify in Codex

Start a Codex session from your attached project:

// shell 
$ cd /path/to/your/project
$ codex

Once the session is up, ask Codex to list available tools. You should see Mako tools (context_packet, reef_scout, repo_map, cross_search, ast_find_pattern, etc.) under the mako-ai server.

First task

// prompt 
Before reading any source files, call the mako-ai
context_packet tool with the query:
"locate and explain the auth callback handler".

Show me the packet, then proceed with the task.

If you'd rather drive Mako from a script:

// non-interactive (codex exec) 
$ codex exec "Use mako-ai context_packet for: fix the broken /auth/callback route. Show packet, then patch."

Tell Codex when to use Mako

Codex respects AGENTS.md at the project root. Drop the contents of agentmako's AGENTS.md into your project's AGENTS.md so the agent learns to reach for context_packet before grep.

Result On the same task, Codex with Mako guidance issues 1–2 tool calls; without it, expect 5+ file reads searching for the target. The AGENTS.md entry is the cheapest token win in this whole setup.

Troubleshooting

Codex doesn't see mako-ai

Confirm the TOML key is exactly [mcp_servers.mako-ai] (not [mcp.mako-ai]). Restart any open Codex sessions — the config is read at startup.

Server starts then exits

Run the server manually to see the error: agentmako mcp. If you get a stack trace about a missing project, you haven't run agentmako connect . yet.

Tools call but return empty

Mako needs an attached project per directory. Make sure you launched codex from the same directory you ran agentmako connect in.