MCP in Codex: config.toml, keys and timeouts
The short version: Codex keeps MCP servers in ~/.codex/config.toml, in [mcp_servers.name] sections. A remote server needs a url, and Codex takes the key from an environment variable whose name you put in bearer_token_env_var. Plus one setting almost everybody misses: by default a tool call is cut off after 60 seconds.
Where Codex keeps MCP servers
Global settings live in ~/.codex/config.toml. For a trusted project you can add a .codex/config.toml at its root, and those servers will only be enabled there. The file is TOML; each server is its own section. What an MCP server is in the first place, and what an agent wants one for, is in the overview of MCP servers.
Step 1. A key in an environment variable
Codex does not store the key in the config — it reads it from the environment when connecting. Get a key (no registration):
A key for Codex
Get an sk-… key right here on the page
Pick any model series — Codex runs on its own model, and the MCP servers only need the key. It is substituted into the line below.
Press it and get your base_url and API key.
No sign-up, no card.
Free. Your key appears right here.
~/.zshrc or ~/.bashrcThe highlighted parts are stand-ins. The button above issues them in seconds, no sign-up.export TWELVER_API_KEY="sk-<your-key>"Open a new terminal, or run source ~/.zshrc, so the variable exists in the current shell.
Step 2. mcp_servers sections in config.toml
[mcp_servers.twelver-web-search]
url = "https://twelver.app/api/mcp/v1/web-search"
bearer_token_env_var = "TWELVER_API_KEY"
[mcp_servers.twelver-image]
url = "https://twelver.app/api/mcp/v1/image-generation"
bearer_token_env_var = "TWELVER_API_KEY"
tool_timeout_sec = 120Note that bearer_token_env_var takes the name of the variable, not the key itself. Codex adds the Authorization: Bearer … header to every request for you.
Or in one command
A server can be added from the terminal and Codex will write the section itself. The name of the variable holding the key still has to be added to the section afterwards (bearer_token_env_var) — or you sign in over OAuth, which needs a registered account:
codex mcp add twelver-web-search --url https://twelver.app/api/mcp/v1/web-search
codex mcp login twelver-web-searchStep 3. Timeouts: why generation "fails" after a minute
Codex has two timeouts per server, and both are worth knowing:
| Setting | Default | What it covers |
|---|---|---|
startup_timeout_sec | 10 seconds | Connecting to the server and fetching its tool list |
tool_timeout_sec | 60 seconds | Executing a single tool call |
A minute is plenty for search. It is not always plenty for generating a high-resolution image. And video generation holds the call open until the clip is ready, which is minutes. If Codex reports a timeout and the tokens were charged anyway, this is exactly that case: the server finished the job, but the client had stopped waiting for the answer. Raise the timeout on the video server in advance:
[mcp_servers.twelver-video]
url = "https://twelver.app/api/mcp/v1/seedance-video-generation"
bearer_token_env_var = "TWELVER_API_KEY"
tool_timeout_sec = 600Keep search global, generation per project
~/.codex/config.toml. Image and video generation are better enabled in the .codex/config.toml of the projects that need them, a frontend or a landing page, say.Step 4. Check it
Run codex and give it a task that needs a tool: "find out what the breaking changes are in the latest major release of our ORM and check whether they touch our code". Codex will call web-search, read the changelog and only then go through the project files. The list of connected servers is printed by:
codex mcp listIf it does not work
| Symptom | Cause | What to do |
|---|---|---|
| 401 on connect | The environment variable is empty in the shell Codex runs in | Check echo $TWELVER_API_KEY; bearer_token_env_var must hold the variable's name, not the key |
| The server cannot connect within 10 seconds | A slow network on the first connection | Raise startup_timeout_sec to 20–30 |
| The call is cut off after a minute | tool_timeout_sec defaults to 60 | Use 120 for image generation, 600 for video |
| The servers are missing in a project | A project .codex/config.toml is only read in a trusted project | Mark the project trusted, or move the sections into ~/.codex/config.toml |
The same "URL + key" pair works in OpenCode and Claude Code. What else a developer should connect besides search is in the shortlist of the best MCP servers.
Frequently asked questions
How do I connect MCP to Codex?
[mcp_servers.name] section to ~/.codex/config.toml. For a remote server give it a url and, if a key is needed, bearer_token_env_var with the name of an environment variable. Or run codex mcp add name --url address and Codex writes the section for you.Where is the Codex MCP config?
~/.codex/config.toml for all projects, and in .codex/config.toml at the root of a trusted project — for that project only.How do I pass a token to an MCP server in Codex?
bearer_token_env_var — Codex adds the Authorization: Bearer header itself. For other headers there is http_headers. If the server supports OAuth, you can sign in with codex mcp login name.Why does an MCP tool in Codex fail with a timeout?
tool_timeout_sec defaults to 60 seconds. Slow tools — video generation, sometimes high-resolution images — do not fit inside that. Raise the value in the server's section, for example to 600 for video.Which MCP servers are useful in Codex?
Try it yourself
Everything in this guide runs inside Twelver
One chat for text, images, video, music and voice — no separate services or subscriptions.
Open Twelver chat