Using with OpenAI Codex

Connect Codex to your MCP Gateway and access all your servers through native Streamable HTTP transport.

Why Use MCP Gateway with Codex?

Codex natively supports Streamable HTTP MCP servers, so it connects directly to the gateway with no bridge required. You get:

  • Direct connection — No mcp-remote bridge needed, unlike Claude Desktop
  • Session management — Codex uses Mcp-Session-Id headers for reliable request correlation
  • All your servers in one config — Add servers in the console, they appear in Codex automatically
  • Usage tracking — See which tools Codex is calling in the console analytics

Prerequisites

  • OpenAI Codex installed — desktop app or CLI (installation guide)
  • An AppXen account with an active subscription
  • An API key (create one in Console under MCP Gateway → Keys)

Configuration

1

Set Your API Key

Export your AppXen API key as an environment variable. Add this to your shell profile (.bashrc, .zshrc, etc.) so it persists: 

export APPXEN_API_KEY="axgw_live_k1_your_key_here"
2

Add to Codex Config

Edit your Codex configuration file at ~/.codex/config.toml and add the gateway as an MCP server: 

# All your MCP servers through AppXen Gateway
[mcp_servers.appxen]
url = "https://api.appxen.ai/mcp"
bearer_token_env_var = "APPXEN_API_KEY"

Note: bearer_token_env_var tells Codex to read the token from the environment variable rather than embedding it in the config file.

3

Verify the Connection

Check that Codex sees the MCP server: 

codex mcp

Then start Codex and ask it to list available tools:

Try asking:

"What tools do you have available from my MCP servers?"

Connecting to a Single Server

By default, /mcp aggregates all your servers with prefixed tool names (e.g., github__get_me). To connect to a single server with original tool names, use the /mcp/{alias} endpoint: 

# Connect to just your GitHub server (unprefixed tool names)
[mcp_servers.github]
url = "https://api.appxen.ai/mcp/github"
bearer_token_env_var = "APPXEN_API_KEY"

# Connect to just your Neon server
[mcp_servers.neon]
url = "https://api.appxen.ai/mcp/neon"
bearer_token_env_var = "APPXEN_API_KEY"

Full Configuration Example

Here's a complete ~/.codex/config.toml with the gateway alongside other settings: 

# AppXen MCP Gateway — all servers, aggregated
[mcp_servers.appxen]
url = "https://api.appxen.ai/mcp"
bearer_token_env_var = "APPXEN_API_KEY"

# Or connect to individual servers for unprefixed tool names
# [mcp_servers.github]
# url = "https://api.appxen.ai/mcp/github"
# bearer_token_env_var = "APPXEN_API_KEY"

# Local MCP servers still work alongside the gateway
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]

How It Works

When Codex starts, it performs the MCP handshake with the gateway:

  1. Initialize — Codex sends initialize and receives gateway capabilities plus an Mcp-Session-Id header
  2. Notification — Codex sends notifications/initialized (the gateway responds with 202 Accepted)
  3. Tools — Codex calls tools/list with the session header to discover available tools
  4. Usage — Codex calls tools as needed, always including the session header

The gateway implements MCP Streamable HTTP transport (spec 2025-03-26), which Codex supports natively.

Troubleshooting

Server not showing in codex mcp?

  • Check that ~/.codex/config.toml has the correct TOML syntax
  • Verify the environment variable is set: echo $APPXEN_API_KEY

Connection or auth errors?

  • Verify your API key is valid and hasn't been revoked
  • Ensure the URL is exactly https://api.appxen.ai/mcp
  • Check that the bearer_token_env_var matches the exported variable name

Tools not appearing?

  • Verify you have at least one server enabled in the console
  • Try the aggregated endpoint (/mcp) — it includes tools from all servers

Added or removed servers but don't see changes?

Codex may cache the tools list for the duration of a session. Restart Codex to pick up server changes made in the console.

What's Next?