How to configure MCP servers on the shared Codex host

Model Context Protocol (MCP) connects a model to tools and context. ChatGPT docs use it so ChatGPT or Codex can reach third-party documentation, or developer tools such as a browser or Figma.

Web and local clients do not share a setup screen. ChatGPT web uses remote MCP-backed tools supplied by plugins. The desktop app, Codex CLI, and IDE extension support MCP servers and share MCP configuration for the same Codex host. Add a server once on that host, then switch clients without repeating setup. Hosted plugin tools can have different capabilities from servers configured on a Codex host.

A STDIO server is a local process started by a command and can receive environment variables. A Streamable HTTP server is one you access at an address. Documented HTTP auth is bearer token authentication, OAuth (including Client ID Metadata Documents and Dynamic Client Registration), and ChatGPT session authentication for trusted first-party servers. Codex reads the MCP instructions field returned during initialization and uses it as server-wide guidance alongside the server's tools.

Shared host configuration

Codex stores MCP configuration in config.toml alongside other Codex settings. The desktop app, CLI, and IDE extension share this configuration (default ~/.codex/config.toml or a trusted project's .codex/config.toml). ChatGPT web does not read local Codex configuration files and does not expose the local Codex command menu.

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.

Add a server with the CLI

The STDIO add command on the page is:

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

Context7, described there as a free MCP server for developer documentation, is added with:

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

Run codex mcp list to see configured servers. Run codex mcp --help for the other MCP commands. For a server that supports OAuth, run codex mcp login <server-name>. In the codex terminal UI, /mcp shows active MCP servers.

If the authorization server requires a pre-registered client:

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

For a confidential client, pass the secret from an environment variable. The option requires a nonempty client ID and secret:

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

Codex saves that secret as mcp_servers.example.oauth.client_secret in config.toml. Keep the file private and out of version control. Codex displays the complete callback URL to register. Example output it may display is OAuth callback URL: http://127.0.0.1/callback; Codex may also append a callback ID or use mcp_oauth_callback_url. Register only the exact callback codex mcp add displays. The same page covers issuer-based callback selection and mcp_oauth_callback_port. If no credential source resolves, Codex can connect without authentication.

Add a server in the IDE extension

Open the gear menu, 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 extension.

The list shows enabled servers and servers that require OAuth. Select Authenticate when sign-in is required.

Edit config.toml

Use ~/.codex/config.toml, or .codex/config.toml in a trusted project, when you need more than name, command, and URL. Each server is a [mcp_servers.<server-name>] table. The page points to the configuration reference for every supported option. This section repeats only keys named on the MCP page.

STDIO requires command. Optional keys are args, env, env_vars, cwd, and experimental_environment. Set experimental_environment to remote to start the stdio server through a remote executor environment when one is available. String env_vars entries and source = "local" read Codex's local environment. source = "remote" reads the remote executor environment and requires remote MCP stdio. The page's example is:

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

A Context7 table from the page:

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

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

Streamable HTTP requires url. Optional keys are auth, bearer_token_env_var, http_headers, env_http_headers, and http_headers_helper. Codex tries auth after configured bearer tokens and authorization headers. Use oauth (the default) for stored MCP OAuth credentials. Use chatgpt for the current ChatGPT session on the trusted first-party ChatGPT origin, with stored OAuth as a fallback. bearer_token_env_var is the environment variable name for a bearer token sent in Authorization.

The page's Figma remote example:

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

Other optional keys are startup_timeout_sec (default 10), tool_timeout_sec (default 60), enabled, required, enabled_tools, disabled_tools (applied after enabled_tools), default_tools_approval_mode, tools.<tool>.approval_mode, and tools.<tool>.output_token_limit. Approval values are auto, prompt, writes, and approve. The writes mode prompts for tools that are not marked read-only. Set enabled to false to disable a server without deleting it. Set required to true to make startup fail if that enabled server cannot initialize.

mcp_optional_startup_grace_ms defaults to 1000 milliseconds. It is how long Codex waits for optional MCP servers while building the initial tool catalog. Set it to 0 to wait for each server's startup_timeout_sec instead. Required servers still use their startup timeouts.

http_headers_helper is a local command that prints a JSON object of header names and string values, such as {"X-Auth": "temporary-token"}. The page supports it for HTTP MCP connections from the local environment, not for stdio servers or remote execution. Explicit bearer tokens and OAuth credentials take precedence over a helper-provided Authorization header.

Plugins in 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 launch from the plugin, so user config does not set their transport command. User config can still control on/off state and tool policy under plugins.<plugin>.mcp_servers.<server>.

Local computer access with Work Cloud is separate. Continuing that conversation on another device does not install plugins or grant access to connected accounts. The enterprise mcp_servers TOML requirement in Agent Security applies to local executors. Cloud containers retain Work Cloud policies. Local MCP servers and transports may not be available in the cloud; check connectivity and authentication separately. Command hooks and hooks from local configuration or plugins are not supported with cloud orchestration, even when tools execute locally.

Examples the page names

The page says the list of MCP servers keeps growing and names OpenAI Docs MCP, Context7, Figma local and remote, Playwright, Chrome Developer Tools, Sentry, and GitHub. Do not invent install steps for the other names. Bring that server's command or URL into Settings, the CLI, the IDE, or config.toml.

If you maintain a server for Codex, use instructions for cross-tool workflows, constraints, and rate limits, and keep the first 512 characters self-contained.

Next step

Open Settings, then MCP servers, or run codex mcp list, and see what the shared Codex host already has. To try the documented path, add Context7 with the command above. In the desktop app, select Restart and type /mcp. In the terminal UI, /mcp shows active servers. For OAuth, run codex mcp login <server-name> and register only the callback codex mcp add displays. Read the Learn page again before changing callback ports or OAuth client registration; those rules are longer than this setup path.