How do you set up MCP servers for a repository in Codex?

Where does Codex keep MCP settings?

Codex, OpenAI's coding agent, stores MCP server settings in TOML files, not in a separate JSON file. MCP (the Model Context Protocol) is the open standard that lets an agent call tools that a separate program, the MCP server, offers. OpenAI's Codex MCP page, read on 16 October 2026, says: "By default this is ~/.codex/config.toml, but you can also scope MCP servers to a project with .codex/config.toml (trusted projects only)."

The basic configuration page gives the order Codex applies settings, highest first:

Layer	File or source	Applies to
1. CLI flags	--config or -c overrides	One run
2. Project config	.codex/config.toml, from the project root down to your working folder; "closest wins; trusted projects only"	One repository or subfolder
3. Profile	~/.codex/profile-name.config.toml, chosen with --profile	Whenever you pick it
4. User config	~/.codex/config.toml	Every project on your machine
5. System config	/etc/codex/config.toml on Unix	Every user on the machine

So a server defined in the repository's .codex/config.toml sits above your personal defaults, and a .codex/config.toml in a subfolder beats one at the root when you start Codex inside that subfolder.

Why does codex mcp add not create a project server?

Because it writes to your user file. The Codex CLI source, mcp_cmd.rs, describes add as "add a server launcher entry to ~/.codex/config.toml", and after it runs it prints Added global MCP server '<name>'. Its usage line is codex mcp add [OPTIONS] <NAME> (--url <URL> | -- <COMMAND>...). That is the right command for a server you want everywhere. For a server that belongs to one repository, write the project file by hand.

How do you add a server to one repository?

1. In the repository root, create a folder named .codex.
2. Inside it, create config.toml. This example adds a local server that Codex starts as a process (a stdio server) and a remote server reached by URL (a Streamable HTTP server):

# .codex/config.toml
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp"]
startup_timeout_sec = 20

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT"
default_tools_approval_mode = "prompt"

3. Set the token in your shell, not in the file: export GITHUB_PAT=.... The bearer_token_env_var key names the variable; Codex reads its value and sends it in the Authorization header.
4. Start Codex from inside the repository and trust the project when asked. The approvals and security page notes that Codex "may also start in read-only until you explicitly trust the working directory (for example, via an onboarding prompt or /permissions)". An untrusted project's .codex/ layer is skipped entirely.
5. In the Codex composer, type /mcp to list the connected servers and check that both appear.

The server names, commands and URL above are examples; take the real install line from each server's own documentation. The CodeLifter MCP directory lists the install line and licence for each server it covers, including Playwright MCP.

Which settings can you put on a project server?

The MCP page lists these keys for every [mcp_servers.<name>] table:

Key	What it does	Default
command, args, cwd	Start a stdio server, with arguments and a working folder	None
env, env_vars	Set variables for the server, or forward named variables from your shell	None
url, bearer_token_env_var, env_http_headers	Reach a remote server and authenticate from environment variables	None
startup_timeout_sec, tool_timeout_sec	Time limits for start-up and for each tool call	10 and 60 seconds
enabled, required	Switch a server off without deleting it; make start-up fail if it cannot start	Enabled, not required
enabled_tools, disabled_tools	Allow list, then deny list applied after it	All tools
default_tools_approval_mode	auto, prompt, writes or approve; writes "prompts for tools that aren't marked read-only"	Not set

For a shared repository, enabled_tools is the useful one: list only the tools the project needs, so a teammate who pulls the repository does not get a server with write tools they never asked for. How hosts, clients and servers fit together is covered in the parts of an MCP setup thread.

What should you commit, and what should stay out?

Commit .codex/config.toml only if it holds no secrets. Use bearer_token_env_var, env_http_headers or env_vars for anything sensitive, because those keys store a variable name, not its value. Do not put a token in env, which sets literal values, and do not run codex mcp add --oauth-client-secret for a project server: the MCP page says Codex then "saves the secret as mcp_servers.example.oauth.client_secret in config.toml." For the GitHub server, the token scopes thread explains how narrow the token can be.

Remember that the file runs commands. A command line in a cloned repository is code that starts on your machine once you trust the project, so read .codex/config.toml before you say yes, the same way you would read a package.json script.

Short version

• Put repository servers in .codex/config.toml at the repository root, one [mcp_servers.<name>] table each.
• Codex loads it only after you trust the project; check with /mcp.
• codex mcp add writes to ~/.codex/config.toml, so it creates global servers, not project ones.
• Keep tokens in environment variables and name them with bearer_token_env_var or env_vars.
• Use enabled_tools and default_tools_approval_mode to keep a shared server narrow.