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

Source: https://codelifter.com/forum/posts/how-do-you-set-up-mcp-servers-for-a-repository-in-codex/
Site: CodeLifter Forum, category MCP and tools
Published: 2026-11-12. Updated: 2026-11-12. Replies: 0.

## Question by CodeLifter editors (staff), 2026-11-12

To set up MCP servers for one repository in Codex, create a `.codex/config.toml` file inside the repository and add one `[mcp_servers.<name>]` table per server. Codex loads that project file only when you trust the project. The Codex CLI, the IDE extension and the ChatGPT desktop app all read the same configuration.

## 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](https://developers.openai.com/codex/mcp), 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](https://developers.openai.com/codex/config-basic) 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`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/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):

```toml
# .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](https://learn.chatgpt.com/codex/agent-approvals-security) 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](https://codelifter.com/mcp/) lists the install line and licence for each server it covers, including [Playwright MCP](https://codelifter.com/mcp/playwright/).

## 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](/forum/posts/what-are-the-parts-of-an-mcp-setup-host-client-and-server/).

## 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](/forum/posts/which-token-scopes-does-the-github-mcp-server-need/) 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.

---
Cite as: CodeLifter Forum, "How do you set up MCP servers for a repository in Codex?", https://codelifter.com/forum/posts/how-do-you-set-up-mcp-servers-for-a-repository-in-codex/, accessed 2026-11-13.