Codex CLI + MCP: How to Connect OpenAI's Agent to External Tools

Codex CLI — OpenAI's terminal-based coding agent — supports the Model Context Protocol for connecting to external tools. If you want Codex to interact with your databases, project management tools, or cloud services, MCP is how you make that happen.

How MCP works with Codex CLI

MCP lets Codex CLI discover and use external tools without custom integration code. You configure one or more MCP servers, and Codex connects to them at startup. Each server advertises its available tools, and Codex uses them when relevant to your requests.

This means you can ask Codex to "check my latest GitHub issues" or "query the production database for user counts" and it will route those requests through the appropriate MCP server.

Setting up MCP servers in Codex CLI

Codex CLI reads MCP configuration from its settings file. The exact location depends on your OS, but the configuration format is:

{
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://mcp.github.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/path/to/project"]
    }
  }
}

Codex supports both URL-based servers (remote, using SSE or Streamable HTTP transport) and command-based servers (local, using stdio transport). URL servers are simpler to set up for cloud services. Command servers are better for local tools like file system access or database connections.

Best MCP servers to start with

If you're new to MCP with Codex CLI, these servers provide the most immediate value:

GitHub MCP server. Read issues, PRs, and repository data directly from your conversations. Essential if you're using Codex for open source work.

Filesystem MCP server. Gives Codex structured access to files beyond its default working directory. Useful for monorepos or projects with complex directory structures.

Database servers. PostgreSQL, MySQL, and SQLite MCP servers let Codex query your databases directly instead of you copy-pasting query results.

Sequential Thinking. A reasoning-enhancement server that helps Codex break down complex problems systematically.

You can browse and install MCP servers from the Agensi MCP directory, which includes security-scanned options with one-click setup instructions for Codex CLI.

Codex CLI MCP vs Claude Code MCP

Both agents support MCP, but there are differences in implementation. Claude Code has had MCP support since late 2024 and has the most mature integration. Codex CLI added MCP support more recently, and some servers that work with Claude Code may need minor configuration adjustments for Codex.

The protocol itself is the same — an MCP server built for one agent works with the other. The differences are in how each agent discovers servers, handles authentication, and manages tool execution permissions.

Troubleshooting MCP connections

The most common issues when setting up MCP with Codex CLI:

Server not appearing. Make sure you've restarted Codex after editing the config file. MCP servers are loaded at startup, not hot-reloaded.

Authentication failures. Double-check your tokens and API keys. For URL-based servers, ensure the headers are correctly formatted. For OAuth-based servers, you may need to complete an auth flow before the server works.

Timeout errors. Some MCP servers take a few seconds to initialize. If you're seeing connection timeouts, try increasing the timeout value in your configuration.

Tool not found. If Codex acknowledges the server but can't find specific tools, the server version may be outdated. Update the server package and try again.

Combining MCP with SKILL.md

MCP and SKILL.md serve different purposes and work well together. MCP connects your agent to external tools and data. SKILL.md teaches your agent how to do specific tasks. A SKILL.md skill might instruct your agent to use a database MCP server to check migration status before running new migrations, combining tool access with workflow knowledge.

Browse SKILL.md skills that leverage MCP servers on Agensi — many are designed specifically for Codex CLI workflows.