Skip to main content

​
What are Apps & Connectors?

Apps & Connectors allow Codex to integrate with external services and ChatGPT apps, extending its capabilities beyond the terminal. This feature enables Codex to access data from connected services and use tools provided by ChatGPT apps.
Apps & Connectors bring ChatGPT’s ecosystem of integrations into your command-line workflow.

​
Using Connectors in Composer

The easiest way to use apps is through the composer with the $ prefix.

​
Inserting a Connector

Type $ in the composer to trigger the connector popover:
1

Open the composer

Start typing your prompt in Codex.
2

Type $ to trigger connector popover

> $
A popover appears listing accessible apps.
3

Select an app

Use arrow keys to navigate and press Enter to select an app.
4

Complete your prompt

The connector is inserted into your prompt:
> $MyApp Tell me about recent notifications

​
Which Apps Appear?

The popover lists:
  • Connected apps - Apps you’ve already authorized, labeled as “connected”
  • Available apps - Apps that can be installed
Connected apps appear first for easy access.

​
Managing Apps

Use the /apps slash command to manage your connected apps.

​
Listing Available Apps

> /apps
This shows:
  • All available ChatGPT apps
  • Which apps are currently connected
  • Which apps can be installed

​
Example Output

Available Apps:

1. GitHub (connected)
   - Access repository data and create issues

2. Linear (connected)
   - Query and update Linear issues

3. Slack
   - Send messages and search conversations
   - Status: Can be installed

4. Google Calendar
   - Read and create calendar events
   - Status: Can be installed

​
Configuring MCP Servers

Codex can connect to Model Context Protocol (MCP) servers configured in ~/.codex/config.toml.

​
What is MCP?

The Model Context Protocol is a standardized way for AI applications to connect to external data sources and tools. MCP servers expose resources and tools that Codex can use.

​
Configuration

Add MCP server configuration to your config.toml: 
# ~/.codex/config.toml

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
env = {}

[[mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

​
Available MCP Servers

Popular MCP servers include:

Filesystem

@modelcontextprotocol/server-filesystemProvides file system access to specified directories.

GitHub

@modelcontextprotocol/server-githubAccess GitHub repositories, issues, and pull requests.

Google Drive

@modelcontextprotocol/server-gdriveRead and write Google Drive documents.

Slack

@modelcontextprotocol/server-slackSend messages and search Slack conversations.
See the MCP documentation for a complete list of available servers.

​
Managing MCP Servers via CLI

Codex provides commands to manage MCP servers: 
# List configured MCP servers
codex mcp list

# Add a new MCP server
codex mcp add <name> <command> [args...]

# Get details about a specific MCP server
codex mcp get <name>

# Remove an MCP server
codex mcp remove <name>

​
Example: Adding GitHub MCP Server

codex mcp add github npx -y @modelcontextprotocol/server-github

​
Using Codex as an MCP Server

Codex can also function as an MCP server, allowing other MCP clients to use Codex as a tool.

​
Starting the MCP Server

codex mcp-server
This launches Codex in MCP server mode, exposing its capabilities to other agents.

​
Testing with MCP Inspector

Test Codex as an MCP server using the official inspector: 
npx @modelcontextprotocol/inspector codex mcp-server
This opens a web interface where you can:
  • See available tools
  • Test tool calls
  • View responses

​
Using Codex as a Tool

Other agents can use Codex to:
  • Execute code in a sandboxed environment
  • Analyze codebases
  • Perform refactoring
  • Generate code with context awareness

​
Common Use Cases

​
Querying External Services

> $GitHub List all open PRs in the openai/codex repository

> $Linear Show me all high-priority issues assigned to me

​
Integrating Data into Code

> $GoogleSheets Read the data from the "Sales Q1" sheet and generate a Python script to analyze it

​
Cross-Service Workflows

> $GitHub Get the latest issues labeled "bug" and $Linear create corresponding Linear issues for them

​
Configuration Reference

​
Full MCP Server Configuration

# ~/.codex/config.toml

[[mcp_servers]]
# Name used to identify the server
name = "my-service"

# Command to launch the MCP server
command = "node"

# Arguments passed to the command
args = ["/path/to/mcp-server.js"]

# Environment variables
env = {
  API_KEY = "${MY_API_KEY}",  # Can reference env vars
  BASE_URL = "https://api.example.com"
}

# Optional: Working directory
workdir = "/path/to/working/directory"

# Optional: Timeout in seconds
timeout = 30

​
Environment Variable Substitution

MCP server configurations support environment variable substitution: 
[[mcp_servers]]
name = "authenticated-service"
command = "npx"
args = ["-y", "@company/mcp-server"]
env = {
  API_KEY = "${COMPANY_API_KEY}",
  ENDPOINT = "${COMPANY_ENDPOINT}"
}
Codex will substitute ${VAR_NAME} with the value from your environment.

​
Security Considerations

Apps and MCP servers can access external services on your behalf. Only connect apps you trust and review permissions carefully.

​
Best Practices

Before connecting an app, review what data it can access and what actions it can perform.
Store API keys and tokens in environment variables, not directly in config.toml:
env = { API_KEY = "${MY_SECRET_KEY}" }
For filesystem servers, only grant access to specific directories:
args = ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents/safe-directory"]
Periodically review connected apps with /apps and disconnect ones you no longer use.

​
Troubleshooting

​
App Not Appearing in Popover

  1. Verify the app is installed and connected
  2. Run /apps to check connection status
  3. Restart Codex to refresh app connections

​
MCP Server Connection Failed

  1. Check that the server command is correct and accessible: 
    # Test the command directly
npx -y @modelcontextprotocol/server-github
  2. Verify environment variables are set: 
    echo $GITHUB_TOKEN
  3. Check Codex logs for detailed error messages: 
    RUST_LOG=debug codex

​
Permission Errors

  1. Ensure API keys have the necessary permissions
  2. Check that OAuth tokens haven’t expired
  3. Re-authenticate the app if needed

​
Examples

​
Example: GitHub Integration

# ~/.codex/config.toml
[[mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
Usage: 
> $GitHub List all open issues with label "bug" in openai/codex
> Create a summary of the most common issues

​
Example: Notion Integration

# ~/.codex/config.toml
[[mcp_servers]]
name = "notion"
command = "npx"
args = ["-y", "@notionhq/mcp-server-notion"]
env = { NOTION_API_KEY = "${NOTION_API_KEY}" }
Usage: 
> $Notion Read the contents of my "Project Ideas" database and create a prioritized TODO list

​
Example: Custom MCP Server

# ~/.codex/config.toml
[[mcp_servers]]
name = "company-api"
command = "python"
args = ["/opt/mcp-servers/company_api.py"]
env = {
  API_KEY = "${COMPANY_API_KEY}",
  ENVIRONMENT = "production"
}
workdir = "/opt/mcp-servers"
Usage: 
> $company-api Fetch customer data for account ID 12345 and generate a usage report

​
Next Steps

MCP Documentation

Learn more about the Model Context Protocol

Configuration Guide

Complete configuration reference

Skills System

Create skills that use MCP servers

Security

Understand Codex’s security model