How to Add and Configure MCP Servers in Codex CLI

Codex CLI uses MCP, the Model Context Protocol, to connect to external tools and data sources. An MCP server gives Codex access to tools, such as search, or data, such as documentation. You can configure Codex to launch a local server or contact a remote server over the network.

Codex supports two ways to connect to a server: STDIO, which passes data between Codex and a local server process through standard input and output, and Streamable HTTP, which connects to a server at a web address. Choose the method that matches how the server runs. Add either type with codex mcp add. Run codex mcp list to check its configuration. In the Codex terminal interface, use /mcp to inspect active connections. The Codex MCP documentation covers both connection methods.

Add a local server with STDIO

For a local server, give Codex the command that starts it. The -- marks the end of Codex’s options and the start of the server command.

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

If the server needs environment variables, pass each one with a separate --env option:

codex mcp add my-server --env API_KEY="$API_KEY" -- server-command

Replace my-server and server-command with the name and launch command for the server you intend to use. Check the server’s own instructions for required variables and arguments.

Codex stores server settings by default in ~/.codex/config.toml. You can also configure a server there directly, which helps when you need to set a working directory or other options:

[mcp_servers.local_docs]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
cwd = "/path/to/project"

Here, command names the program Codex runs, while args holds its command-line arguments. The cwd value sets the directory where Codex starts the server. Set env to define variables for the server process; use env_vars to specify which variables Codex can pass through from your local environment.

Add a remote server with Streamable HTTP

For a remote server, use --url with its MCP address. For example, OpenAI provides a server for searching and reading its developer documentation:

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

The OpenAI Docs MCP page describes what that server provides.

A remote server that requires a bearer token can read it from an environment variable. The server grants access when a request includes the bearer token, a secret value. GitHub’s hosted MCP server, for example, documents this Codex command:

codex mcp add github \
  --url https://api.githubcopilot.com/mcp/ \
  --bearer-token-env-var GITHUB_PAT_TOKEN

Set the named variable in your shell before using the server. Keep the token value out of the command history and configuration files, and grant it only the permissions the server needs. GitHub’s Codex installation instructions recommend avoiding hard-coded tokens and using narrowly scoped permissions.

You can also configure an HTTP server in TOML:

[mcp_servers.remote_docs]
url = "https://example.com/mcp"
bearer_token_env_var = "MCP_ACCESS_TOKEN"

url gives the server address; bearer_token_env_var names the environment variable holding its token. Codex also documents options for static HTTP headers and headers populated from environment variables. Keep credentials out of project files that you share or commit.

Choose where the configuration lives

Use ~/.codex/config.toml for your personal Codex configuration. A project can also have its own .codex/config.toml, but Codex applies project-scoped configuration only for trusted projects. The configuration is shared by Codex CLI, the Codex IDE extension, and the ChatGPT desktop app on the same host.

Each server uses a named TOML table, such as [mcp_servers.github]. That name identifies the entry in commands such as codex mcp get github, codex mcp login github, and codex mcp remove github. Keep project configuration free of secrets, especially when the project is under version control.

Configure access, tools, and timeouts

Codex lets you disable a server, filter which tools it exposes, set timeouts, and choose a default approval mode. For example:

[mcp_servers.example]
enabled = true
enabled_tools = ["search", "summarize"]
disabled_tools = ["summarize"]
startup_timeout_sec = 20
tool_timeout_sec = 45
default_tools_approval_mode = "prompt"

enabled = false turns off the server but leaves its configuration in place. enabled_tools lists the tools Codex is allowed to expose. After applying that list, Codex removes any tools named in disabled_tools. The documented approval modes are auto, prompt, writes, and approve; you can also set approval modes for individual tools. Choose settings based on what the server’s tools can do and what you want Codex to ask before doing.

Codex’s documented defaults are 10 seconds for server startup and 60 seconds for a tool call. When Codex builds its initial list of tools from optional servers, it gives them 1,000 milliseconds to start. If you set mcp_optional_startup_grace_ms = 0, Codex waits for each optional server’s startup timeout instead. The Codex configuration reference lists these settings and their supported values.

Sign in and verify the connection

For an HTTP server that supports OAuth, start authentication with:

codex mcp login server-name

OAuth is a sign-in method that lets the server grant access without storing your account password in Codex’s configuration. If your terminal does not have a local browser, run:

codex mcp login server-name --no-browser

Codex prints an authorization link. Open it in a browser, sign in, and paste the full redirect URL back into the terminal, even if the browser cannot display the callback page. Use codex mcp logout server-name to remove saved OAuth credentials. If a server requires a pre-registered OAuth client, follow its instructions; Codex’s documentation notes that a saved client secret is written to config.toml, so protect that file and keep it out of version control.

Check configured entries from the shell:

codex mcp list
codex mcp get server-name

The --json option returns machine-readable output from either command. These commands show the saved configuration. In an active Codex terminal session, use /mcp to see which servers are running and which tools they provide. If a configured server does not appear as active, check its launch command or URL and its authentication. Also confirm that the server provides the tools you expect.

Codex documents STDIO and Streamable HTTP as connection methods. Its current MCP documentation does not list Server-Sent Events (SSE) as a supported method. If a server’s instructions offer SSE, confirm that the server also supports a method Codex documents. To see the options in your installed CLI version, run codex mcp --help.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com