Field guide / 16 min
Connect external systems through MCP
Transport, authentication, tool policy, and failure behavior belong in the connection contract.
Codex supports local STDIO and Streamable HTTP MCP servers. CLI, IDE extension, and desktop app share host configuration. A reliable connection names its transport, authentication source, timeouts, required status, enabled tools, and approval behavior before a workflow depends on it.
Verified terminal sequence
- $
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp - $
codex mcp list - $
codex mcp login <server> - ›
/mcp
Working principles
Connection is not trust
An installed server can expose powerful actions. Review identity, authentication, instructions, and tool annotations.
Constrain the tool surface
Use enabled and disabled tool lists plus per-tool approvals rather than exposing everything by default.
Fail loudly when required
Set required=true when continuing without a critical server would make results misleading.
Field procedure
- 01
Add the Docs MCP lab
Connect the official OpenAI developer documentation MCP endpoint using the documented CLI command.
- 02
List and inspect
Run codex mcp list and use /mcp in the TUI to confirm the active server.
- 03
Authenticate separately
For OAuth servers, run codex mcp login for that server; do not embed tokens in checked-in config.
- 04
Scope tools and approvals
Allow only needed tools and prompt for writes or sensitive actions.
- 05
Test failure behavior
Confirm how the workflow behaves when the server is unavailable, slow, or returns an error.
PASS / FAIL
Acceptance checklist
- Server identity and transport are known.
- Secrets come from an appropriate credential source.
- Only required tools are enabled.
- Critical startup failure cannot silently degrade the workflow.
WATCH / REJECT
Failure patterns
- Committing bearer tokens.
- Assuming every MCP tool is read-only.
- Depending on an optional server without checking its presence.