Codex MCP Config: How to Add MCP Servers to OpenAI Codex

Codex is a sharp coding agent on its own, but it only sees what you hand it: your files, your shell, and whatever the model already knows. MCP servers change that. Add one and Codex can query a database, read an issue tracker, search library docs, or generate an image from the same prompt where you ask for code. The catch is that the setup lives in a TOML file and a handful of CLI flags, and one wrong setting means the server silently never shows up.

This article gives you the exact Codex MCP config for local and remote servers, the commands that write it for you, and fixes for the errors people hit most often. The settings and defaults below match the OpenAI Codex documentation as of October 2026.

What MCP Gives Codex

MCP, the Model Context Protocol, is an open standard that lets an AI client call tools exposed by a separate program. That program is the server. Codex is the client. Each server publishes a list of tools with names, descriptions, and input schemas, and Codex decides during a task when one of them is worth calling.

Without servers, Codex edits files and runs shell commands. With them, the same session can query your staging database, pull a design spec, or ask a documentation index how a library behaves in its latest release instead of guessing from training data.

Two Ways to Connect

Codex supports two server types, and every setting you write belongs to one of them.

Local stdio servers start when Codex starts and stop when it exits. Remote servers are already running somewhere else, so Codex only needs the address and, usually, a credential.

Why Bother With Servers

• Fresh context. Docs servers return current API details instead of whatever the model memorized months ago.
• Real data. Database and tracker servers let Codex check a table or a ticket instead of inventing one.
• Fewer copy-pastes. You stop moving text between browser tabs and the terminal.
• Media in the loop. Image and video servers let a coding session produce assets without leaving the terminal.

💡 Tip: Start with one or two servers. Every tool you expose adds to what the model reads before it acts, and a crowded tool list makes its choices less precise.

Where Codex Stores MCP Settings

Codex keeps MCP entries in the same config.toml it uses for every other setting. There is no separate MCP file to hunt for.

The Global File

The default location is ~/.codex/config.toml. On Windows that resolves to a .codex folder inside your user profile. Servers defined here are available in every project you open. The ChatGPT desktop app, the Codex CLI, and the IDE extension all read this same file, so a server you add once shows up in all three.

The Project File

You can also place a .codex/config.toml inside a repository to scope servers to that project. Codex only reads it for trusted projects, which stops a freshly cloned repo from quietly launching commands on your machine. Project files suit servers that only make sense in one codebase, such as a database pointed at that app's dev schema, and they let teammates share a setup through version control.

💡 Tip: Never commit tokens. Reference environment variables by name, as shown below, and keep the values in your shell profile or a secrets manager.

Add a Server From the Terminal

The fastest route is codex mcp add. It writes the TOML entry for you, which removes typos in table names and quoting. Use it first, then open the file to fine tune.

Local stdio Servers

Everything after the double dash is the command Codex will run:

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

Copy Prompt

That registers a server named context7, launched through npx. To pass environment variables, put --env flags before the double dash:

codex mcp add postgres --env DATABASE_URL=postgresql://localhost:5432/mydb -- node pg-mcp-server.js

Copy Prompt

Pick short, lowercase names without spaces. The name becomes the TOML table name and identifies the server in every listing.

Remote HTTP Servers

Remote servers use --url instead of a trailing command:

codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN

Copy Prompt

--bearer-token-env-var names the environment variable that holds the token. The token itself is never written to disk, only the variable name, which beats pasting a secret into a header. Export the variable in the shell that launches Codex:

export GITHUB_PAT_TOKEN="paste-your-token-here"

Copy Prompt

Log In With OAuth

Some hosted servers skip static tokens and use OAuth. Add the server with its URL, then authenticate:

codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear

Copy Prompt

login starts the OAuth flow, usually in your browser, and stores the resulting credentials. When a server documents specific permissions, add --scopes followed by a comma separated list. To drop stored credentials, run codex mcp logout linear.

Edit config.toml by Hand

The CLI is quick, but timeouts, tool filters, and forwarded variables live in the file itself. Every entry is a table named mcp_servers.<name>, with an underscore and a plural.

A Local Server Entry

This is what the context7 command from earlier produces:

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

Copy Prompt

These are the settings a stdio server accepts:

env sets literal values, while env_vars forwards variables that already exist in your shell. Prefer env_vars for anything secret, so the value never appears in the file:

[mcp_servers.postgres]
command = "node"
args = ["pg-mcp-server.js"]
cwd = "/home/dev/db-tools"
env_vars = ["DATABASE_URL"]

[mcp_servers.postgres.env]
LOG_LEVEL = "info"

Copy Prompt

A Remote Server Entry

Remote entries swap command for url:

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"

Copy Prompt

When a service wants a custom header instead of a bearer token, use the two header tables. The second one keeps secrets out of the file:

[mcp_servers.docs]
url = "https://docs.example.com/mcp"

[mcp_servers.docs.http_headers]
X-Team = "platform"

[mcp_servers.docs.env_http_headers]
X-Api-Token = "DOCS_API_TOKEN"

Copy Prompt

Timeouts and Tool Filters

Both server types accept the same optional settings:

A tuned entry looks like this. Replace the tool names with the ones /mcp lists for your server:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled_tools = ["tool_one", "tool_two"]

Copy Prompt

An allowlist is the safer choice for servers that can write or delete data. Use disabled_tools when you trust a server and only want to block one or two risky tools. Use required = true in automated runs, where a missing server should stop the job loudly instead of letting Codex continue without its data.

💡 Tip: Set enabled = false instead of deleting an entry you only need now and then. The settings stay put, and you flip one line to bring it back.

Check That Codex Sees Your Server

Adding a server proves nothing until Codex lists its tools. Run both checks every time.

Use /mcp Inside Codex

In an interactive session, type /mcp. Codex shows the connected servers and the tools each one exposes. If your server is missing, or it appears with no tools, nothing else matters until that is fixed. Restart the session after editing the file so Codex reads the new settings.

Inspect From the Shell

The codex mcp family manages everything without opening an editor:

Add --json to list or get when a script needs to read the output. Once the server shows up, give Codex a task only that server can answer, such as asking for the current signature of a library function your docs server indexes.

Fix the Errors You Will Hit

Most failures come down to a handful of causes. Work through them in this order.

The Server Never Starts

• Startup timeout. The first npx -y run downloads the package, and 10 seconds is often too short. Raise startup_timeout_sec to 30 or more.
• Command not found. Codex launches command itself, so the program must be on the PATH of the shell that started Codex. An absolute path removes the doubt.
• Windows launchers. npx is a script on Windows, and a direct launch can fail. Route it through cmd:

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

Copy Prompt

• Noisy stdout. A stdio server must write only protocol messages to standard output. A startup banner or debug print on stdout breaks the handshake, so send logs to stderr.
• Silent failures. Add required = true while testing so a dead server stops the session with an error you can read.

Variables and Auth Fail

• Unexported variables. bearer_token_env_var and env_vars read from the environment of the process that launched Codex. A variable set in another terminal tab, or a desktop app opened from the dock without your shell profile, will not see it. Check with echo $GITHUB_PAT_TOKEN.
• Rejected tokens. A 401 usually means an expired token or missing permissions. For OAuth servers, run codex mcp logout <name> and then codex mcp login <name> to get a fresh session.
• Ignored project file. A .codex/config.toml in an untrusted project is skipped. Trust the project, or move the entry to the global file.
• Slow tools. If a long query dies at one minute, raise tool_timeout_sec above its 60 second default.

Connect Codex to PicassoIA Tools

Coding sessions often need pictures: a hero image for a landing page, a product mockup, a short clip for a README. PicassoIA offers its generation models through a developer API and through MCP connections, so the same Codex setup can request media without leaving the terminal.

These are the facts worth knowing before you wire it up:

• The API base URL is https://api.picassoia.com/v1, and credentials start with pia_sk_.
• Four models are available through the API and MCP: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video, and Seedance 2.5 Lite, which produces video with audio.
• Jobs are asynchronous. You create a prediction, poll it, then fetch the result.
• Each account can run five predictions at once, shared across credentials and MCP connections, and prompts can reach 4,000 characters.
• MCP connections are managed at picassoia.com/en/mcp/accounts after you log in, and the server address is shown there rather than published on the public site.

Once you have the address, the Codex side is the pattern from earlier. If the page gives you a remote URL, register it with codex mcp add picassoia --url <address> and add a bearer token variable if it asks for one. If it gives you a command to run locally, use the stdio form instead. Plan requirements for API and MCP access are listed on the pricing page, so check them before you build a workflow around it.

Try a Model First

Before you automate anything, test a prompt by hand so you know what a good request looks like:

1. Open the PicassoIA Image page.
2. Write a prompt that names the subject, the setting, the light direction, and a lens such as 35mm or 85mm.
3. Generate, then adjust one detail at a time: the angle, the time of day, or the surface texture.
4. Send the winning image to PicassoIA Image Editor Pro when you need local fixes instead of a full redo.

Chat models help with the config work too. Paste a confusing error into GPT 5.6 Sol or Claude Sonnet 5 and ask which TOML setting it points at. Both are listed on PicassoIA for coding tasks, and a second opinion is cheap before you edit the file.

Make Your First Image Today

You now have everything for a working Codex MCP config: the file locations, the CLI commands, the settings for both server types, a verification routine, and a short list of fixes. Add one server, confirm it with /mcp, and give Codex a real task.

If you want to put it to work on visuals, open PicassoIA Image and write your first prompt. Describe a scene the way a photographer would, with the light, the lens, and the textures, then compare the result with a PicassoIA Video version of the same idea. Browse the full catalog at picassoia.com/en/all-models and see what Picasso IA can make for you.