To connect Codex to an MCP server, open the ChatGPT desktop app, go to Settings, then MCP servers, select Add server, enter a name, choose STDIO or Streamable HTTP, paste the command or URL, then save and restart. You can also add it with the codex mcp add command or by editing config.toml, and all three routes write to the same shared configuration.
MCP is the standard that lets ChatGPT and Codex use tools and information from other systems, like looking up a ticket in your support desk. If that's new to you, here's MCP in plain English. This page covers the Codex side: servers set up on your own computer, for the moment someone hands you a server address and says connect it.
One setup for three Codex apps
The detail that saves the most time: the ChatGPT desktop app, the Codex CLI and the IDE extension share one MCP configuration for the same Codex host. Set a server up once and you can switch between them without redoing anything.
The difference that causes the most confusion: ChatGPT on the web works another way. It uses remote MCP tools through plugins and doesn't read your local Codex configuration files, so a server you add in config.toml won't appear in the web app. That's the web route, and I cover it in my ChatGPT MCP guide.
Four ways to connect a server
| Route | Where you do it | Best for |
|---|---|---|
| Desktop app | Settings, then MCP servers | Most people: no commands to type |
| Codex CLI | The codex mcp add command in a terminal | Developers, and servers started by a command |
| config.toml | The config.toml file in the .codex folder in your home folder, or a project's own .codex folder for trusted projects | Fine control: allow lists, timeouts and approval modes |
| Plugin Creator | A Work task in ChatGPT, with the server hosted on Sites | Building a new connection your team can also use on the web |
Here's the desktop app route, step by step, as of October 2026:
- Open Settings and select MCP servers.
- Select Add server.
- Enter a name, choose STDIO or Streamable HTTP, and give the server's command or URL.
- Save the server, then select Restart.
- If the list shows the server needs OAuth, select Authenticate and sign in.
- In the composer, type /mcp to see which servers are connected.
The CLI route is one line. OpenAI's example adds Context7, a free MCP server for developer documentation:
Add a server, then list your servers
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
For servers that support it, codex mcp login handles OAuth sign-in, and inside the Codex terminal app /mcp shows your active servers. The IDE extension has the same Add server flow under its gear menu, finishing with Restart extension.
Local process or web address
When you add a server you pick one of two types. Whoever gave you the server will know which:
- STDIO: the server runs as a local process on your computer, started by a command. The command is required; arguments, environment variables and a working directory are optional.
- Streamable HTTP: the server lives at an address. The URL is required, and it supports a bearer token, OAuth and, for trusted first-party servers, your ChatGPT session.
If you build or maintain a server, Codex reads the instructions the server returns when it starts and treats them as guidance across all its tools. OpenAI says to keep the first 512 characters self-contained, so the most important guidance is there when Codex decides how to use the server.
Sign-in, secrets and where they end up
Some sign-in systems need a pre-registered OAuth client. You pass its client ID when you add the server, and for a confidential client you pass the secret too, read from an environment variable rather than typed in the open. Codex then prints the full callback URL to register with your provider.
Here's the catch I'd tell any team: Codex saves that client secret in config.toml. OpenAI's own instruction is to keep the file private and out of version control. If your config.toml sits in a shared project folder or gets committed to GitHub, the secret goes with it. And on the Plugin Creator route, the docs say to keep passwords, API keys and other secrets out of chat.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Settings that keep it safe
In config.toml each server gets its own table, named mcp_servers followed by a dot and the server's name. Inside it, these options do the safety work:
- default_tools_approval_mode: auto, prompt, writes or approve. The writes mode asks before any tool that isn't marked read-only, which is a sensible middle ground.
- enabled_tools and disabled_tools: an allow list and a deny list, so a server only exposes the tools you want.
- enabled set to false switches a server off without deleting it, and required set to true makes startup fail if the server can't start.
- startup_timeout_sec, default 10 seconds, and tool_timeout_sec, default 60 seconds.
A per-tool approval mode can override the server default, so a search tool can run freely while anything that changes a record still asks first. If you're deciding what to connect in the first place, I've shortlisted MCP servers worth connecting.
When Plugin Creator is the better route
If the goal is a connection the whole team can use in ChatGPT on the web, the docs point to Plugin Creator: start a Work task, choose Plugin Creator, attach your system's API documentation and ask for a read-only plugin with an MCP server hosted on Sites. OpenAI's example is a Support Ticket Lookup that finds a ticket's status, owner and latest update. Old GPT custom actions don't migrate; you rebuild them as a new Sites plugin.
If tools go missing, OpenAI's checks are simple: make sure the Site owner published the latest version and the plugin is installed and connected. If ChatGPT ignores a tool, choose the plugin with @ and ask for a specific lookup. A plugin marked Desktop only needs a supported desktop app.
My advice: I'd add one read-only server from the desktop app first, and skip config.toml editing until you need an allow list or an approval mode.
If you're connecting AI assistants to the tools your team already uses and want the access rules right, that's the kind of AI enablement I help with. I run AI training and workshops for teams, and help businesses with AI enablement and workflow automation, so the busywork runs itself and people get time back. Most of that work is with SaaS marketing teams and small businesses. Here's how we can work together.
Frequently asked questions
How do I add an MCP server to Codex?
In the ChatGPT desktop app, open Settings, then MCP servers, select Add server, choose STDIO or Streamable HTTP, enter the command or URL, save and restart. Or run codex mcp add in a terminal.
Where is the Codex MCP config file?
By default it's config.toml in the .codex folder in your home folder. Trusted projects can also have their own .codex/config.toml.
Why doesn't my Codex MCP server show up in ChatGPT on the web?
ChatGPT web doesn't read local Codex configuration files. On the web, MCP tools come through installed plugins.
Is it safe to store an OAuth secret in config.toml?
Codex saves a confidential client's secret there, so keep the file private and out of version control.
Can I make Codex ask before using an MCP tool?
Yes. Set default_tools_approval_mode to prompt, or to writes so it asks before any tool that isn't marked read-only.
