MCP (Model Context Protocol) Integration Guide

What You'll Learn

Learn how to extend OpenAI Codex's capabilities using MCP servers for database connections, API integrations, browser automation, and more.

Prerequisites

• OpenAI Codex CLI installed
• Basic understanding of JSON configuration
• Appropriate MCP servers installed (via npm or local development)

Steps

Step 1: Add an MCP Server

Use the CLI to add MCP servers to your configuration:

# Add a server with stdio transport (most common)
codex mcp add github npx -y @modelcontextprotocol/server-github

# Add with specific scope (local, project, or user)
codex mcp add postgres node /path/to/postgres-mcp/index.js --scope project

Step 2: Configure Environment Variables

Set required environment variables for your MCP servers:

# Set environment variable for a specific server
codex mcp set-env github GITHUB_PERSONAL_ACCESS_TOKEN your-token-here

# Or configure in settings.json

Step 3: Configure in Settings File (Alternative)

Create or edit .codex/settings.json:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/postgres-mcp-server/build/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/db"
      }
    }
  }
}

Step 4: Set Permissions for MCP Tools

Configure permissions in your settings file:

{
  "permissions": {
    "allow": [
      "mcp__github__create_issue",
      "mcp__github__create_pr",
      "mcp__postgres__query",
      "mcp__postgres__schema"
    ]
  }
}

Step 5: Use MCP Tools in Your Session

Once configured, OpenAI Codex can use MCP tools automatically. The naming format is: mcp__server_name__tool_name

Example Usage

Database Query Example

codex "analyze the customer_orders table and show me the top 10 customers by revenue"
# OpenAI Codex will use mcp__postgres__query to execute the analysis

GitHub Integration Example

codex "create a GitHub issue summarizing the bugs found in today's testing"
# OpenAI Codex will use mcp__github__create_issue

Browser Automation Example

# First add Puppeteer MCP
codex mcp add puppeteer npx @puppeteer/mcp-server

# Then use it
codex "take a screenshot of our staging site at staging.example.com"
# OpenAI Codex will use mcp__puppeteer__navigate and mcp__puppeteer__screenshot

Common MCP Servers

| Server | Installation | Common Tools | |--------|-------------|--------------| | GitHub | npx -y @modelcontextprotocol/server-github | create_issue, create_pr, get_repo | | Puppeteer | npx @puppeteer/mcp-server | navigate, screenshot, click | | Postgres | Custom installation required | query, schema | | Linear | npx @linear/mcp-server | get_issue, create_issue, update_issue | | Slack | npx @slack/mcp-server | send_message, get_channels |

Tips & Variations

Scope Management

• Local: Configuration only for current directory
• Project: Shared with team via .codex/settings.json
• User: Available across all projects in ~/.codex/settings.json

OAuth Authentication

For servers requiring OAuth:

# Authenticate interactively
/mcp auth server-name

# Or use the CLI
codex mcp auth server-name

Resource References

Use MCP resources in your prompts:

@github:repo://owner/repo
@postgres:table://database/schema/table

Troubleshooting

• Issue: "Command not found" error Solution: Ensure the MCP server package is installed and accessible in PATH

• Issue: Permission denied for MCP tools Solution: Add the specific MCP tool to your allow list in permissions

• Issue: Connection failures Solution: Verify environment variables and network connectivity

• Issue: MCP server not recognized Solution: Check JSON syntax in settings file and restart OpenAI Codex

Security Best Practices

1. Vet MCP Servers: Only use MCP servers from trusted sources
2. Review Permissions: Grant only necessary MCP tool permissions
3. Secure Credentials: Use environment variables for sensitive data
4. Isolate Environments: Use different MCP configs for dev/staging/prod

Advanced Configuration

Multiple Environments

Create environment-specific configurations:

{
  "mcpServers": {
    "postgres-dev": {
      "type": "stdio",
      "command": "node",
      "args": ["postgres-mcp.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/dev_db"
      }
    },
    "postgres-prod": {
      "type": "stdio",
      "command": "node", 
      "args": ["postgres-mcp.js"],
      "env": {
        "DATABASE_URL": "${PROD_DATABASE_URL}"
      }
    }
  }
}

OpenAI Codex as MCP Server

Expose OpenAI Codex's tools to other MCP clients:

codex mcp serve

References

• Official MCP Documentation
• MCP Server Examples
• OpenAI Codex Settings Guide