Docs / Connect / Codex CLI

Connect ModelBrain to Codex CLI

Codex CLI keeps its MCP servers in a single TOML file, so connecting ModelBrain means adding one small table to it and nothing else.

Codex is the one assistant here whose config is TOML rather than JSON, which makes a careless paste the most likely way to break it. The safe move is to add one table and leave everything else in the file exactly as it was.

Where the program lives

This client needs the full path to ModelBrain's mcp_server program. The commands and snippets on this page show the macOS path; on Windows or Linux, put the path for your system in the same place. Write the full path rather than a variable such as %LOCALAPPDATA% or ~, because a client may not expand it.

macOS

/Applications/ModelBrain.app/Contents/MacOS/mcp_server

Windows

C:\Users\you\AppData\Local\Programs\ModelBrain\mcp_server.exe (that is %LOCALAPPDATA%\Programs\ModelBrain\mcp_server.exe, with your own user name). Inside JSON, TOML or a quoted YAML string, double each backslash.

Linux

/home/you/.local/lib/modelbrain/mcp_server, with your own home folder. The install script puts ModelBrain in ~/.local/lib/modelbrain.

Steps

Install ModelBrain if you haven't yet (macOS, Windows or Linux).
Open Codex's config file. It is ~/.codex/config.toml, or config.toml inside the folder named by your CODEX_HOME variable if you set one. Create it if it does not exist.
Add this table at the end of the file. If you already have a table named [mcp_servers.modelbrain], edit it instead of adding a second one, because TOML refuses duplicate tables.
```
[mcp_servers.modelbrain]
command = "/Applications/ModelBrain.app/Contents/MacOS/mcp_server"
```
Start a new Codex session. Codex reads its config when it starts, so a session that was already open will not see the change.
Check it is connected. Ask Codex to remember something, then recall it in a fresh session.

Or use the setup wizard

Available in 0.5.0. Setup for Codex CLI is in ModelBrain 0.5.0 and later. It is tested on sample files only, and the config location comes from OpenAI's docs. We have not yet tried it on a real Codex CLI install. If anything differs on your machine, use the manual steps above and tell us through the Support page.

Open Setup guide from the ModelBrain menu bar or tray icon.
Find the Codex CLI card and click Set up Codex CLI. The card appears only when Codex's ~/.codex folder exists. The wizard never creates a client's folders for you.
Let it write the entry. It adds modelbrain to ~/.codex/config.toml, keeps your other servers, and saves a one-time copy of the original file next to it with the suffix .bak-original. If the file cannot be read as valid, the wizard stops and leaves it alone.
Start a new Codex session so it picks up the ModelBrain tools.

Running the wizard twice is safe: it recognises its own entry and does nothing. The uninstaller removes only the entry that points at ModelBrain.app.

Questions

Does ModelBrain edit Codex's config for me?

Not yet. ModelBrain's setup code can add and remove this table safely and keeps your comments and other settings untouched, but it is not in a released build, so this page uses the manual route.

Where does the command path come from?

It is the program ModelBrain installs inside its app bundle. If you installed ModelBrain somewhere other than Applications, use the path to mcp_server inside that copy of the app.

How do I undo it?

Delete the [mcp_servers.modelbrain] table from config.toml. Your memories are not stored in that file, so nothing is lost.

Has this been tested?

We have tested this configuration against sample files and the ModelBrain setup code, but not yet by hand on a real install of Codex CLI. If ModelBrain does not appear in Codex CLI after you follow these steps, tell us through the Support page and we will fix this guide.

Not installed yet?

Start with the install guide.

Install ModelBrain →

Then

A 10-minute walkthrough: add a folder, ask something that needs two notes, see the citation.

Quickstart →