Codex CLI MCP Setup: How to Configure MCP Servers

Codex CLI supports MCP servers through a configuration file. This is how you give the agent access to tools beyond file editing and shell commands. The setup takes a few minutes once you understand the config format.

What MCP Does for Codex

Codex CLI is a terminal coding agent from OpenAI. Out of the box, it reads files, writes code, and runs commands. MCP extends that by connecting it to external tool servers. Each server provides tools that Codex discovers at startup: web search, image generation, data lookups, or anything else the server exposes.

The agent decides when to use a tool based on your prompt and the tool’s description. You don’t call tools manually. You describe what you want, and Codex picks the right tool if one is available.

The config.toml Format

Codex CLI reads MCP server config from ~/.codex/config.toml. Each server gets its own section:

[mcp_servers.my-server]
command = "npx"
args = ["my-mcp-package"]

[mcp_servers.my-server.env]
API_KEY = "sk-abc123"

The structure:

  • command: The executable to run (e.g., npx, node, python).
  • args: An array of arguments passed to the command.
  • env: A table of environment variables passed to the server process.

You can define multiple servers. Each one gets its own [mcp_servers.<name>] block.

Authentication

Most MCP servers need some form of authentication. The standard approach is passing an API key or bearer token through the env table:

[mcp_servers.my-server.env]
API_KEY = "your-key-here"

The server reads this from its environment at startup. Some servers use bearer token auth, others use custom headers. Check the server’s documentation for the expected variable name.

A tip: don’t commit config.toml to version control if it contains API keys. Either keep it in your home directory (the default location) or use a secrets manager to inject values.

Verifying the Connection

Start a Codex session after saving your config. Codex queries each configured MCP server on launch. If a server fails to connect, you’ll see a warning in the output.

To confirm tools loaded, ask Codex something that would require an external tool:

“Search the web for the latest version of Express.js.”

If the search tool is configured, Codex will call it. If not, it will answer from training data (and might be wrong).

Troubleshooting

Server not starting: Verify the command works outside of Codex. Run npx my-mcp-package (or whatever your command is) in a terminal. If it fails there, it will fail in Codex too.

TOML syntax errors: TOML is picky about formatting. Arrays use brackets: args = ["arg1", "arg2"]. Strings need quotes. Use a TOML validator if you’re unsure.

Environment variables not being passed: Make sure the [mcp_servers.<name>.env] section is nested under the correct server name. A typo in the server name creates a disconnected config block that Codex ignores.

Tools not being called: Codex chooses whether to use a tool based on context. If you expect it to search the web but it doesn’t, try being more explicit: “Use web search to find…” This helps during initial testing. Once you’ve confirmed the tool works, Codex will call it on its own in future sessions.

AgentPatch Setup

AgentPatch provides multiple tools through one MCP server: web search, image generation, email, maps, and more. Here’s the config:

The AgentPatch CLI is designed for AI agents to use via shell access. Install it, and your agent can discover and invoke any tool on the marketplace.

Install (zero dependencies, Python 3.10+):

pip install agentpatch

Set your API key:

export AGENTPATCH_API_KEY=your_api_key

Example commands your agent will use:

ap search "web search"
ap run google-search --input '{"query": "test"}'

Get your API key from the AgentPatch dashboard.

Add AgentPatch to ~/.codex/config.toml:

[mcp_servers.agentpatch]
url = "https://agentpatch.ai/mcp"
bearer_token_env_var = "AGENTPATCH_API_KEY"

Then set your API key:

export AGENTPATCH_API_KEY=your_api_key

Replace your_api_key with your actual key from the AgentPatch dashboard. Codex discovers all AgentPatch tools automatically on next start.

Save this and start a new Codex session. Ask it to search for something. If results come back, you’re connected.

Wrapping Up

MCP config in Codex CLI lives in ~/.codex/config.toml. Define a server, pass its auth credentials, and Codex picks up the tools on next launch. AgentPatch bundles a full set of tools behind one server entry, which makes it a good way to test your setup and get productive fast. See the full tool list at agentpatch.ai.

← Back to blog