Codex MCP Settings: A config.toml Reference and Examples
Codex MCP settings reference for config.toml, with HTTP and stdio examples, CLI equivalents, CODEX_HOME behavior, OAuth, and safer secret handling.
Author: Variant Team. Variant is built by a small team working on HTML-native presentation tools, MCP workflows, and agent-editable decks.
Codex MCP settings share a TOML file with the rest of your Codex configuration. The challenge is keeping HTTP servers, stdio commands, environment variables, and authentication details in the right places.
This page covers the supported keys and commands. The CLI is safer for one server. The full examples help when you maintain several.
#Quick answer
Codex stores MCP server definitions in ~/.codex/config.toml under [mcp_servers.<name>]. The codex mcp add command writes the server table for you, while CODEX_HOME moves the whole Codex configuration directory to another location.
Use url for a streamable HTTP server. Use command and optional args for a stdio server. Keep tokens out of config.toml; use OAuth or --bearer-token-env-var instead.
#File location and table shape
The default Codex MCP config file is:
~/.codex/config.tomlEach server gets a named table:
[mcp_servers.example]
url = "https://mcp.example.com/mcp"Set CODEX_HOME when you need a different Codex directory. For example, this command uses the config file at /opt/team-codex/config.toml for that process:
CODEX_HOME=/opt/team-codex codex mcp listCODEX_HOME affects the whole Codex configuration directory. Check it when a server appears in one shell but not another.
#Codex MCP configuration keys
These are the server keys covered by this reference. Run codex mcp add --help before using a key or flag that is not listed here.
| Key or table | Type | Applies to | Meaning |
|---|---|---|---|
url | String | HTTP | Streamable HTTP server URL. |
command | String | stdio | Executable Codex starts. |
args | String array | stdio | Ordered executable arguments. |
[mcp_servers.<name>.env] | TOML table | stdio | Child process environment variables. |
startup_timeout_sec | Number | stdio | Seconds to wait for startup. |
An HTTP definition needs url. A stdio definition needs command and can include the other stdio keys. Do not combine both transports in one server table.
#CLI flags and their config role
codex mcp add is the normal way to create a definition.
| Flag | Applies to | Purpose | Config relationship |
|---|---|---|---|
--url <URL> | HTTP | Adds a streamable HTTP server. | Maps to url. |
--env KEY=VALUE | stdio | Passes a child process variable. | Maps to the env table. |
--bearer-token-env-var <ENV_VAR> | HTTP | Reads a token from an environment variable. | Keeps the token value out of TOML. |
--oauth-client-id <CLIENT_ID> | HTTP | Supplies an OAuth client ID. | Configures the OAuth client. |
--oauth-resource <RESOURCE> | HTTP | Identifies the OAuth resource. | Configures the OAuth resource. |
For a stdio server, everything after -- is the command and its arguments:
codex mcp add local-search -- node /absolute/path/search-server.mjsThe separator tells Codex that the remaining tokens belong to the child command.
#Complete HTTP server example
This is the smallest useful HTTP definition:
[mcp_servers.docs]
url = "https://mcp.example.com/mcp"The CLI equivalent is:
codex mcp add docs --url https://mcp.example.com/mcpCheck the saved definition with:
codex mcp get docsFor OAuth, add the server and run codex mcp login docs. The list shows Not logged in until login succeeds.
#Complete stdio server example
This definition starts Node, passes arguments and variables, and extends the startup wait:
[mcp_servers.local_docs]
command = "node"
args = ["/Users/example/tools/docs-server.mjs", "--index", "/Users/example/docs"]
startup_timeout_sec = 30
[mcp_servers.local_docs.env]
DOCS_MODE = "readonly"
LOG_LEVEL = "warn"The CLI can create the command, arguments, and environment values:
codex mcp add local_docs \
--env DOCS_MODE=readonly \
--env LOG_LEVEL=warn \
-- node /Users/example/tools/docs-server.mjs --index /Users/example/docsAdd startup_timeout_sec to the generated table when needed. An absolute script path works across changing working directories.
#Several MCP servers in one config file
Global Codex settings and multiple MCP definitions can sit side by side:
model = "your-model-name"
model_reasoning_effort = "medium"
[mcp_servers.team_api]
url = "https://mcp.example.com/mcp"
[mcp_servers.local_docs]
command = "node"
args = ["/Users/example/tools/docs-server.mjs"]
startup_timeout_sec = 30
[mcp_servers.local_docs.env]
DOCS_MODE = "readonly"
[mcp_servers.variant]
url = "https://mcp.variant.art/mcp"Simple server names made of letters, numbers, and underscores do not need extra quoting.
#CLI equivalents and file effects
Use JSON output when a script needs structured data.
| Command | What it does | Effect on config.toml |
|---|---|---|
codex mcp list | Lists servers, status, and auth. | Reads all definitions. |
codex mcp list --json | Lists servers as JSON. | Reads all definitions. |
codex mcp get <NAME> | Shows one server. | Reads one definition. |
codex mcp get <NAME> --json | Shows one server as JSON. | Reads one definition. |
codex mcp add <NAME> --url <URL> | Adds an HTTP server. | Writes a server table. |
codex mcp add <NAME> -- <command> [args...] | Adds a stdio server. | Writes command and args. |
codex mcp remove <NAME> | Removes a server. | Removes its definition. |
codex mcp login <NAME> | Starts OAuth login. | Leaves the server table intact. |
codex mcp login <NAME> --scopes a,b | Requests OAuth scopes. | Leaves the server table intact. |
codex mcp logout <NAME> | Logs out. | Leaves the server table intact. |
If the list looks wrong, compare codex mcp get <NAME> with its table. Run codex doctor for installation, configuration, or authentication problems.
For a step-by-step connection flow, see how to add an MCP server to Codex. For presentation-specific setup, the Codex MCP documentation uses the same commands.
#Global settings near MCP tables
Two common global keys often appear above the MCP tables:
| Key | Meaning |
|---|---|
model | Selects the default model. |
model_reasoning_effort | Selects the default reasoning effort. |
Use -c key=value for a per-run config override. Use -p or --profile when you want to layer a named profile configuration. Use --strict-config to catch configuration typos instead of silently carrying a bad assumption into a session.
These are global controls, not fields inside [mcp_servers.<name>].
#Keep secrets out of config.toml
Never paste a bearer token into config.toml. The file can enter a backup, dotfiles repository, or screen recording.
For an HTTP server that accepts a bearer token, point Codex at the name of an environment variable:
codex mcp add private_api \
--url https://mcp.example.com/mcp \
--bearer-token-env-var PRIVATE_MCP_TOKENSet PRIVATE_MCP_TOKEN through your secret manager or shell. The flag names the variable, not its value.
Prefer OAuth when the server supports it. OAuth keeps login and refresh behavior out of the static server table. See Codex MCP OAuth troubleshooting when a configured HTTP server remains logged out.
#Valid config that can still bite you
| Pattern | Why it hurts | Better choice |
|---|---|---|
| A server name with dots or spaces | TOML can interpret punctuation as table syntax unless the name is quoted correctly. | Prefer a simple name such as team_docs. |
| A relative stdio command or script path | The server can fail when Codex starts from a different working directory. | Use an executable on PATH or an absolute path. |
| A slow package launcher with no timeout | First-run package setup can take longer than the default wait. | Set startup_timeout_sec for a known slow stdio server. |
| A token written directly in TOML | The credential can leak through backups or dotfiles. | Use OAuth or --bearer-token-env-var. |
The right file under the wrong CODEX_HOME | Codex reads a different configuration directory. | Run codex mcp list with the same environment as the failing session. |
A quoted TOML name can be valid, but simple names are easier to review.
#Connect Variant to Codex
Variant has a hosted streamable HTTP server for editable HTML and CSS decks:
codex mcp add variant --url https://mcp.variant.art/mcpThen verify the definition:
codex mcp get variantVariant uses OAuth by default. The first MCP request opens a browser for sign-in, and tokens refresh automatically. Scoped bearer tokens are available for headless setups.
Use Variant when Codex should create, preview, revise, and export a deck. Use stdio for a local process you own. The presentation MCP server guide explains the workflow.
#Related reading
- Use Codex to generate editable presentation decks
- What is an MCP server for presentations?
- Variant MCP documentation
#FAQ
#Where are Codex MCP settings stored?
Codex MCP settings are stored in ~/.codex/config.toml under [mcp_servers.<name>] tables. If CODEX_HOME is set, Codex reads config.toml from that directory instead.
#How do I add an MCP server to Codex config.toml?
Run codex mcp add <NAME> --url <URL> for a streamable HTTP server. For a stdio server, run codex mcp add <NAME> -- <command> [args...]. Codex writes the matching server table to config.toml.
#What is the difference between url and command?
The url key defines a remote streamable HTTP MCP server. The command key defines a local stdio server process that Codex starts, with optional args and environment variables.
#Can I keep several MCP servers in one Codex config file?
Yes. Add one [mcp_servers.<name>] table per server in the same config.toml file. Use a distinct, simple name for each server so codex mcp get <NAME> and codex mcp remove <NAME> stay clear.
#Should API tokens go in config.toml?
No. Keep bearer token values out of config.toml. Use OAuth when available, or pass --bearer-token-env-var <ENV_VAR> so Codex reads the credential from the process environment.
#How do I check whether Codex loaded my MCP server?
Run codex mcp list to see configured HTTP and stdio servers, status, and authentication state. Run codex mcp get <NAME> for one definition, or add --json to either command for scripted inspection.
#When is Variant the wrong MCP server choice?
Variant is the wrong choice when the task is not about presentation decks, when a deck must remain in another editor as its source of truth, or when you need a custom local process. Variant fits workflows where Codex creates and edits HTML and CSS slides through hosted presentation tools.
#The short version
Codex MCP settings belong in named tables inside ~/.codex/config.toml, and codex mcp add is the safest way to write them. Use url for HTTP or command and args for stdio, then inspect the result with codex mcp get. Keep secrets out of TOML and check CODEX_HOME when the expected server disappears. Variant is a good hosted choice for agent-editable presentation decks, but it is not a general replacement for every MCP server or an editor that must remain your source of truth.
Next step
Use Codex to build your next deck
Connect Codex to the Variant MCP server, create a short deck, render a preview, then revise one slide.