MCP Servers

Model Context Protocol (MCP) servers allow you to extend Codex with custom tools, resources, and integrations. This guide shows you how to configure and use MCP servers with Codex.

What are MCP Servers?

MCP servers are processes that expose tools, resources, and prompts that Codex can use. They communicate over the Model Context Protocol, providing:

Custom tools - Extend Codex with domain-specific operations
Resources - Provide access to external data sources
Prompts - Add specialized prompt templates
OAuth integration - Secure authentication for external services

Configuration Location

MCP servers are configured in ~/.codex/config.toml under the [mcp_servers] section:

[mcp_servers.my-server]
command = "npx"
args = ["-y", "@my-org/my-mcp-server"]
enabled = true

Server Transport Types

MCP servers can connect via two transport mechanisms:

Stdio Transport (Local)

Run a local process that communicates over stdin/stdout:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]
enabled = true

[mcp_servers.filesystem.env]
DEBUG = "mcp:*"

Streamable HTTP Transport (Remote)

Connect to a remote MCP server over HTTP:

[mcp_servers.remote-server]
url = "https://mcp.example.com"
bearer_token_env_var = "MCP_TOKEN"
enabled = true

Configuration Options

command

string

Executable command to launch the MCP server (stdio only)

args

array

Arguments to pass to the command (stdio only)

url

string

URL for streamable HTTP MCP server (HTTP only)

enabled

boolean

default:"true"

Whether the server is enabled. Set to false to disable without removing config.

required

boolean

default:"false"

If true, Codex will fail to start if this server cannot connect

env

object

Environment variables to set when launching the server (stdio only)

env_vars

array

List of environment variable names to inherit from parent process

cwd

string

Working directory for the server process (stdio only)

bearer_token_env_var

string

Environment variable containing bearer token for authentication (HTTP only)

http_headers

object

Static HTTP headers to include in requests (HTTP only)

env_http_headers

object

HTTP headers with values from environment variables (HTTP only)

startup_timeout_sec

number

Maximum time to wait for server startup (seconds)

tool_timeout_sec

number

Maximum time to wait for tool execution (seconds)

enabled_tools

array

If set, only these tools are exposed (whitelist)

disabled_tools

array

List of tools to disable (blacklist)

scopes

array

OAuth scopes to request during authentication

oauth_resource

string

OAuth resource identifier for this server

Managing MCP Servers

Codex provides CLI commands for managing MCP server configurations:

List Configured Servers

# List all configured MCP servers
codex mcp list

# Output as JSON
codex mcp list --json

Add a Server

# Add a stdio server
codex mcp add my-server -- npx -y @my-org/my-mcp-server

# Add with environment variables
codex mcp add my-server --env DEBUG=mcp:* -- npx -y @my-org/my-server

# Add a remote HTTP server
codex mcp add remote-server --url https://mcp.example.com --bearer-token-env-var MCP_TOKEN

Get Server Details

# Show server configuration
codex mcp get my-server

# Output as JSON
codex mcp get my-server --json

Remove a Server

codex mcp remove my-server

OAuth Authentication

Some MCP servers require OAuth authentication. Codex provides built-in OAuth flow support:

# Authenticate with default scopes
codex mcp login my-server

# Authenticate with specific scopes
codex mcp login my-server --scopes read,write

Codex will:

Open your browser to the OAuth authorization page
Start a local callback server
Receive the authorization code
Exchange it for tokens
Store credentials securely

Logout from an MCP Server

codex mcp logout my-server

This removes stored OAuth credentials.

OAuth Credential Storage

Configure where OAuth tokens are stored:

mcp_oauth_credentials_store = "auto"

mcp_oauth_credentials_store

string

default:"auto"

Where to store MCP OAuth credentials.Options:

"auto" - Prefer OS keyring, fallback to file
"keyring" - Use OS keyring (most secure)
"file" - Store in ~/.codex/.credentials.json

OAuth Callback Configuration

mcp_oauth_callback_port = 3000
mcp_oauth_callback_url = "http://localhost:3000/callback"

mcp_oauth_callback_port

integer

Fixed port for OAuth callback server. When unset, uses ephemeral port.

mcp_oauth_callback_url

string

Redirect URI to use in OAuth flow. Local listener still binds to 127.0.0.1.

Tool Control

Whitelist Specific Tools

Only enable specific tools from a server:

[mcp_servers.my-server]
command = "npx"
args = ["-y", "@my-org/my-server"]
enabled_tools = ["read_file", "write_file"]

Blacklist Specific Tools

Disable specific tools:

[mcp_servers.my-server]
command = "npx"
args = ["-y", "@my-org/my-server"]
disabled_tools = ["delete_file", "execute_command"]

If both enabled_tools and disabled_tools are set, enabled_tools takes precedence (whitelist mode).

Example Configurations

Filesystem MCP Server

Provide Codex access to local filesystem:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
enabled = true
startup_timeout_sec = 30

GitHub MCP Server

Integrate with GitHub repositories:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
enabled = true
scopes = ["repo", "read:user"]

[mcp_servers.github.env]
GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}"

Then authenticate:

codex mcp login github --scopes repo,read:user

Slack MCP Server

Connect to Slack workspace:

[mcp_servers.slack]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-slack"]
enabled = true
scopes = ["channels:read", "channels:history", "chat:write"]

Database MCP Server

Query PostgreSQL databases:

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
enabled = true

[mcp_servers.postgres.env]
DATABASE_URL = "postgresql://user:pass@localhost/mydb"

Custom HTTP MCP Server

Connect to a remote custom server:

[mcp_servers.custom-api]
url = "https://mcp.mycompany.com/api"
bearer_token_env_var = "COMPANY_MCP_TOKEN"
enabled = true
tool_timeout_sec = 60

[mcp_servers.custom-api.http_headers]
"X-Organization-ID" = "org-123"

Set the token:

export COMPANY_MCP_TOKEN="your-token-here"

App-Level Tool Controls

Codex also provides app-level controls for MCP tools:

[apps.github]
enabled = true
default_tools_enabled = true
default_tools_approval_mode = "auto"
destructive_enabled = false
open_world_enabled = true

[apps.github.tools.delete_repo]
enabled = false
approval_mode = "prompt"

apps.<name>.enabled

boolean

default:"true"

Enable or disable the entire app/connector

apps.<name>.default_tools_enabled

boolean

Whether tools are enabled by default for this app

apps.<name>.default_tools_approval_mode

string

Default approval mode: "auto", "prompt", or "approve"

apps.<name>.destructive_enabled

boolean

Allow tools marked as destructive

apps.<name>.open_world_enabled

boolean

Allow tools with open world access hints

Troubleshooting

Server fails to start

Check that the command and args are correct
Verify the executable is in PATH or use absolute path
Check startup_timeout_sec if server is slow to start
Review server logs (set DEBUG=mcp:* in env)
Ensure required environment variables are set

OAuth login fails

Tools not appearing

Verify server is enabled (enabled = true)
Check if tools are in disabled_tools list
If using enabled_tools, ensure tools are listed
Verify server process is running successfully
Check that server implements MCP protocol correctly

Tool execution timeouts

Increase tool_timeout_sec for slow operations
Check network connectivity for HTTP servers
Review server implementation for performance issues
Verify server is not rate-limited or throttled

Environment variables not working

For stdio servers, use env section to set variables
For HTTP servers, use env_http_headers for header values
Check environment variable names for typos
Verify variables are exported in your shell
Use env_vars to inherit specific parent environment variables

Security Considerations

MCP servers run with the same permissions as Codex and can access files and networks. Only use trusted MCP servers.

Best Practices

Review server code - Inspect open-source servers before use
Use tool whitelisting - Enable only necessary tools with enabled_tools
Disable destructive operations - Set destructive_enabled = false for apps
Use OAuth when available - More secure than static API keys
Store credentials securely - Prefer keyring over file storage
Set timeouts - Prevent hung operations with tool_timeout_sec
Monitor server logs - Watch for unexpected behavior
Keep servers updated - Update MCP servers regularly

Complete Configuration Example

# OAuth credential storage
mcp_oauth_credentials_store = "auto"
mcp_oauth_callback_port = 3000

# MCP servers
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
enabled = true
scopes = ["repo", "read:user"]
required = false

[mcp_servers.github.env]
DEBUG = "mcp:*"

[mcp_servers.slack]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-slack"]
enabled = false  # Disabled by default
scopes = ["channels:read", "chat:write"]

[mcp_servers.custom-api]
url = "https://mcp.example.com/api"
bearer_token_env_var = "MCP_TOKEN"
enabled = true
tool_timeout_sec = 60

[mcp_servers.custom-api.http_headers]
"X-API-Version" = "2024-01"

# App-level controls
[apps.github]
enabled = true
default_tools_approval_mode = "auto"
destructive_enabled = false

[apps.github.tools.delete_repo]
enabled = false

[apps.slack]
enabled = true
default_tools_approval_mode = "prompt"

Get Started

Core Concepts

Configuration

Features

Advanced Usage

What are MCP Servers?

Configuration Location

Server Transport Types

Stdio Transport (Local)

Streamable HTTP Transport (Remote)

Configuration Options

Managing MCP Servers

List Configured Servers

Add a Server

Get Server Details

Remove a Server

OAuth Authentication

Logout from an MCP Server

OAuth Credential Storage

OAuth Callback Configuration

Tool Control

Whitelist Specific Tools

Blacklist Specific Tools

Example Configurations

Filesystem MCP Server

GitHub MCP Server

Slack MCP Server

Database MCP Server

Custom HTTP MCP Server

App-Level Tool Controls

Troubleshooting

Security Considerations

Best Practices

Complete Configuration Example

Next Steps

Configuration Reference

Building MCP Servers

Get Started

Core Concepts

Configuration

Features

Advanced Usage

​What are MCP Servers?

​Configuration Location

​Server Transport Types

​Stdio Transport (Local)

​Streamable HTTP Transport (Remote)

​Configuration Options

​Managing MCP Servers

​List Configured Servers

​Add a Server

​Get Server Details

​Remove a Server

​OAuth Authentication

​Login to an MCP Server

​Logout from an MCP Server

​OAuth Credential Storage

​OAuth Callback Configuration

​Tool Control

​Whitelist Specific Tools

​Blacklist Specific Tools

​Example Configurations

​Filesystem MCP Server

​GitHub MCP Server

​Slack MCP Server

​Database MCP Server

​Custom HTTP MCP Server

​App-Level Tool Controls

​Troubleshooting

​Security Considerations

​Best Practices

​Complete Configuration Example

​Next Steps

Configuration Reference

Building MCP Servers

What are MCP Servers?

Configuration Location

Server Transport Types

Stdio Transport (Local)

Streamable HTTP Transport (Remote)

Configuration Options

Managing MCP Servers

List Configured Servers

Add a Server

Get Server Details

Remove a Server

OAuth Authentication

Login to an MCP Server

Logout from an MCP Server

OAuth Credential Storage

OAuth Callback Configuration

Tool Control

Whitelist Specific Tools

Blacklist Specific Tools

Example Configurations

Filesystem MCP Server

GitHub MCP Server

Slack MCP Server

Database MCP Server

Custom HTTP MCP Server

App-Level Tool Controls

Troubleshooting

Security Considerations

Best Practices

Complete Configuration Example

Next Steps