Skip to main content

​
Syntax

codex mcp <SUBCOMMAND> [OPTIONS]

​
Description

The mcp command manages external MCP servers that extend Codex’s capabilities. MCP servers can provide additional tools, data sources, and integrations.

​
Subcommands

  • list - List configured MCP servers
  • get - Show details for a specific server
  • add - Add a new MCP server
  • remove - Remove an MCP server
  • login - Authenticate with an MCP server (OAuth)
  • logout - Remove MCP server credentials

​
codex mcp list

List all configured MCP servers. 
codex mcp list [--json]
​
--json
boolean
Output server list as JSON.

​
Examples

# List servers in table format
codex mcp list

# Output:
# Name          Command              Args    Env    Cwd     Status    Auth
# github-mcp    node                 main.js -       -       enabled   authenticated
# local-tools   /usr/local/bin/mcp   -       -       -       enabled   unsupported

# Get JSON output
codex mcp list --json

​
codex mcp get

Show detailed configuration for a specific MCP server. 
codex mcp get <NAME> [--json]
​
NAME
string
required
Name of the MCP server to display.
​
--json
boolean
Output server details as JSON.

​
Examples

# Show server details
codex mcp get github-mcp

# Output:
# github-mcp
#   enabled: true
#   transport: stdio
#   command: node
#   args: /path/to/github-mcp/main.js
#   env: GITHUB_TOKEN=ghp_***
#   remove: codex mcp remove github-mcp

# Get JSON output
codex mcp get github-mcp --json

​
codex mcp add

Add a new MCP server configuration. 
# Add stdio server
codex mcp add <NAME> -- <COMMAND> [ARGS...]

# Add streamable HTTP server
codex mcp add <NAME> --url <URL>
​
NAME
string
required
Name for the MCP server. Must contain only letters, numbers, hyphens, and underscores.

​
For stdio servers:

​
COMMAND
string
required
Command to launch the MCP server.
​
--env
string
Environment variables in KEY=VALUE format (repeatable).

​
For HTTP servers:

​
--url
string
required
URL for a streamable HTTP MCP server.
​
--bearer-token-env-var
string
Environment variable name containing a bearer token for authentication.

​
Examples

# Add stdio server with Node.js
codex mcp add github-mcp -- node /path/to/server.js

# Add with environment variables
codex mcp add slack-mcp \
  --env SLACK_TOKEN=xoxb-... \
  --env SLACK_WORKSPACE=myteam \
  -- node slack-server.js

# Add Python-based MCP server
codex mcp add python-tools -- python3 -m mcp_server

# Add streamable HTTP server
codex mcp add remote-mcp --url https://mcp.example.com

# Add HTTP server with bearer token
codex mcp add api-mcp \
  --url https://api.example.com/mcp \
  --bearer-token-env-var API_TOKEN

​
codex mcp remove

Remove an MCP server configuration. 
codex mcp remove <NAME>
​
NAME
string
required
Name of the MCP server to remove.

​
Examples

# Remove a server
codex mcp remove github-mcp

# Output:
# Removed global MCP server 'github-mcp'.

# Attempt to remove non-existent server
codex mcp remove unknown

# Output:
# No MCP server named 'unknown' found.

​
codex mcp login

Authenticate with an MCP server using OAuth. 
codex mcp login <NAME> [--scopes <SCOPE,SCOPE,...>]
​
NAME
string
required
Name of the MCP server to authenticate with.
​
--scopes
string
Comma-separated list of OAuth scopes to request.
OAuth login is only supported for streamable HTTP servers.

​
Examples

# Login to MCP server
codex mcp login github-mcp

# Login with specific scopes
codex mcp login github-mcp --scopes repo,user

# Output:
# Starting OAuth flow...
# Visit: https://github.com/login/oauth/authorize?client_id=...
# Successfully logged in to MCP server 'github-mcp'.

​
codex mcp logout

Remove OAuth credentials for an MCP server. 
codex mcp logout <NAME>
​
NAME
string
required
Name of the MCP server to deauthenticate.

​
Examples

# Logout from MCP server
codex mcp logout github-mcp

# Output:
# Removed OAuth credentials for 'github-mcp'.

# If no credentials stored
codex mcp logout github-mcp

# Output:
# No OAuth credentials stored for 'github-mcp'.

​
Configuration

MCP servers are stored in ~/.codex/config.toml: 
[mcp_servers.github-mcp]
enabled = true
transport = { type = "stdio", command = "node", args = ["/path/to/server.js"] }
env = { GITHUB_TOKEN = "ghp_***" }

[mcp_servers.remote-api]
enabled = true
transport = { type = "streamable_http", url = "https://api.example.com" }
bearer_token_env_var = "API_TOKEN"

​
MCP Server Types

​
stdio Servers

Local servers that communicate via stdin/stdout: 
codex mcp add my-tool -- python3 -m my_mcp_server
Use cases:
  • Local tools and utilities
  • File system access
  • Development and testing

​
Streamable HTTP Servers

Remote servers over HTTP: 
codex mcp add remote-service --url https://mcp.example.com
Use cases:
  • Cloud services
  • Shared team tools
  • OAuth-authenticated APIs

​
Troubleshooting

​
Server Won’t Start

Check server configuration: 
codex mcp get <NAME>
Verify command is executable: 
which <COMMAND>

​
Environment Variables Not Set

Ensure environment variables are available: 
codex mcp add my-server \
  --env TOKEN=$MY_TOKEN \
  -- command
Or set in config.toml: 
[mcp_servers.my-server]
transport = { type = "stdio", command = "command" }
env = { TOKEN = "value" }

​
OAuth Issues

For OAuth authentication problems:
  1. Verify server supports OAuth: 
    codex mcp get <NAME> --json | jq .transport.type
  2. Check credentials: 
    codex mcp list --json | jq '.[] | select(.name=="<NAME>") | .auth_status'
  3. Re-authenticate: 
    codex mcp logout <NAME>
codex mcp login <NAME>