Codex MCP config: shared TOML setup for CLI and VS Code

Codex can share one MCP setup across the ChatGPT desktop app, Codex CLI, and the Codex IDE extension when those clients run on the same host. You do not need to maintain one JSON file for the editor and another file for the terminal.

The current official MCP documentation also confirms an important change from early Codex releases: Codex supports both local STDIO servers and remote Streamable HTTP servers.

This guide shows the shortest reliable setup, then explains the TOML structure and failure modes.

Fastest setup: use the CLI

For a local STDIO server:

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

For a remote Streamable HTTP server:

codex mcp add company-tools --url https://mcp.example.com/mcp

Then confirm what Codex stored:

codex mcp list
codex mcp get context7

Add --json to list or get when a script needs machine-readable output.

The CLI writes the same configuration that the local Codex clients read. After adding a server, open or restart the relevant client session and verify that the expected tools appear.

Where the shared configuration lives

User-level configuration normally lives at:

~/.codex/config.toml

A trusted project can add project-specific settings at:

.codex/config.toml

The desktop app, CLI, and IDE extension share these layers for the same host. This is useful, but it also means one malformed user-level entry can affect every local client.

Use project scope when a server belongs to one repository. Use user scope for tools you intentionally want across projects. Remember that Codex ignores project-scoped .codex configuration until the project is trusted.

Configuration precedence matters

According to the current Codex configuration basics, values resolve from:

1. CLI flags and --config overrides
2. Trusted project config files
3. A selected profile
4. User config
5. System config
6. Built-in defaults

When an MCP server appears in the CLI but not in an editor session, first confirm that both clients are on the same machine and project. Then check whether a project file, profile, or launch override is changing the active configuration.

STDIO server structure

A local server is launched as a child process. A minimal entry looks like this:

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

For a Python server:

[mcp_servers.internal_docs]
command = "python"
args = ["-m", "internal_docs_mcp"]

Prefer commands available on the normal process PATH. If a server works in your interactive shell but not in the IDE, the difference is often the environment inherited by the editor process.

Environment variables for STDIO

You can declare which existing variables the server should receive:

[mcp_servers.internal_docs]
command = "python"
args = ["-m", "internal_docs_mcp"]
env_vars = ["INTERNAL_DOCS_TOKEN"]

You can also define explicit environment values:

[mcp_servers.internal_docs.env]
LOG_LEVEL = "info"

Do not commit secrets into a project config. Prefer an environment or managed credential source. A TOML file is configuration, not a secrets vault.

Streamable HTTP server structure

A remote server uses a URL instead of a local command:

[mcp_servers.company_tools]
url = "https://mcp.example.com/mcp"

Current Codex clients can use bearer-token authentication and OAuth for compatible Streamable HTTP servers.

For an OAuth-capable server:

codex mcp login company-tools

To remove the stored OAuth credentials without deleting the server:

codex mcp logout company-tools

To remove the server definition:

codex mcp remove company-tools

The current CLI command reference should be treated as authoritative when flags or authentication behavior change.

A safer team configuration pattern

Use three layers instead of copying personal files:

Repository layer

Check in only non-secret project requirements:

[mcp_servers.project_docs]
command = "node"
args = ["scripts/project-docs-mcp.mjs"]
env_vars = ["PROJECT_DOCS_TOKEN"]

Developer environment

Each developer supplies the named environment variable through their normal local secret workflow.

Managed or remote layer

For an organization service, prefer remote authentication and access controls over distributing one static token to every developer.

This pattern makes the repository reproducible without turning it into a credential store.

Troubleshooting in the right order

1. Ask Codex what it loaded

codex mcp list --json
codex mcp get company-tools --json

If the entry is absent, debug configuration location, trust, and precedence before debugging the server.

2. Test the transport independently

For STDIO, run the configured command from the same environment that launches Codex. Confirm the executable exists and the package can start.

For Streamable HTTP, confirm the URL and server availability. Do not assume an HTTP 401 is a network failure; it usually means the server was reached but authentication was rejected.

3. Isolate one server

Temporarily disable unrelated entries or create a minimal profile. One broken process, slow package install, or interactive login prompt can look like a general MCP failure.

4. Verify authentication separately

For OAuth:

codex mcp login company-tools

For a bearer token or environment-based STDIO credential, verify that the variable is present in the Codex process environment without printing its value.

5. Check client and project scope

The CLI and editor share configuration, but an already running session may not immediately reflect a changed process or project context. Reopen the project or start a fresh session after confirming the stored entry.

6. Run Codex diagnostics

codex doctor

The current CLI reference describes codex doctor as a diagnostic report covering installation, config, authentication, runtime, Git, terminal, app-server, and thread inventory issues.

Common mistakes to avoid

• Copying JSON syntax into TOML
• Using [mcp-servers] instead of [mcp_servers]
• Assuming Codex is still limited to STDIO
• Committing bearer tokens or API keys
• Using a relative executable path that depends on one shell startup file
• Debugging the extension before checking codex mcp list
• Forgetting that project config loads only for trusted projects
• Expecting one host’s configuration to appear automatically on another machine

How MCP fits the Codex workflow

MCP should add a capability that the repository or normal shell does not already provide. Good examples are an internal documentation source, a browser controller, a design system, or a deployment service with narrow, reviewable tools.

Keep the server list intentionally small. Every enabled server adds instructions, tools, startup behavior, and a new security boundary.

For the wider workflow, read:

• Codex CLI and VS Code integration
• Codex approval policies and sandbox modes
• Troubleshooting Codex in VS Code

Final checklist

1. Add the server with codex mcp add or a valid TOML entry.
2. Keep secrets outside checked-in config.
3. Run codex mcp list and inspect the exact entry.
4. Authenticate the transport separately.
5. Test one server before enabling a large tool set.
6. Confirm the same host and trusted project context in the CLI and IDE.

That sequence resolves most “MCP works here but not there” problems without deleting a valid configuration or weakening security.