Codex MCP Expert

Connect Codex to external tools, databases, and services using Model Context Protocol (MCP).

When to Use

• User wants to connect external services (GitHub, Jira, Sentry)
• User needs database access (PostgreSQL, MongoDB)
• User asks about MCP configuration or

  .mcp.json

• User has MCP connection or authentication issues

What is MCP?

Model Context Protocol (MCP) is an open standard that connects AI agents to:

• External APIs (GitHub, Jira, Notion, Slack)
• Databases (PostgreSQL, MongoDB, MySQL)
• File systems (local, Google Drive)
• Custom integrations

Quick Start

# Add an HTTP server
Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Add an SSE server
Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

# Add a stdio server (npm package)
Codex mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

# Manage servers interactively
/mcp

Transport Types

HTTP (Most Common)

For cloud services with REST-like endpoints.

Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp
Codex mcp add --transport http github https://api.github.com/mcp
Codex mcp add --transport http notion https://mcp.notion.com/mcp

SSE (Server-Sent Events)

For streaming services.

Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse
Codex mcp add --transport sse asana https://mcp.asana.com/sse

stdio (Local/NPM Packages)

For local tools or npm packages.

Codex mcp add --transport stdio postgres \
  --env POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost:5432/db" \
  -- npx -y @modelcontextprotocol/server-postgres

Codex mcp add --transport stdio filesystem \
  --env ALLOWED_DIRECTORIES="/path/to/dir" \
  -- npx -y @modelcontextprotocol/server-filesystem

Popular Integrations

Development Tools

Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp

Codex mcp add --transport http github https://api.github.com/mcp

Codex mcp add --transport http socket https://mcp.socket.dev/

Project Management

Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

Codex mcp add --transport http linear https://mcp.linear.app/mcp

Codex mcp add --transport http notion https://mcp.notion.com/mcp

Codex mcp add --transport sse asana https://mcp.asana.com/sse

Databases

# PostgreSQL
Codex mcp add --transport stdio postgres \
  --env POSTGRES_CONNECTION_STRING="postgresql://localhost:5432/mydb" \
  -- npx -y @modelcontextprotocol/server-postgres

# MongoDB
Codex mcp add --transport stdio mongodb \
  --env MONGODB_URI="mongodb://localhost:27017/mydb" \
  -- npx -y @modelcontextprotocol/server-mongodb

Communication

# Slack
Codex mcp add --transport stdio slack \
  --env SLACK_BOT_TOKEN=xoxb-your-token \
  --env SLACK_TEAM_ID=T1234567 \
  -- npx -y @modelcontextprotocol/server-slack

# Gmail
Codex mcp add --transport stdio gmail \
  -- npx -y @modelcontextprotocol/server-gmail

Configuration Files

.mcp.json Structure

{
  "mcpServers": {
    "server-name": {
      "transport": "http",
      "url": "https://mcp.service.com/mcp"
    },
    "database": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/db"
      }
    }
  }
}

Configuration Scopes

~/.Codex/.mcp.json

.Codex/.mcp.json

.Codex/.mcp.local.json

Add with Scope

Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp --user     # Global
Codex mcp add --transport http linear https://mcp.linear.app/mcp --project  # Team
Codex mcp add --transport http notion https://mcp.notion.com/mcp --local    # Personal override

Authentication

OAuth (Recommended)

# Install server
Codex mcp add --transport http github https://api.github.com/mcp

# Authenticate via /mcp command
/mcp
# Select: Authenticate with server
# Browser opens → authorize → done

API Keys (Environment Variables)

Codex mcp add --transport stdio server-name \
  --env API_KEY=your_api_key \
  -- npx -y package-name

Via settings.json

{
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxx",
    "SENTRY_AUTH_TOKEN": "sntrys_xxxxx"
  }
}

Using MCP Features

MCP Tools

Once connected, use naturally:

"Check Sentry for errors in the last 24 hours"
"Create a PR for this feature on GitHub"
"List my assigned Jira tickets"
"Query the users table for active accounts"

MCP Resources

Reference MCP-provided files:

Review @mcp://github/README.md and suggest improvements

MCP Prompts as Commands

MCP prompts become slash commands:

/mcp__github__create_issue "Bug in login" high
/mcp__jira__update_status PROJ-123 "In Progress"

Managing Servers

Interactive Management

/mcp
# Options:
# - View all servers
# - Add new server
# - Remove server
# - Authenticate
# - View tools/prompts/resources

Command Line

Codex mcp list                    # List servers
Codex mcp add ...                 # Add server
Codex mcp remove server-name      # Remove server

Troubleshooting

Server Not Connecting

1. Verify URL/command - check for typos
2. Check auth - run

   /mcp

   → Authenticate
3. Test network - can you reach the URL?
4. Debug mode - run

   Codex --debug

Authentication Failing

1. Re-authenticate:

   /mcp

   → Clear auth → Re-authenticate
2. Check API key validity
3. Verify OAuth tokens not expired
4. Check permissions/scopes

stdio Server Errors

# Test command manually
npx -y @modelcontextprotocol/server-postgres

# Check environment variables are set
echo $POSTGRES_CONNECTION_STRING

# Verify npm package exists
npm info @modelcontextprotocol/server-postgres

Tools Not Available

1. Confirm server is connected:

   /mcp

2. Check authentication completed
3. Restart Codex
4. Verify server provides expected tools

Security Best Practices

DO:

• Use OAuth when available
• Store secrets in settings.json, not .mcp.json
• Use project scope for team configs
• Review server permissions regularly

DON'T:

• Commit API keys to git
• Install untrusted servers
• Share OAuth tokens
• Use broad permissions unnecessarily

Example Workflows

Issue to PR

# Setup
Codex mcp add --transport http github https://api.github.com/mcp
Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

# Usage
"Read JIRA ticket ENG-123, implement the feature, and create a PR on GitHub"

Error Investigation

# Setup
Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Usage
"Check Sentry for errors in the last hour and fix them"

Database Query to Report

# Setup
Codex mcp add --transport stdio postgres \
  --env POSTGRES_CONNECTION_STRING="postgresql://localhost/analytics" \
  -- npx -y @modelcontextprotocol/server-postgres

# Usage
"Find users who signed up this month and summarize their activity"

Resources

• MCP Website: https://modelcontextprotocol.io/
• MCP Servers List: https://github.com/modelcontextprotocol/servers
• Codex MCP Docs: https://docs.anthropic.com/en/docs/Codex/mcp