How to add an MCP server to Codex, and why pasting JSON fails

Codex, OpenAI's coding agent, can use MCP servers just as Claude can, but it keeps them somewhere different and in a different format. Most setup instructions you will find online are written for Claude, as a block of JSON. Codex reads a TOML file instead, so pasting that JSON in does nothing. The good news is that one command writes the file for you. Muse, a $29 Mac app for saved pictures, links and notes, is the worked example at the end: its built-in MCP server joins Codex with that one command.

The commands and file format below follow OpenAI's Codex MCP documentation. We ran each one with Codex CLI 0.157 on a Mac, and the file contents shown are what Codex wrote.

How do I add an MCP server to Codex?

Run codex mcp add with a name, two dashes, and the command that starts the server:

codex mcp add <name> -- <command> [args...]

For example, a server that runs through npx:

codex mcp add airtable -- npx -y airtable-mcp-server

Everything after the two dashes is the server's own command, passed along untouched. If the server needs an API key, add --env before the dashes:

codex mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server

Codex replies "Added global MCP server" and the server is ready the next time you start a session. For a server on the internet rather than on your Mac, use --url with its address in place of the dashes and command.

Where is the Codex MCP config file?

Codex stores servers in ~/.codex/config.toml, in your home folder. The .codex folder is hidden in Finder; press Command-Shift-Period to show hidden files, or open it from Terminal with open ~/.codex/config.toml.

Here is what the command with the API key wrote, exactly as Codex saved it:

[mcp_servers.airtable]
command = "npx"
args = ["-y", "airtable-mcp-server"]

[mcp_servers.airtable.env]
AIRTABLE_API_KEY = "YOUR_KEY"

Each server gets its own section headed [mcp_servers.NAME], and environment variables go in a section below it. OpenAI's documentation says the Codex CLI, the Codex IDE extension and the ChatGPT desktop app share this one file, so a server you add once is there in each.

You can also scope a server to a single project by putting it in a .codex/config.toml inside that project's folder. Codex only reads project files in projects you have marked as trusted.

Can I paste Claude's JSON setup into Codex?

No, and this is the most common reason a server "does nothing" in Codex. A setup written for Claude looks like this:

{
  "mcpServers": {
    "muse": { "command": "/Applications/Muse.app/Contents/MacOS/muse-mcp" }
  }
}

To use it with Codex, take the name and the command out of it and give them to codex mcp add. The JSON above becomes:

codex mcp add muse -- /Applications/Muse.app/Contents/MacOS/muse-mcp

If the JSON has an args list, those go after the command, separated by spaces. If it has an env section, each entry becomes an --env KEY=VALUE. And if you would rather write the TOML yourself, the section name is mcp_servers, with an underscore; a heading such as [mcpServers] or [mcp.servers] is simply ignored.

Here is a fuller conversion. The official filesystem server's Claude setup has a command of npx and an args list of "-y", "@modelcontextprotocol/server-filesystem" and a folder. For Codex, that is one line, with the args in the same order after the command:

codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

If a folder name contains a space, wrap that path in quotes on the command line, otherwise Terminal splits it in two and the server looks for folders that do not exist.

[mcp_servers.airtable]
command = "npx"
args = ["-y", "airtable-mcp-server"]
startup_timeout_sec = 20
tool_timeout_sec = 120
enabled = true

How do I check which servers Codex can see?

• codex mcp list prints every server with its command, its environment (with values hidden) and whether it is enabled.
• codex mcp get <name> shows one server.
• codex mcp remove <name> removes it from the file.
• Inside a Codex session, type /mcp to see what is connected.

If a server is listed but its tools never appear, run its command on its own in Terminal. A wrong path or a missing program shows up there straight away. Paths should be full ones, starting from /.

A worked example: Codex and your saved library

Codex is built for code, but it is happy to work through any tools you give it. Muse includes an MCP server from version 1.0.40, so Codex can search your saved pictures, links and notes, save new ones and file them into collections. Turn on Allow AI Apps in Muse's Settings > Intelligence, then run:

codex mcp add muse -- /Applications/Muse.app/Contents/MacOS/muse-mcp

That writes exactly this to config.toml:

[mcp_servers.muse]
command = "/Applications/Muse.app/Contents/MacOS/muse-mcp"

Then ask it something like "save these links to Research, tagged pricing". Anything an AI app removes goes to Muse's Trash, which only you can empty, and hidden items stay out of sight. The Connect AI Apps guide has the rest.