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)
  • The AppXen Platform appliance deployed in your AWS account, with a domain so that it has a trusted certificate (see the note below)
  • An API key (create one in your appliance's console under API Keys, in the General section of the sidebar; it is shown once)

Self-signed certificate: until the appliance has a domain it serves a self-signed certificate. Your browser lets you click through the warning, but MCP clients such as Codex verify certificates and cannot connect to it. Set DomainName at launch, or point a domain's DNS A record at the ElasticIp output and run sudo appxenctl set-domain <name> on the instance, which obtains a Let's Encrypt certificate. See Connect an MCP client.

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://<your-appliance-host>/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://<your-appliance-host>/mcp/github"
bearer_token_env_var = "APPXEN_API_KEY"

# Connect to just your Neon server
[mcp_servers.neon]
url = "https://<your-appliance-host>/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://<your-appliance-host>/mcp"
bearer_token_env_var = "APPXEN_API_KEY"

# Or connect to individual servers for unprefixed tool names
# [mcp_servers.github]
# url = "https://<your-appliance-host>/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://<your-appliance-host>/mcp
  • If the appliance has no domain yet, its self-signed certificate is rejected: give it a domain (see the note under Prerequisites)
  • Check that the bearer_token_env_var matches the exported variable name

Tools not appearing?

  • Verify you have at least one server enabled in your appliance's 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?