Codex Desktop MCP Guide: Connect Codex Desktop to External Data and Services
Learning Objectives
By the end of this tutorial, you will be able to:
- Understand how MCP (Model Context Protocol) works in Codex Desktop
- Add MCP servers to Codex Desktop through the configuration file
- Enable and manage MCP servers in the Desktop Settings panel
- Use MCP tools in Codex Desktop conversations
Time needed: 10–15 minutes
Difficulty: Beginner
Which version is covered? This tutorial covers Codex Desktop — the graphical desktop application of Codex. MCP servers are configured through the ~/.codex/config.toml file, which is shared with Codex CLI. If you use the command-line version, see the Codex MCP CLI Beginner's Guide.
Prerequisites
Before you begin, make sure you have:
| Requirement | Details |
|---|---|
| Codex Desktop installed | Open Codex Desktop and verify it launches correctly. Not installed? Follow the Codex Desktop App guide first. |
| Codex signed in | Sign in with your ChatGPT account (Plus, Pro, or higher) |
| Basic familiarity with MCP | If you are new to MCP, read the Codex MCP CLI Beginner's Guide for an introduction |
How MCP Works in Codex Desktop
Codex Desktop shares the same MCP configuration system as Codex CLI. All MCP servers are defined in the ~/.codex/config.toml file (macOS/Linux) or %USERPROFILE%\.codex\config.toml (Windows).
When you add an MCP server through the CLI (codex mcp add), it automatically appears in Codex Desktop's Settings → MCP Servers panel. You can also edit the config.toml file directly.
The key difference from the CLI version:
- CLI: MCP servers are always available in every session
- Desktop: MCP servers must be enabled in the Settings panel, and they may need OAuth authentication in some cases
Step 1: Open the MCP Servers Settings
Open Codex Desktop and navigate to:
- 1Click your profile icon or the Settings gear in the sidebar
- 2Select MCP Servers from the settings list
What you should see: A list of configured MCP servers (or an empty list if none are configured yet). Each server shows its name, status, and an enable/disable toggle.
Step 2: Find an MCP Server
MCP servers are available in several places. On Cataito, we curate 55+ MCP servers ready to connect. For this tutorial, we will use the **GitHub MCP server** — one of the most popular servers, which lets Codex read repositories, issues, and pull requests.
Browse the full collection at the MCP directory on Cataito.
Step 3: Add the MCP Server
There are two ways to add an MCP server to Codex Desktop:
Method A: Using the CLI (Recommended)
If you have Codex CLI installed, open a terminal and add the server. It will appear in Desktop automatically:
codex mcp add github -- npx -y @modelcontextprotocol/server-github
What you should see: The server is registered. Now open Codex Desktop and go to Settings → MCP Servers — the GitHub server should appear in the list (you may need to restart Codex Desktop).
Method B: Editing config.toml Directly
Open ~/.codex/config.toml (macOS/Linux) or %USERPROFILE%\.codex\config.toml (Windows) in a text editor and add the server entry:
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
Save the file, then restart Codex Desktop.
What you should see: The GitHub server appears in Settings → MCP Servers after restart.
Step 4: Enable the MCP Server
In the Settings → MCP Servers panel:
- 1Find the server you just added
- 2Make sure the toggle switch is enabled (green/on)
- 3If the server requires OAuth authentication, click the gear icon and follow the authentication flow
What you should see: The server status shows as "Connected" or "Ready".
Step 5: Use MCP Tools in a Desktop Chat
Now start a new conversation in Codex Desktop and use the MCP tools:
- 1Click New Chat in the sidebar
- 2Type a prompt that uses the MCP server, for example:
List the open issues in the facebook/react repository
What you should see: Codex Desktop calls the GitHub MCP server's tools automatically, fetches the data, and displays the results in the chat. You can also use the /mcp command in the chat to see which MCP tools are available.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| MCP server appears in Settings but not in chat | Desktop bug: project-scoped servers may not load in GUI | Configure the server globally (not project-scoped), then restart Codex Desktop |
| Server disappears after restart | Desktop may overwrite config.toml | Re-add the server with codex mcp add, or check ~/.codex/config.toml for corruption |
| OAuth authentication not showing | Desktop MCP settings do not display OAuth status per server | Authenticate via the CLI first: codex mcp login <server-name>, then restart Desktop |
| MCP tools not available in chat | Server may be disabled in Settings | Go to Settings → MCP Servers and verify the toggle is enabled |
npx: command not found | Node.js not installed | Install Node.js LTS from nodejs.org, then restart Codex Desktop |
FAQ
Do I need Codex CLI installed to use MCP in Desktop? No. You can edit config.toml directly, but using codex mcp add is the recommended way because it handles the configuration syntax correctly.
Can I use the same MCP servers in both Desktop and CLI? Yes — they share the same ~/.codex/config.toml file. Servers added via CLI appear in Desktop, and vice versa.
Does the Desktop version support all MCP servers? Most stdio-based MCP servers work. Streamable HTTP servers may have compatibility issues with the Desktop version.
Can I use MCP with a free ChatGPT plan? MCP support requires a paid plan (Plus, Pro, or higher).
Next Steps
- Browse the MCP directory on Cataito — 55+ curated MCP servers ready to connect
- Read the Codex MCP CLI Beginner's Guide for advanced CLI-specific MCP features
- Follow the Codex Desktop App guide for desktop installation and setup
