Codex

Codex is OpenAI's coding agent, available as both a CLI and a macOS desktop app (Codex.app). Both surfaces share the same configuration file at ~/.codex/config.toml, so configuring Macuse once applies to both.

Automatic Setup

1. Open Macuse from your menu bar
2. Click the Server card
3. Under Quick Setup, click the Setup button next to Codex
4. Macuse will append a [mcp_servers.macuse] section to ~/.codex/config.toml
5. Restart Codex (CLI session or desktop app) to apply changes

Manual Configuration

If automatic setup doesn't work, you can manually edit the configuration file.

Config file: ~/.codex/config.toml

Option 1: stdio (Recommended)

Add the following section to ~/.codex/config.toml:

[mcp_servers.macuse]
type = "stdio"
command = "/Applications/Macuse.app/Contents/MacOS/macuse"
args = ["mcp"]

You can also add it via the CLI:

codex mcp add macuse -- /Applications/Macuse.app/Contents/MacOS/macuse mcp

Save the file and restart Codex.

Option 2: HTTP with API Key

If stdio doesn't work, you can connect via HTTP using an API Key:

1. Open Macuse Settings → Connections, click +, enter "Codex" as the name, and click Create
2. Copy the API key immediately (it is only shown once)
3. Export it as an environment variable Codex will read at launch:

export MACUSE_API_KEY="<your_api_key>"

4. Add the following section to ~/.codex/config.toml:

[mcp_servers.macuse]
url = "http://127.0.0.1:35729/mcp"
bearer_token_env_var = "MACUSE_API_KEY"

Or via the CLI:

codex mcp add macuse \
  --url http://127.0.0.1:35729/mcp \
  --bearer-token-env-var MACUSE_API_KEY

5. Restart Codex

See the API Keys page for more details.

Verifying the Connection

1. Open Codex (CLI or desktop app) and start a new session
2. Ask the AI to "list available Macuse tools"
3. If configured correctly, the AI will show the available toolboxes