How to Install an MCP Server in Codex

To install a local MCP server in Codex, use codex mcp add or add an [mcp_servers.<name>] table to user or trusted-project config.toml, then verify it with codex mcp list and /mcp. The steps below cover both native methods without requiring another product.

Before you edit anything

You need a local MCP server that communicates over standard input and output. In every example below:

• local-tools is a harmless example name. You may replace it with a short name for your server.
• node is the executable used to start the example server.
• /absolute/path/to/your-mcp-server.mjs is a placeholder, not a file supplied by this article. Replace it with the absolute path to your own stdio MCP server before running any add command.

First, confirm that the executable and server file you intend to use are available:

node --version
test -f /absolute/path/to/your-mcp-server.mjs

The second command succeeds silently only after you replace the placeholder with a real file path. If your server starts with Python, uvx, npx, or another executable, use that command and its arguments in the Codex configuration instead.

Add the server with the Codex CLI

After replacing the placeholder path, run:

codex mcp add local-tools -- node /absolute/path/to/your-mcp-server.mjs

The -- separates Codex options from the command that starts the stdio server.

Alternatively, edit config.toml

Codex shares MCP configuration among its local clients. By default, the file is ~/.codex/config.toml; a trusted project may instead use .codex/config.toml at the project root.

Add the following table to the appropriate Codex configuration file:

[mcp_servers.local-tools]
command = "node"
args = ["/absolute/path/to/your-mcp-server.mjs"]

For a stdio server, command is required and args is optional. Keep each argument as a separate string in the array. Do not include shell quoting inside those strings.

Choose scope and handle secrets safely

Use ~/.codex/config.toml for servers you want across projects. A trusted project can define shared overrides in <project>/.codex/config.toml. Keep machine-specific credentials out of project files: use env_vars for stdio servers, bearer_token_env_var for bearer tokens, or env_http_headers for secret HTTP headers. Authenticate OAuth-capable remote servers with codex mcp login <name> rather than copying stored credentials.

Verify the Codex connection

List the configured servers:

codex mcp list

Then open a Codex client. In the terminal interface, /mcp shows active servers. Ask Codex to list the tools exposed by local-tools to confirm that the server initialized and advertised its tools.

Troubleshoot a server that does not connect

If the server is listed but fails to start:

1. Run node /absolute/path/to/your-mcp-server.mjs directly after replacing the placeholder.
2. Confirm the executable resolves on your PATH and the server file uses an absolute path.
3. Compare the configured command and args with the working terminal command.
4. Check whether the server needs environment variables or a specific working directory and add those settings to its mcp_servers table.
5. If the server needs OAuth, run codex mcp login local-tools; if it uses an environment variable, confirm that variable exists in the client process.
6. Restart the Codex client after correcting the configuration, then check codex mcp list and /mcp again.

Official sources

These instructions were checked against the following vendor documentation.

• OpenAI: Model Context Protocol for Codex