tessl/npm-openai--codex

OpenAI Codex CLI is a lightweight coding agent that runs locally, providing multimodal inputs, rich approvals workflow, and terminal-based AI-assisted development

Overview

Eval results

Files

MCP Management

Name: tessl/npm-openai--codex
Author: tessl

Model Context Protocol (MCP) server management allows you to add, remove, and configure external tools and capabilities for Codex CLI.

Usage

codex mcp [OPTIONS] [SUBCOMMAND]

Subcommands

Serve

Run Codex as an MCP server for integration with other tools.

codex mcp serve

List Servers

List all configured MCP servers.

codex mcp list [OPTIONS]

Options

--json    # Output server list as JSON

Get Server Details

Show details for a specific MCP server.

codex mcp get [OPTIONS] <NAME>

Arguments

<NAME>    # Name of the MCP server to display

Options

--json    # Output server configuration as JSON

Add Server

Add a new MCP server configuration.

codex mcp add [OPTIONS] <NAME> -- <COMMAND>...

Arguments

<NAME>        # Name for the MCP server configuration
<COMMAND>...  # Command to launch the MCP server

Options

--env <KEY=VALUE>    # Environment variables to set when launching (can be used multiple times)

Remove Server

Remove an MCP server configuration.

codex mcp remove <NAME>

Arguments

<NAME>    # Name of the MCP server configuration to remove

Examples

Serving as MCP Server

# Run Codex as an MCP server
codex mcp serve

Managing Server Configurations

# List all configured servers (table format)
codex mcp list

# List all configured servers (JSON format)
codex mcp list --json

# Add a simple server
codex mcp add docs-server -- python -m http.server 8000

# Add a server with environment variables
codex mcp add database-tool \
  --env DATABASE_URL=postgresql://localhost/mydb \
  --env API_KEY=secret123 \
  -- db-mcp-server --port 3000

# Add a complex server with multiple args
codex mcp add file-processor \
  --env WORKDIR=/tmp/processing \
  --env MAX_WORKERS=4 \
  -- python /path/to/processor.py --mode server --timeout 30

# Get server details (human-readable)
codex mcp get docs-server

# Get server details (JSON)
codex mcp get docs-server --json

# Remove a server
codex mcp remove docs-server

Working with Server Lists

The list command shows configured servers in table format:

Name          Command                   Args                    Env
docs-server   python                   -m http.server 8000     -
database-tool db-mcp-server           --port 3000             DATABASE_URL=postgresql://localhost/mydb, API_KEY=secret123

JSON Output Format

When using --json flag, output follows this structure:

[
  {
    "name": "docs-server",
    "command": "python",
    "args": ["-m", "http.server", "8000"],
    "env": null,
    "startup_timeout_ms": null
  },
  {
    "name": "database-tool",
    "command": "db-mcp-server",
    "args": ["--port", "3000"],
    "env": {
      "API_KEY": "secret123",
      "DATABASE_URL": "postgresql://localhost/mydb"
    },
    "startup_timeout_ms": null
  }
]

Configuration Storage

MCP server configurations are stored in ~/.codex/config.toml under the [mcp_servers] section:

[mcp_servers.docs-server]
command = "python"
args = ["-m", "http.server", "8000"]

[mcp_servers.database-tool]
command = "db-mcp-server"
args = ["--port", "3000"]
[mcp_servers.database-tool.env]
DATABASE_URL = "postgresql://localhost/mydb"
API_KEY = "secret123"

Server Name Validation

Server names must:

Not be empty
Contain only ASCII alphanumeric characters, hyphens (-), and underscores (_)
Valid examples: my-server, tool_v2, server123
Invalid examples: my server, tool@home, über-tool

Environment Variable Format

Environment variables must be specified in KEY=VALUE format:

# Valid formats
--env DATABASE_URL=postgresql://localhost/mydb
--env PORT=3000
--env ENABLE_DEBUG=true

# Multiple environment variables
codex mcp add myserver \
  --env VAR1=value1 \
  --env VAR2=value2 \
  -- command args

Error Handling

Common error scenarios:

Invalid server name: Contains invalid characters
Server not found: No server with specified name exists
Invalid environment format: Environment variables not in KEY=VALUE format
Command required: Add command requires at least one command argument

Integration with Codex

Once configured, MCP servers are automatically available in Codex sessions:

Servers start automatically when referenced
Tools and resources become available in conversations
Servers shut down when session ends

Best Practices

Use descriptive names: Choose clear, descriptive names for your servers
Set appropriate timeouts: Configure startup timeouts for slow-starting servers
Secure environment variables: Use environment variables for sensitive configuration
Test server configurations: Verify servers start correctly after adding
Regular cleanup: Remove unused server configurations to keep setup clean