Add a remote MCP server to Codex
Codex keeps MCP servers in config.toml, one [mcp_servers.<name>] table per server. A remote (Streamable HTTP) server needs only url; headers and timeouts are optional keys in the same table.
By Jake Marsh. Checked against Codex's own docs on 2026-10-31; each section links its source.
The Codex config
For a server named my-server at https://example.com/mcp that takes an Authorization header. Where it goes: ~/.codex/config.toml.
[mcp_servers.my_server]
url = "https://example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }Swap in your own server below and the Codex version updates first, with every other client after it.
Where Codex reads it
~/.codex/config.tomluser: every project.codex/config.toml in the projectproject: loaded in trusted projects only
Source: developers.openai.com/codex/mcp
Keys, headers and sign-in
Codex has three ways to send a key. http_headers is a map of header names to fixed values. env_http_headers maps header names to environment variable names, and Codex reads the values from the environment. bearer_token_env_var names one environment variable whose value Codex sends as a bearer token in Authorization.
For a server that supports OAuth, run codex mcp login <name>.
[mcp_servers.my_server]
url = "https://example.com/mcp"
bearer_token_env_var = "MY_SERVER_KEY"
startup_timeout_sec = 20Source: developers.openai.com/codex/mcp
Check that it connected
codex mcp list prints the configured servers. In the codex TUI, /mcp shows the active servers, and in the desktop app you type /mcp in the composer.
Source: developers.openai.com/codex/mcp
Codex gotchas
A project's .codex/config.toml loads only when the project is trusted. If a server you added there never shows up, put it in ~/.codex/config.toml or trust the project.
Source: developers.openai.com/codex/mcp
startup_timeout_sec defaults to 10 seconds and tool_timeout_sec to 60. Raise them for a server that is slow to start or has long-running tools.
Source: developers.openai.com/codex/mcp
Codex CLI, the IDE extension and the desktop app share one configuration, so a server you add for one appears in all three, and a broken entry affects all three.
Source: developers.openai.com/codex/mcp
enabled = false turns a server off without deleting its table. enabled_tools is an allow list and disabled_tools a deny list, applied after enabled_tools.
Source: developers.openai.com/codex/mcp
Still not connecting? Codex CLI MCP server not loading walks through the fixes in order.
Generate the config for your server
Runs in your browser. Nothing you type is sent anywhere. Still, don't paste real keys on shared screens.
Codex CLI
~/.codex/config.toml
[mcp_servers.my_server]
url = "https://example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }Source: developers.openai.com/codex/mcp
Claude Code
Run in a terminal (--scope user makes it available in every project)
claude mcp add --transport http --scope user my-server "https://example.com/mcp" --header "Authorization: Bearer YOUR_KEY"Source: code.claude.com/docs/en/mcp
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
"mcpServers": {
"my-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: cursor.com/docs/context/mcp
Windsurf / Devin Desktop
~/.config/devin/mcp_config.json (older Windsurf: ~/.codeium/windsurf/mcp_config.json)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Devin CLI / Devin Local
Run in a terminal (-s user saves it to ~/.config/devin/mcp_config.json for every project)
devin mcp add -s user -H "Authorization: Bearer YOUR_KEY" my-server "https://example.com/mcp"VS Code (Copilot agent mode)
.vscode/mcp.json in the workspace, or your user mcp.json (MCP: Open User Configuration)
{
"servers": {
"my-server": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: code.visualstudio.com/docs/agents/reference/mcp-configuration
Gemini CLI
~/.gemini/settings.json (or .gemini/settings.json in the project)
{
"mcpServers": {
"my-server": {
"httpUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Antigravity CLI (agy)
~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in the workspace)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: antigravity.google/docs/mcp
Cline
cline_mcp_settings.json (in the Cline panel, MCP Servers > Configure > Configure MCP Servers; Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json)
{
"mcpServers": {
"my-server": {
"type": "streamableHttp",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: docs.cline.bot/mcp/mcp-overview
OpenCode
opencode.json in the project root, or ~/.config/opencode/opencode.json for every project
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: opencode.ai/docs/mcp-servers/
Need a task list for those agents?
Taskhold is a remote MCP server that gives Codex and your other agents a task list you share, with their progress on a live board. Its setup link writes this config for the agent, so you don't have to. $12 a month or $120 a year, 7-day trial.