AI Coding Guide

Add an MCP server to Codex CLI: the [mcp_servers] block in config.toml

Codex Published:

Connecting MCP servers to Codex CLI: the [mcp_servers.<name>] block in config.toml, passing tokens through environment variables, and debugging a server that will not connect.

Verified on Sep 7, 2026 These tools change quickly. Please also check the latest official documentation.
#Codex#Codex CLI#MCP#config.toml#integrations
Contents
  1. Writing it in config.toml
  2. Adding servers with codex mcp
  3. Checking the connection
  4. How this compares across the three tools
  5. Summary

Connecting an MCP (Model Context Protocol) server to Codex CLI lets it drive a browser, search documentation or read issues on its own initiative. Codex keeps all of that configuration in config.toml, which means the syntax differs from Claude Code and Gemini CLI even when the underlying server is identical.

This article covers writing the config, adding servers from the command line, checking the connection, and narrowing down a server that won't start.

KEY POINT

What you will learn

  • The [mcp_servers.<name>] block for stdio servers
  • Passing tokens through environment variables rather than the config file
  • A checking order for when a server doesn't connect

Writing it in config.toml

Add one section per server to ~/.codex/config.toml.

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }
KeyMeaning
commandThe command that starts the server
argsArguments to that command, as an array
envEnvironment variables handed to the server process

Values in env are passed when the server starts. Keep tokens out of the file itself and read them from your shell instead.

Never put a token directly in config.toml

config.toml is exactly the kind of file that leaks through backups and shared dotfiles. Write an environment variable reference such as ${GITHUB_TOKEN} in env and keep the real value in your shell. If your version doesn't expand environment variables there, point command at a small wrapper script and read the variable inside the script.

Adding servers with codex mcp

Instead of editing TOML by hand:

codex mcp add playwright -- npx @playwright/mcp@latest
codex mcp list
codex mcp remove playwright

What the command adds is written to config.toml, so you can edit it by hand afterwards. Which subcommands exist varies by version — check codex mcp --help.

Checking the connection

Start Codex and run /mcp in the session to list the registered servers and the tools each provides. If a server is missing or errors, work through this order:

  1. Start the server on its own: run npx @playwright/mcp@latest directly in a terminal. A failed npm download or an old Node.js shows up here.
  2. Check the environment variable: echo $GITHUB_TOKEN. If the shell you launched Codex from doesn't have it, the server doesn't either.
  3. Check the TOML syntax: a missing comma in an array or an unclosed quote is the usual cause. /status shows whether your configuration loaded.
  4. Sandbox network limits: the MCP server itself runs outside the Codex sandbox, but if the commands Codex runs need the network, network_access matters — see Codex approval modes and sandbox.

用語解説

stdio transport: Codex starts the server as a subprocess and talks to it over standard input and output. Most locally-run MCP servers work this way. For remote (HTTP) servers, check the official documentation for your version's support.

How this compares across the three tools

ToolConfig fileFormat
Codex~/.codex/config.tomlTOML, [mcp_servers.<name>]
Claude Code.mcp.json / ~/.claude.jsonJSON, mcpServers
Gemini CLI~/.gemini/settings.json / .gemini/settings.jsonJSON, mcpServers

Because the values you supply — command, args, env — are the same everywhere, a server that works in one tool only needs rewriting into the other's format. For Claude Code see Adding MCP servers to Claude Code, and for Gemini CLI Adding an MCP server to Gemini CLI. For which servers to install first, see Five MCP servers worth installing first.

Summary

  • Put command, args and env under [mcp_servers.<name>] in ~/.codex/config.toml
  • Read tokens from environment variables; never write them into config.toml
  • Check state with /mcp, then debug in order: run the server alone, check the variable, check the TOML
  • The command, args and env values are the same across Claude Code and Gemini CLI, so configurations port over

FAQ

Where does Codex MCP configuration go?
In a [mcp_servers.<name>] section of ~/.codex/config.toml. The codex mcp add command writes it there for you.
Can I reuse a Claude Code .mcp.json as-is?
No. The format differs: Codex uses TOML, so the command, args and env values have to be rewritten. The values themselves carry over unchanged.
Do MCP tools run without approval?
They follow your approval policy. Under on-request, Codex asks when it judges approval is needed.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.

Related articles