# How to add an MCP server to Codex: CLI, config.toml and IDE

> Add any MCP server to OpenAI Codex: codex mcp add for local and remote servers, the config.toml keys, project scope, OAuth sign-in and common fixes.

Page: https://hallwaytest.ai/learn/add-mcp-server-codex
Author: Marian Kushnir, Product Manager
Published: November 6, 2026. Last updated: November 9, 2026

**Short answer:** Run codex mcp add with a server name, then either --url and the address for a remote Streamable HTTP server, or -- followed by the start command for a local stdio server. Codex saves the entry in ~/.codex/config.toml, which the CLI, the IDE extension and the desktop app share. For an OAuth server, run codex mcp login with the name, then check the setup with codex mcp list or /mcp.

Codex can call tools from any Model Context Protocol (MCP) server you connect: documentation search, a browser, an issue tracker, or your own internal API. Adding one takes a single `codex mcp add` command or a few lines in `config.toml`, and the same setup works in the terminal, the IDE extension and the desktop app.

## What an MCP server does in Codex

An MCP server gives Codex extra tools it can call while it works. Codex supports two kinds: **stdio servers**, which run as a local process started by a command, and **Streamable HTTP servers**, which you reach at a URL. Codex also reads the `instructions` a server returns when it connects and treats them as guidance for using that server's tools.

## Add a remote (Streamable HTTP) server

Use `codex mcp add` with `--url` to register a server that already runs somewhere.

```bash
codex mcp add <server-name> --url https://mcp.example.com/mcp
```

The same entry in `~/.codex/config.toml` looks like this:

```toml
[mcp_servers.example]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_MCP_TOKEN"
```

`bearer_token_env_var` names an environment variable whose value Codex sends in the `Authorization` header. Leave it out for servers that use OAuth. For other headers, `http_headers` sets static values and `env_http_headers` reads values from environment variables.

## Add a local (stdio) server

Put `--` after the server name; everything after it is the command that starts the server. The Codex docs use Context7, a documentation server, as the example:

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

Pass environment variables with `--env`, once per variable:

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

In `config.toml`, a stdio server uses `command` (required), `args`, `env`, `env_vars` (names of variables to forward from your environment) and `cwd`:

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

## Where Codex keeps MCP configuration

Codex stores MCP servers in `~/.codex/config.toml` by default, or in `.codex/config.toml` inside a project to scope a server to that project.

| File | Applies to | Note |
| --- | --- | --- |
| `~/.codex/config.toml` | Every project on your machine | Default target of `codex mcp add` |
| `.codex/config.toml` | One project | Loaded only for trusted projects |

Each server is a `[mcp_servers.<server-name>]` table. Options that apply to both kinds of server:

| Key | What it does |
| --- | --- |
| `enabled` | Set `false` to switch a server off without deleting it |
| `startup_timeout_sec` | Seconds to wait for the server to start, default `10` |
| `tool_timeout_sec` | Seconds to wait for a tool call, default `60` |
| `enabled_tools`, `disabled_tools` | Allow list and deny list of tool names |
| `required` | Set `true` to make startup fail if the server is not ready |

## Sign in to an OAuth server

Run `codex mcp login` with the server's name; Codex opens your browser for the sign-in and stores the credentials.

```bash
codex mcp login <server-name>
```

If no credentials are configured, Codex may connect without authentication, so run the login yourself rather than waiting for a prompt. On a machine without a local browser, add `--no-browser`: Codex prints an authorization URL, you sign in elsewhere and paste the full redirect URL back into the terminal. To request specific scopes for one login, add `--scopes read,write`. If the provider requires a pre-registered client, pass `--oauth-client-id` (and `--oauth-client-secret` for a confidential client) to `codex mcp add`.

## Add a server in the IDE extension or the desktop app

Both have a form for the same fields. In the IDE extension, open the gear menu, select **MCP servers**, then **Add server**. Enter a name, choose **STDIO** or **Streamable HTTP**, and enter the command or URL. Save, then select **Restart extension**. In the ChatGPT desktop app the path is **Settings**, **MCP servers**, **Add server**, then **Restart**. For OAuth servers, select **Authenticate** in the server list.

## Check that it works

`codex mcp list` shows every configured server, and `/mcp` in the `codex` terminal UI shows the active ones.

```bash
codex mcp list
```

Then ask Codex in a session which tools it has from that server. `codex mcp --help` lists the other MCP subcommands.

## Troubleshooting

Most problems come down to the server name, the project trust setting or a timeout:

- **The server is missing from the list.** Check the `[mcp_servers.<server-name>]` header for typos. A server in a project's `.codex/config.toml` loads only if the project is trusted.
- **`codex mcp login` cannot find the server.** The name must match the table name exactly; `codex mcp list` shows the names Codex knows.
- **A local server fails to start in time.** Raise `startup_timeout_sec`, especially for `npx` servers that download a package on first run.
- **Long tool calls fail.** Raise `tool_timeout_sec` for that server.
- **Too many tools in the session.** Trim them with `enabled_tools` or `disabled_tools`.

## Example: add Hallway Test to Codex

Hallway Test is a remote MCP server with OAuth, so it needs two commands and no token. It lets your agent send a flow it just built to a real person from our in-house team, who runs it while thinking aloud; see [what the usability testing MCP does](https://hallwaytest.ai/usability-testing-mcp).

```bash
codex mcp add hallwaytest --url https://mcp.hallwaytest.ai/mcp
codex mcp login hallwaytest
```

Or add the entry by hand:

```toml
[mcp_servers.hallwaytest]
url = "https://mcp.hallwaytest.ai/mcp"
```

The login opens your browser: sign in with Google and approve the connection. `codex mcp list` then shows `hallwaytest`, and its tools, among them `create_usability_task`, are available in every Codex session. A new account can connect right away, but the first request to dispatch a test answers with a link to book the free pilot call. After the 30-minute call we activate the account, with no need to reconnect, and results come back within 24 hours. After public launch a test costs $29. The full walkthrough, including the IDE extension, is on [Connect Hallway Test to Codex](https://hallwaytest.ai/connect-codex).

## Sources

1. [Model Context Protocol, OpenAI Codex documentation](https://learn.chatgpt.com/docs/extend/mcp)
2. [Configuration reference, OpenAI Codex documentation](https://learn.chatgpt.com/docs/config-file/config-reference)

## FAQ

**Do the Codex CLI and the IDE extension use the same MCP servers?**
Yes. The Codex CLI, the IDE extension and the ChatGPT desktop app read the same config.toml, so a server you add in one is available in the others without redoing the setup.

**How do I add an MCP server to only one project in Codex?**
Put the [mcp_servers.<name>] table in .codex/config.toml inside the project instead of ~/.codex/config.toml. Codex reads project config only for trusted projects, so trust the folder first.

**How do I pass an API key to an MCP server in Codex?**
For a local stdio server, use --env KEY=value with codex mcp add, or the env table in config.toml. For a remote server, set bearer_token_env_var to the name of an environment variable that holds the token, or map headers to variables with env_http_headers. Keep secrets out of files you commit.

**How do I turn off an MCP server in Codex without deleting it?**
Set enabled = false in the server's table in config.toml. To hide only some of its tools, list the ones you want in enabled_tools or the ones you do not want in disabled_tools.

**What is the difference between a stdio and a Streamable HTTP server?**
A stdio server is a local process that Codex starts with a command, such as npx or python, and talks to over standard input and output. A Streamable HTTP server already runs somewhere and Codex connects to its URL, often with OAuth or a bearer token.

## Related

- [Home](https://hallwaytest.ai/index.md)
- [Pricing](https://hallwaytest.ai/pricing.md)
- [Book a free pilot](https://hallwaytest.ai/book.md)