How to Add an MCP Server to Codex

Do you actually need an MCP server?

For ordinary web development, review the minimal Codex setup for web development before adding another connection. A working project environment, concise AGENTS.md and reliable checks may be enough. You can start with zero plugins.

What is MCP?

You can think of MCP as a USB standard for AI tools. It gives Codex a standard way to connect to things such as development documentation, GitHub, browsers, databases and project-management systems.

You do not need to memorize the protocol before you begin. The practical point is simple: MCP is one way to give Codex access to an external tool. It is not a bundle that everyone must install.

Read the full plain-English explanation of MCP →

How MCP works in Codex

Codex acts as the agent: it understands the task and decides when a tool may help. The MCP server supplies a specific capability.

Adding an MCP server does not install another AI model inside Codex. It is closer to adding an external tool interface. What Codex can do still depends on the server's capabilities and the permissions you grant.

Source: official Codex MCP documentation.

Check these three things first

codex --version

Method 1: use codex mcp add

For most first-time users, adding one server through the CLI is the clearest approach. The basic format for a local stdio server is:

codex mcp add <server-name> -- <server-command>

If the server needs environment variables, the official form is:

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

• server-name: the name you assign to this MCP server for list, get and remove commands.
• --env: passes a configuration value to the server when it requires an environment variable.
• --: marks the point after which the MCP server's own launch command begins.
• stdio-server-command: the command that actually starts the server.

stdio is a common way for Codex and a local server to exchange messages through standard input and output. The text inside angle brackets is a placeholder to replace, not something to run literally.

Source: official CLI configuration format.

Official example: Context7

The Codex documentation uses this example:

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

Then list your configuration:

codex mcp list

Source: official Codex Context7 example.

Another real example: Playwright MCP

The Playwright project's README gives this Codex example:

codex mcp add playwright npx "@playwright/mcp@latest"

Then check it:

codex mcp list

This preserves the example exactly as published by Playwright. The earlier form with -- remains the general stdio syntax.

Source: Playwright MCP official README.

Which MCP servers have I configured?

codex mcp list

This lists the MCP servers in your current Codex configuration. To see all MCP subcommands supported by your installed Codex version, run:

codex mcp --help

This page does not invent sample output. What you see should come from your actual configuration and Codex version.

Inspect one MCP server

codex mcp get <server-name>

For example:

codex mcp get playwright

Use this to inspect a single configured server. Output fields may change between versions, so your result does not need to match an old screenshot line for line.

Source: Codex CLI MCP subcommand implementation.

What if the MCP server needs browser sign-in?

In plain English, OAuth lets you approve access on the service's own website instead of handing your password directly to Codex.

For a configured server that supports OAuth, use:

codex mcp login <server-name>

For example, after configuring a Linear server:

codex mcp login linear

Some remote servers open a browser so you can sign in and approve access. Check the website domain and requested permissions before accepting. Not every MCP server needs login, and typing an arbitrary server name cannot create a valid login flow.

Source: official OAuth login guidance.

An MCP server does not have to run on your computer

Local MCP: Codex starts a local command, such as a server launched through npx, python or docker.

Remote MCP: Codex connects to a network address. The current CLI supports --url, for example:

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

If a remote server supports OAuth, authenticate when required:

codex mcp login linear

Sources: official supported MCP features and the CLI URL argument implementation.

Method 2: edit config.toml directly

For manual configuration, the default user-level Codex file is:

~/.codex/config.toml

Codex also supports a project-level file:

.codex/config.toml

Project-level configuration is loaded only for trusted projects. The CLI and IDE extension share the Codex configuration layer. The ChatGPT website does not read this local file.

Back up the file before editing it. Change only the intended MCP entry and preserve other settings. This site never reads, uploads or rewrites your config.toml.

Source: Codex configuration basics.

Local stdio example

[mcp_servers.example]
command = "npx"
args = ["-y", "example-mcp-server"]

Codex uses mcp_servers, not the mcpServers key common in some JSON clients. TOML and JSON are different formats. Do not paste an entire JSON object into a TOML file.

Example with environment variables

[mcp_servers.example]
command = "example-server"
args = ["--port", "4000"]
env = { "API_KEY" = "YOUR_KEY" }

The two TOML blocks are separate examples. Do not define [mcp_servers.example] twice in one file.

Source: official stdio configuration fields.

Should MCP configuration be global or project-specific?

• User-level ~/.codex/config.toml works for configuration you use across projects.
• Project-level .codex/config.toml works when only one trusted project should use it.

Our editorial advice is simple: when you can limit the scope, do not make a connection global by default. This is not a mandatory Codex rule.

The two configuration levels have precedence; they are not separate installation folders. Running an add command from a project directory does not automatically guarantee project-scoped configuration. Follow the official configuration-layer guidance when scope matters.

Source: configuration scope and precedence.

How do I know the connection really works?

codex mcp list

A configuration entry does not prove every tool works

Seeing a server in list does not guarantee every tool is available. The server may fail to start, a runtime may be missing, OAuth may be incomplete, an environment variable may be absent, or a network or compatibility problem may remain.

After configuration, complete one real but low-risk task. This guide does not promise a “100% successful installation,” and we have not tested your environment.

How do I remove an MCP server?

If you can add it, you should also know how to remove it.

codex mcp remove <server-name>

For example:

codex mcp remove playwright

Then verify the result:

codex mcp list

Normally, remove deletes the MCP entry from Codex configuration. It does not mean a third-party account or its data has been deleted. Check that service's own policies separately.

If the same name still appears, inspect other configuration layers rather than deleting the entire .codex directory.

Source: Codex MCP remove implementation.

Do not install ten MCP servers at once

Codex best practices recommend adding tools that solve a real workflow problem, starting with one or two that clearly reduce repetitive work, and expanding only when needed.

That matches our editorial principle. Do not connect everything from a “20 must-have MCP servers” list:

• More configuration makes failures harder to diagnose.
• Capabilities may overlap, and many tools may go unused.
• Context can grow and affect token usage; the actual effect depends on the tool and client, so there is no honest universal percentage.
• Every external connection adds another set of permissions to review and maintain.

Install less. Keep what actually helps.

MCP setup failed? Check these six things

Notes for Windows users

PowerShell, cmd and other shells can parse commands differently. Check the environment you are actually using:

• Is npx, Node.js or another required program available on PATH?
• Can the official server command run in that terminal?
• Does a path with spaces or special characters cause a problem for that specific server?
• Are Codex and your terminal using the same runtime environment?

These are diagnostic directions, not a claim that MCP is generally broken on Windows. This guide does not provide unsupported one-size-fits-all repair commands or recommend disabling security checks.

What not to do

Install everything that looks popular

Identify the purpose first. Popularity is not a requirement.

Give an unfamiliar server an API key

Verify the source and requested permissions before sharing any credential. A server being easy to add does not make it trustworthy.

Keep reinstalling after configuration breaks

Use list and get to inspect the current state. If you need a clean reconfiguration, remove the intended entry and confirm the result before adding it again. Do not create duplicate entries around an unresolved error.

Treat MCP as “more tools must be better”

More tools do not automatically improve the work. The goal is a smoother workflow, not a longer tool list.

A 30-second setup flow

Frequently asked questions

Does Codex support MCP?

Yes. Codex CLI includes commands for configuring and managing MCP servers, including supported local stdio and remote servers.

Do Codex Desktop, the IDE extension and the CLI share MCP configuration?

This guide covers the local CLI and IDE path: they share the Codex configuration layer. The official MCP documentation also explains that the desktop application on the same Codex host can use that configuration. Do not assume a remote host reads the same file.

The ChatGPT website does not read your local Codex config.toml. Do not confuse web plugin settings with a file on your computer.

Where is the MCP configuration file?

The user-level file is ~/.codex/config.toml. The project-level file is .codex/config.toml, and it loads only for trusted projects.

How many MCP servers should I install?

There is no universal number. Start with one or two that have a clear purpose, and add another only when a real need appears.

Does removing an MCP server delete my account with that service?

Normally, codex mcp remove removes the server from Codex configuration. It is not an instruction to delete a third-party account. Review that service's rules for data, authorization and account removal.

Are MCP and plugins the same thing?

Not exactly. MCP describes a way to connect tools, while a plugin may package several kinds of capabilities. Start with What is MCP? rather than deciding from the label alone.

Related published content

• What is MCP?
• What is a CLI?
• What is an API?
• What is AI context?
• Is Playwright MCP worth installing?
• Playwright MCP vs CLI
• A minimal Codex setup for web development

This is a setup guide, not an automatic installer. The site does not read your configuration, collect credentials or start an MCP server.