MCP servers for Codex CLI: config.toml setup step by step

MCP servers give an agent access to external tools: library documentation, an issue tracker, a database, a browser. Codex CLI can connect such servers in two ways, with a command and with an entry in config.toml. Below: how to set up MCP servers for Codex step by step, how to verify they work, and why a gateway connection needs nothing extra.

The parameters come from OpenAI's documentation on MCP in Codex as of October 18, 2026. The set of options keeps growing, so see the Codex configuration reference for the full key list.

What to know up front

Codex keeps MCP settings in config.toml. By default this is ~/.codex/config.toml; for a project you can add .codex/config.toml, but Codex reads it only in trusted projects. The Codex CLI, the IDE extension and the desktop app share one configuration, so a server configured once is available everywhere.

Two kinds of servers are supported:

• STDIO: a process started by a command on your machine;
• Streamable HTTP: a server at an address, with a token in a header or OAuth authorization.

For the general picture read the article MCP server: what it is and why agents need it↗. If you use Claude Code, the same is described in the piece on MCP in Claude Code↗.

Step 1. Make sure Codex works with the gateway

MCP tools do not depend on the model provider: Codex itself calls the server and hands the result to the model. But first you need a working Codex. A minimal Zukko setup in ~/.codex/config.toml:

model = "gpt-6.1-sol"
model_provider = "zukko"

[model_providers.zukko]
name = "zukko"
base_url = "https://api.zukko.pro/v1"
env_key = "ZUKKO_API_KEY"
wire_api = "responses"

Put the fetch_... key from the dashboard↗ in the ZUKKO_API_KEY environment variable. Installation and the alternative method with auth.json are described in the Codex documentation↗. According to the Zukko documentation, GPT and Claude models work in Codex and GLM models do not. The model calls MCP tools like ordinary functions, so pick a model that formats calls correctly for your task and verify that in practice.

Step 2. Add a server with a command

The shortest path for a local server:

codex mcp add context7 -- npx -y @upstash/context7-mcp

This is how OpenAI's documentation connects Context7, a server with developer documentation. The command format is codex mcp add <name> --env VARIABLE=VALUE -- <launch command>. Environment variables for the server are passed with the --env flag.

To see the configured servers:

codex mcp list

codex mcp --help shows all available subcommands. For OAuth servers there is a sign-in: codex mcp login <name>.

Step 3. Or put the server in config.toml

For fine control, edit the file directly. Each server is described by a [mcp_servers.<name>] table.

A local server (STDIO):

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

command is required; args and env are optional. env_vars lists variables from your environment that may be forwarded to the server, so you do not write secrets into the file.

An HTTP server:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

Here url is required and the token comes from an environment variable, not from the file. This is an example from OpenAI's documentation; substitute your own server's address and variables.

Step 4. Limit tools and timeouts

Useful optional fields:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]   # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

• startup_timeout_sec (default 10) and tool_timeout_sec (default 60) help with slow servers;
• enabled = false disables a server without deleting the entry;
• required = true makes startup fail if the server did not start;
• enabled_tools and disabled_tools set allow and deny lists;
• default_tools_approval_mode accepts auto, prompt, writes and approve: writes asks for confirmation for tools not marked read-only.

For those working in a trusted project: the same tables can go in .codex/config.toml inside the repository, and the team gets identical servers.

Step 5. Check that the server is visible

Start codex and type /mcp in the interface: Codex shows the active MCP servers. Then give a simple task that needs a tool, for example "find in the documentation of library X an example call of Y". During the work Codex shows the tool call and asks for confirmation if the mode requires it.

If the server is not visible, check in order: no typo in the table name, the command runs by hand in the same terminal, no enabled = false, startup_timeout_sec is enough. For a local npx it matters that Node.js is in the PATH of the environment Codex starts from.

What MCP servers cost in tokens

Tool descriptions (name, purpose, argument schema) are sent to the model with the request. The more servers and tools, the more input tokens at each step. This matters for the agent budget.

A calculation example. Suppose the connected servers provide 25 tools of 200 tokens of description: 200 × 25 = 5,000 tokens. If a session makes 60 requests, that is 5,000 × 60 = 300,000 input tokens. On gpt-6.1-sol (input $0.27 per 1M, prices as of October 18, 2026) that is 0.3 × 0.27 = $0.081 without cache. If part of the input comes from cache at the read price of $0.013 per 1M, with full cache hits it is 0.3 × 0.013 = $0.0039. The numbers are illustrative: the real size of descriptions depends on the servers. The point is that extra tools cost money and blur the model's choice. Keep only the needed ones via enabled_tools. For GPT models the gateway accounts for cache reads, and cache writes are not billed separately.

A key limit helps control spending: How to set a daily and monthly limit↗. Current prices: GET https://api.zukko.pro/v1/models.

FAQ

Do I need to configure anything in the gateway for MCP?

No. MCP works on the Codex side, and the gateway receives ordinary requests to /v1/responses. You only need a model that can call functions.

How is MCP different from Codex skills and plugins?

MCP is a protocol for connecting external tools. Skills are text instructions with optional scripts, and plugins package skills and, per the documentation, may include MCP servers too. To begin, connecting a server directly as above is enough.

Is it safe to connect third-party MCP servers?

A server gets access to what you give it and may run code on your machine (STDIO). Connect trusted servers, pass secrets through environment variables, and keep the prompt or writes approval mode on.

Why is the server in the config but there are no tools?

Most often the server did not manage to start (raise startup_timeout_sec) or the launch command does not work in Codex's environment. Run the command by hand and check /mcp in the interface.

Create a key in the Zukko dashboard, connect Codex and add your first MCP server with codex mcp add.