# Codex MCP Setup: Connect Tools and Live Context

> Connect OpenAI Codex to MCP servers through the CLI, desktop app, IDE, or config.toml — with practical scoping, OAuth, and tool-approval guidance.

Codex uses Model Context Protocol servers to reach live documentation, developer tools, and external systems. Local clients support STDIO and Streamable HTTP servers and share config.toml. Add only the servers a workflow needs, keep secrets in environment variables or OAuth, constrain exposed tools, and require approval for writes or sensitive side effects.

**Model Context Protocol gives Codex a standard way to use live tools and data outside the repository.** An MCP server can expose search, issue trackers, design files, browser controls, observability data, databases, or internal APIs as typed tools the agent can select during a task.

MCP is the integration layer, not the instruction layer. Use [`AGENTS.md`](/guides/configuration/codex-agents-md) to tell Codex how a repository works, and a [skill](/guides/skills/codex-skills-guide) to teach a repeatable procedure. Use MCP when that procedure needs information that changes or an action in another system.

## Choose the transport

Codex supports two MCP server types for local clients:

- **STDIO** — Codex starts a local process and communicates through standard input and output. This is common for developer tools installed with npm, Python, or a local binary.
- **Streamable HTTP** — Codex connects to a stable remote URL. This suits hosted and team services and can use bearer tokens or OAuth.

The ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP configuration on the same host. Hosted ChatGPT Work uses plugins for remote MCP-backed tools rather than reading the local machine's config file.

## Add a local server from the CLI

The fastest path for a local STDIO server is `codex mcp add`:

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

The name comes before `--`; everything after it is the command Codex launches. Pass environment values with `--env` when the server needs them, but avoid leaving secrets in shell history. Prefer forwarding a pre-existing environment variable or using the authentication mechanism supported by the server.

In the interactive terminal UI, `/mcp` shows active servers. The desktop app and IDE extension provide an **MCP servers** settings screen where you can add either transport, authenticate, enable or disable servers, and restart the client.

## Configure with `config.toml`

User-level configuration lives at `~/.codex/config.toml`. A trusted repository can carry project-specific configuration in `.codex/config.toml`; use that when the server exists only to support this codebase.

Local STDIO server:

```toml
[mcp_servers.docs]
command = "npx"
args = ["-y", "@example/docs-mcp"]
env_vars = ["DOCS_TOKEN"]
startup_timeout_sec = 20
tool_timeout_sec = 45
```

Remote Streamable HTTP server:

```toml
[mcp_servers.issues]
url = "https://mcp.example.com/api"
bearer_token_env_var = "ISSUES_MCP_TOKEN"
enabled_tools = ["search_issues", "get_issue", "add_comment"]
default_tools_approval_mode = "writes"
```

`env_vars` forwards named variables to a local process. `bearer_token_env_var` tells Codex which environment variable contains the remote token; the credential value stays outside the configuration file.

For OAuth-capable servers, add the server and run:

```bash
codex mcp login issues
```

## Treat the tool list as a permission surface

Connecting a server is not only a context decision. Every exposed tool expands what the agent can attempt. A read-only search tool and a “delete production deployment” tool should not share the same friction.

Codex configuration can narrow and govern that surface:

- `enabled_tools` creates an allowlist.
- `disabled_tools` removes tools after the allowlist is applied.
- `default_tools_approval_mode` sets the server-wide behavior.
- Per-tool approval settings can make a sensitive action stricter than the rest.

A safe default is to expose the small set of read operations the workflow needs, prompt for writes, and require explicit approval for destructive or externally visible actions. Do not rely only on a tool description to enforce security; the MCP server itself must validate authorization and arguments.

## Verify in layers

When a server does not appear or a call fails, check the stack from the bottom up:

1. **Process or URL** — can the local command start, or can the host reach the remote endpoint?
2. **Authentication** — is the expected environment variable present, or has OAuth login completed?
3. **Configuration scope** — is the project trusted, and did this client load the intended user or project config?
4. **Server initialization** — does `/mcp` or `codex mcp list` show it as enabled?
5. **Tool policy** — is the requested tool allowed and does its approval mode permit the call?
6. **Workflow routing** — does the prompt or skill make clear when Codex should use the tool?

Test one harmless read operation before enabling writes. That separates transport and auth problems from side-effect policy, and it gives you a known-good baseline.

> [!WARNING]
> Tool output is still external input. Documentation pages, issue bodies, and web content can contain instructions aimed at the model. Keep permissions scoped and ask Codex to treat retrieved content as data, not authority over the task.

## A good integration boundary

Start with one integration that removes a repeated manual loop: current library docs, a design source, issue context, or error traces. Pair it with a focused skill only if the organization needs a consistent multi-step method around those tools. Add more servers after you can explain the data, actions, credentials, and approval policy of the ones already installed.

Official reference: [Model Context Protocol in Codex](https://learn.chatgpt.com/docs/extend/mcp).

---

_Source: https://agentscamp.com/guides/mcp/codex-mcp-setup — Guide on AgentsCamp._