The setup
The shortest reliable path
MCP connects Codex to external tools and context. This guide covers Codex acting as the client—not building a server that exposes Codex itself as a tool.
The order below keeps configuration, credentials, discovery, and tool behavior from collapsing into one generic failure. Restart the desktop app or IDE extension when its settings flow asks you to; then prove the connection from the Codex surface where you intend to use it.
Choose
STDIO for a local process; Streamable HTTP for a server URL.
Add
Use Codex settings, the CLI, or config.toml.
Inspect
Confirm the effective entry with list and get.
Authenticate
Complete OAuth or provide an environment-backed credential.
Discover
Confirm exact tool names in /mcp.
Execute
Make one narrow read-only call and check its result.
The transport
Choose the boundary Codex will cross
Local Codex clients support STDIO servers and Streamable HTTP servers. The right choice follows the server you are connecting to; it is not a performance preference.
Local process
STDIO
Codex starts a command on the same machine. Validate the executable, arguments, working directory, and inherited environment.
command + args + env + cwdRemote endpoint
Streamable HTTP
Codex connects to a URL. Validate reachability separately from OAuth, bearer-token, and provider permission failures.
url + auth + headersThe ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP configuration on the same Codex host. ChatGPT web is different: it uses installed plugins and does not read your local config.toml. See the current Codex MCP reference.
The connection
Connect and authenticate without hiding the state
The settings UI is the shortest route for an interactive setup. The CLI and config.toml are better when the setup must be reviewable and repeatable.
# Local STDIO server codex mcp add context7 -- npx -y @upstash/context7-mcp # Remote Streamable HTTP server codex mcp add openaiDeveloperDocs \ --url https://developers.openai.com/mcp # Inspect and authenticate codex mcp list codex mcp get openaiDeveloperDocs codex mcp login <server-name>
For a remote server, prefer OAuth or an environment-backed bearer token over committing a secret to a repository. For a project-scoped .codex/config.toml, Codex requires a trusted project.
[mcp_servers.openaiDeveloperDocs] url = "https://developers.openai.com/mcp" enabled = true required = false startup_timeout_sec = 15 tool_timeout_sec = 45 enabled_tools = ["search_openai_docs", "fetch_openai_doc"] [mcp_servers.openaiDeveloperDocs.tools.search_openai_docs] output_token_limit = 8000
The proof
Verify every layer before trusting the tool
Configured, connected, discovered, and usable are different states. Test them in that order so each failure has one owner.
Effective configuration
`list` contains the server; `get` shows the expected transport, target, and enabled state.
Does not prove startup.Startup and authentication
The process initializes or the HTTP endpoint accepts the configured credential.
Reachability alone does not prove auth.Tool discovery
`/mcp` exposes the exact tools the workflow needs.
A visible tool has not executed yet.Tool execution
One narrow read-only call returns a known document, record, or result.
No error is weaker than a correct result.openaiDeveloperDocs enabled: true transport: streamable_http url: https://developers.openai.com/mcp
The tested CLI exposed list, get, add, remove, login, and logout. It did not expose a codex mcp check command. An open feature request proposes one, so the four proofs above are the current bounded diagnostic.
The diagnosis
Debug by the first failing layer
Do not change transport, credentials, timeouts, and filters together. Find the first proof that fails, change one variable, and rerun the smallest check that can falsify your hypothesis.
| Symptom | Likely layer | Next bounded check |
|---|---|---|
| Missing from list | Configuration | Confirm the config file and server name Codex loaded. |
| STDIO closes on initialize | Startup | Run the exact command; check path, cwd, args, and environment. |
| HTTP reachable, login required | Authentication | Run `codex mcp login <name>` and finish the provider flow. |
| Server visible, tools missing | Discovery | Compare `/mcp` with exact allow/deny-list names. |
| Tool starts, then times out | Execution | Call the smallest read-only tool and inspect `tool_timeout_sec`. |
| First turn slows after additions | Startup inventory | Disable optional servers; re-enable and test one at a time. |
| Correct call, excessive output | Output shape | Narrow the request and apply a per-tool output budget. |
An open issue in the official Codex repository reports that multiple slow, unauthenticated, or unhealthy servers can delay startup or first-turn discovery. It is evidence that the failure is reported—not that every large MCP setup is slow. Measure your own startup and keep only the servers the workflow needs.
Find the first layer that fails. Change one variable. Run the smallest proof again.
The operating policy
Keep the tool surface intentional
Optimize only after the connection is correct. The aim is not the fewest tools; it is the smallest sufficient surface where Codex can select the right capability and return the evidence the task needs.
enabledTurn off servers that are irrelevant to the current work.
requiredBlock startup only when the workflow cannot proceed without it.
enabled_toolsExpose a sufficient allow list; apply the deny list last.
timeoutsSet startup and tool limits from observed behavior.
default_tools_approval_modeChoose prompts from side effects, not convenience.
output_token_limitBound tools whose useful answer is smaller than worst-case output.
The product boundary
Where Supercode fits—and where it does not
Repair the MCP lifecycle
Supercode does not fix a process, OAuth flow, handshake, tool discovery, server permission, or incorrect tool implementation. Use the four-layer proof first.
Noisy output after a tool works
Supercode Token Optimization Basic is designed to reduce noisy or repetitive command output sent to the agent. Actual savings depend on the task and output.
If MCP output is one part of a larger context-cost problem, continue with our guide to Codex token use in large repositories. Output reduction never replaces the evidence or validation the task requires.
The preflight
Codex MCP checklist
A server is ready when each item below has evidence. Keep the checklist with the project setup when the connection is part of a repeatable team workflow.
- The transport matches the server: local command or remote URL.
- Codex loaded the intended config file and server entry.
- Secrets come from OAuth or environment-backed configuration.
- `codex mcp get <name>` shows the expected effective configuration.
- The app or extension was restarted when required.
- `/mcp` exposes the exact expected tools.
- One narrow read-only call returned known-good evidence.
- Optional servers are disabled when not needed.
- Tool filters use exact discovered names.
- Timeouts and output budgets reflect observed behavior.
- Side-effecting tools have an intentional approval policy.
- Output optimization is not described as MCP repair.
Evidence
Sources and test boundary
The configuration model comes from current OpenAI documentation. The CLI surface was checked locally against codex-cli 0.144.4 on September 6, 2026. Open issues document reported failure modes, not prevalence.
After the connection works
Keep the evidence. Reduce the exhaust.
Supercode can reduce noisy or repetitive output after tools work. It does not replace MCP diagnostics, credentials, or required task evidence.