#MCP Integration

MCP (Model Context Protocol) is the standard for connecting Codex to external systems. In-repo file work uses built-in tools; issue trackers, design tools, internal docs, and browsers usually come through MCP.

For the protocol and writing servers, see the MCP tutorial. This chapter covers Codex configuration only.

#Architecture roles

Codex (Host / Client)
        │
        ├── Built-in: file I/O, Shell (in sandbox)
        │
        └── MCP Servers
              ├── GitHub (PRs, Issues)
              ├── Linear / Jira
              ├── Browser / Playwright
              └── Custom internal APIs

An MCP server may expose:

• Tools — callable actions
• Resources — readable data
• Prompts — reusable prompt templates

#Configuration

User-level: ~/.codex/config.toml
Project-level: .codex/config.toml (loads after trusting the project)

#Typical stdio server

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_PERSONAL_ACCESS_TOKEN}" }
enabled = true

#HTTP / Streamable HTTP

[mcp_servers.openai_docs]
url = "https://developers.openai.com/mcp"
transport = "streamable_http"
enabled = true

Field names vary by transport—see Configuration Reference.

#Security: allowlist

Enterprise setups can restrict MCP to an allowlist:

# Only servers on the allowlist (and matching identity) are enabled
allowed_mcp_servers = ["github", "linear"]

Servers not allowlisted or failing identity checks are disabled.

#Working with Skills

Anti-pattern: long “how to call GitHub API” prose in AGENTS.md
Better: Skill defines the workflow + MCP exposes create_issue, list_prs, etc.

Declare MCP dependencies in agents/openai.yaml for one-click install in the App.

#Common scenarios

#Migrating from Claude Code

Claude Code uses JSON (e.g. mcp-servers.json); Codex uses TOML. Same logic, different keys and structure. See Migrate to Codex.

#Debugging tips

1. Start the MCP server alone in a terminal; verify token and port
2. Test in Codex with a read-only task: List my open assigned issues
3. On failure, check enabled and required flags in config.toml

#Next steps

• Subagents: dedicated agents with focused MCP sets
• Agent Skills: reference MCP tool names in Skills