How to connect ChatGPT and Codex to an MCP server

Model Context Protocol (MCP) lets ChatGPT and Codex use tools and information from other systems. An MCP server describes the available tools and handles their requests—for example, looking up a ticket or retrieving documentation. ChatGPT web uses remote MCP tools through plugins. Local Codex clients connect directly and share one configuration. ChatGPT web does not read local Codex configuration files or expose the local Codex command menu, so a server that is ready in the desktop app can still be missing in the browser.

The ChatGPT desktop app, Codex CLI, and IDE extension support MCP servers and share MCP configuration for the same Codex host. Set that configuration once, then switch among those clients without redoing setup. Install a plugin separately when the tool also has to run in hosted ChatGPT.

What a Codex host accepts

On a Codex host, the supported server features are:

STDIO servers: a local process started by a command. Environment variables are supported.
Streamable HTTP servers: a server you access at an address. Supported auth includes a bearer token, OAuth (Client ID Metadata Documents and Dynamic Client Registration), and ChatGPT session authentication for trusted first-party servers.
Server instructions: Codex reads the MCP instructions field returned during initialization and uses it as server-wide guidance alongside the server’s tools.

If a plugin is marked Desktop only, use a supported desktop app. A remote MCP server alone does not make a plugin web-compatible. Hosted plugin tools can have different capabilities from servers configured on a Codex host.

Codex stores MCP configuration in config.toml, by default ~/.codex/config.toml. You can scope servers to a project with .codex/config.toml, for trusted projects only.

Add a server in the desktop app

Open Settings, then select MCP servers.
Select Add server.
Enter a name, choose STDIO or Streamable HTTP, and provide the server’s command or URL.
Save the server, then select Restart.

The server list shows which servers are enabled and which require OAuth. Select Authenticate when an OAuth server requires sign-in. In the composer, type /mcp to view connected servers. This menu configures the shared Codex host. It does not install a web plugin.

Add a stdio server with the CLI

The documented stdio form is:

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

The docs’ Context7 example, a free MCP server for developer documentation, does not include those environment flags:

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

Leave the -- in place before the server command, as both snippets do.

Run codex mcp list to see configured servers. Run codex mcp --help for every MCP subcommand. In the Codex terminal UI, type /mcp to see active MCP servers.

For OAuth, run codex mcp login <server-name>. If the authorization server requires a pre-registered client, pass the client ID when you add the server:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

For a confidential client, also read the secret from an environment variable:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

That option requires a nonempty client ID and secret. Codex saves the secret as mcp_servers.example.oauth.client_secret in config.toml. Keep that file private and out of version control. Register the exact callback URL that codex mcp add displays. The docs show that line as:

OAuth callback URL: http://127.0.0.1/callback

Edit config.toml for the extra fields

For more fine-grained control, edit ~/.codex/config.toml or a trusted project’s .codex/config.toml. Each server is a [mcp_servers.<server-name>] table.

A stdio server requires command. Optional fields include args, env, env_vars, and cwd. The Context7 table in the docs is:

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

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

A Streamable HTTP server requires url. Optional auth is tried after configured bearer tokens and authorization headers. oauth is the default and uses stored MCP OAuth credentials. chatgpt uses the current ChatGPT session for the trusted first-party ChatGPT origin, with stored OAuth as a fallback. If no credential source resolves, Codex can connect without authentication; run codex mcp login <server-name> separately to start OAuth. The Figma example is:

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

Set enabled to false to disable a server without deleting it. Set required to true so startup fails if that enabled server cannot initialize. enabled_tools is an allow list, and disabled_tools is applied after it. startup_timeout_sec defaults to 10. tool_timeout_sec defaults to 60.

Add it from the IDE extension

The Codex IDE extension shares this configuration. Open the gear menu, select MCP servers, then Add server. Enter a name, choose STDIO or Streamable HTTP, provide the command or URL, save, and select Restart extension. Select Authenticate when an OAuth server requires sign-in.

Use a plugin on ChatGPT web

In a hosted ChatGPT Work chat, install a plugin to use its bundled connectors and remote MCP tools. After installation, Chat and Work can use those tools. Workspace administrators can control which plugins and tools are available. Open the Plugins tab to browse and manage them.

Installed plugins can bundle MCP servers in the plugin manifest. Those servers are launched from the plugin, so user config does not set their transport command. You can still control on/off state and tool policy under plugins.<plugin>.mcp_servers.<server>.

Creating a connection starts in a Work task with @Plugin Creator, then Install and Connect. If you already have a server for web, the MCP page points you to its connect-and-test plugin instructions. Neither path reads ~/.codex/config.toml.

Continuing a conversation that uses Local computer access with Work Cloud on another device does not install plugins or grant access to connected accounts. Local MCP servers and transports may not be available in the cloud; check connectivity and authentication separately. If ChatGPT does not use the tool, choose the plugin with @ and ask for a specific lookup. If tools are missing, confirm the Site owner published the latest version and that the plugin is installed and connected.

Confirm the surface, then call a tool

After a desktop save, select Restart and type /mcp in the composer to view connected servers. After a CLI add, run codex mcp list for configured servers, or type /mcp in the terminal UI for active ones. Finish Authenticate or codex mcp login <server-name> before you expect an OAuth server to answer.

If the local checks pass and ChatGPT web still has no tool, stop editing config.toml. Open the Plugins tab and call the plugin with @.

Add one server you already trust—the Context7 command above, or your own command or URL from Settings, then MCP servers—and confirm it with /mcp and codex mcp list before you ask an agent to use a tool. For ChatGPT web, follow the plugin path on the MCP docs instead of the local file.