Codex Pooler MCP server

Codex Pooler is a self-hosted gateway for running Codex-compatible agents, tools, and automation through stable Pool API keys. It works with one upstream Codex account for credential isolation, client normalization, metadata-only operations, and saved reset visibility; add more accounts when you want shared capacity and routing across eligible accounts.

Clients send familiar Codex backend or OpenAI-compatible requests; Codex Pooler selects an eligible account based on model support, quota evidence, limits, session continuity, routing policy, and health. The Pool key stays stable while upstream assignments, lifecycle state, reset policy, and capacity change behind it.

Operators get one place to manage Pools, accounts, API keys, saved resets, routing, request accounting, audit logs, and health without storing prompts, files, audio, images, bearer tokens, or raw Codex secrets. Instance owners keep the global administration surface, while instance admins work only with their assigned Pools.

Highlights

• 🧩 Use the tools you already know: connect Codex, OpenCode and other supported coding agents, plus apps built with OpenAI-compatible SDKs
• 🔑 One key for your apps: connect tools with a Pool API key that stays the same when you add or replace Codex accounts, without sharing account credentials
• ⚡ High cache reuse across protocols: over 95% cached input observed on HTTP/SSE and WebSockets, backed by cache-aware routing and connection reuse
• 🎯 Automatic account selection: send requests to accounts that can serve the chosen model, with available quota and account health taken into account
• 📏 Control how much each key can use: set request limits and daily or weekly AI usage allowances
• 🚀 Give agents more room to work: let them use several tools at once in Full mode, with Lite compatibility when needed
• 🖼️ Images and voice, too: generate and edit images or transcribe audio through supported apps, using the same Pool API key
• 🛡️ Keep conversation content private: track usage and troubleshoot requests without saving prompts, replies, uploaded files, images or audio
• 🔁 Keep conversations together: keep supported sessions linked to the right account when a client reconnects
• 🔭 Let users track their own usage: enable a personal Observatory dashboard for each key, showing activity, response times and estimated costs
• 🏦 Put saved resets to use: see available reset credits and use them to restore account quota, manually or automatically when enabled
• 🖥️ Manage everything in one place: add accounts, manage keys and invites, check usage and change settings from a browser
• 👥 Organize teams and projects: group accounts into Pools with their own access rules and model choices
• 🤝 Connect accounts by invitation: let account owners join a Pool through a guided browser flow, without sending you credential files
• 🚨 Know when attention is needed: receive alerts about low capacity, account problems and reset events in the dashboard, by email or through webhooks
• 🔎 Spot model downgrades: see when the provider reports a different model from the one sent, or changes the model name during a response
• 🧷 Fill in missing continuity: derive stable session identities from cache keys or conversation IDs when a harness does not send them directly
• 🧱 Choose who can connect: optionally allow requests only from approved networks
• 🐳 Run it on your own infrastructure: start with Docker Compose or deploy on Kubernetes as your needs grow

Harness Configuration

Start with a running Codex Pooler instance, a Pool API key, and an installed client. The examples include gpt-6-luna, gpt-6.1-sol and gpt-6-astra, with Sol selected by default. Keep the models available to your Pool. Replace <pool-api-key> with your key and run the command for your terminal before starting the client.

macOS / Linux / Windows WSL (bash or zsh)

export CODEX_POOLER_API_KEY="<pool-api-key>"

Windows PowerShell

$env:CODEX_POOLER_API_KEY = "<pool-api-key>"

These commands set the key for the current terminal. For desktop apps, follow the linked guide to save the key for the app.

The paths below are defaults. On macOS/Linux, ~ is your home folder. On Windows, paste paths starting with %USERPROFILE%, %APPDATA% or %LOCALAPPDATA% into File Explorer's address bar. If you installed a client inside WSL, use its Linux paths and commands inside WSL. Custom configuration folders or profiles take precedence over these defaults.

For a local instance:

Client	Base URL
Codex CLI / Desktop	http://localhost:4000/backend-api/codex
Other harnesses and SDKs	http://localhost:4000/v1

For a deployed instance, replace http://localhost:4000 with your instance's host, such as https://codex-pooler.example.com. Merge snippets into existing configurations. The examples use the large 828,400-token context for GPT-6. Codex CLI and Desktop read the available context size automatically from your Pool.

Each entry covers the basic connection. Its full setup & extras link covers installation, advanced options and troubleshooting. Operator MCP is optional and uses a separate token; see Operator MCP Service.

System	Configuration file
macOS / Linux	~/.codex/config.toml
Windows	%USERPROFILE%\.codex\config.toml

Open config.toml at the path for your system and add the following. If you set CODEX_HOME, use the file in that folder instead. Keep name = "OpenAI" to preserve Codex's native features. Catalog discovery is enabled by default; model_catalog_url points it at your Pool.

model = "gpt-6.1-sol"
model_provider = "codex-pooler-ws"

[model_providers.codex-pooler-ws]
name = "OpenAI"
base_url = "http://localhost:4000/backend-api/codex"
model_catalog_url = "http://localhost:4000/backend-api/codex/models"
env_key = "CODEX_POOLER_API_KEY"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true

Restart Codex and choose a model available to your Pool. If you use Codex Desktop, follow the full guide to make your API key available to the app.

Full setup & extras — desktop setup, account settings, existing conversations and the optional custom provider name with its limitations.

System	Configuration file
macOS / Linux	~/.config/opencode/opencode.jsonc
Windows	%USERPROFILE%\.config\opencode\opencode.jsonc

Open opencode.jsonc at the path for your system and add the configuration for your OpenCode version below.

OpenCode v2

{
  "$schema": "https://opencode.ai/config.json",
  "model": "codex-pooler/gpt-6.1-sol",
  "agents": {
    "title": {
      "model": "codex-pooler/gpt-6-luna"
    }
  },
  "providers": {
    "codex-pooler": {
      "package": "@opencode/ai/providers/openai/responses",
      "settings": {
        "baseURL": "http://localhost:4000/v1",
        "apiKey": "{env:CODEX_POOLER_API_KEY}",
        "transport": "http",
        "compaction": {
          "type": "summary"
        }
      },
      "models": {
        "gpt-6-luna": {
          "modelID": "gpt-6-luna",
          "capabilities": {
            "tools": true,
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": { "context": 828400, "input": 828400, "output": 32000 },
          "settings": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto"
          }
        },
        "gpt-6.1-sol": {
          "modelID": "gpt-6.1-sol",
          "capabilities": {
            "tools": true,
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": { "context": 828400, "input": 828400, "output": 32000 },
          "settings": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto"
          }
        },
        "gpt-6-astra": {
          "modelID": "gpt-6-astra",
          "capabilities": {
            "tools": true,
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": { "context": 828400, "input": 828400, "output": 32000 },
          "settings": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto"
          }
        }
      }
    }
  }
}

OpenCode v2 full setup & extras — installation and advanced options.

OpenCode v1

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-6.1-sol",
  "small_model": "openai/gpt-6-luna",
  "provider": {
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "Codex Pooler",
      "options": {
        "baseURL": "http://localhost:4000/v1",
        "apiKey": "{env:CODEX_POOLER_API_KEY}"
      },
      "models": {
        "gpt-6-luna": {
          "id": "gpt-6-luna",
          "name": "GPT-6 Luna",
          "family": "gpt",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto",
            "include": ["reasoning.encrypted_content"]
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": { "context": 828400, "input": 828400, "output": 64000 }
        },
        "gpt-6.1-sol": {
          "id": "gpt-6.1-sol",
          "name": "GPT-6.1 Sol",
          "family": "gpt",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto",
            "include": ["reasoning.encrypted_content"]
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": { "context": 828400, "input": 828400, "output": 64000 }
        },
        "gpt-6-astra": {
          "id": "gpt-6-astra",
          "name": "GPT-6 Astra",
          "family": "gpt",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto",
            "include": ["reasoning.encrypted_content"]
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": { "context": 828400, "input": 828400, "output": 64000 }
        }
      }
    }
  }
}

OpenCode v1 full setup & extras — installation and OMO setup.

System	Configuration file
macOS / Linux	~/.openclaw/openclaw.json
Windows	%USERPROFILE%\.openclaw\openclaw.json

Open openclaw.json at the path for your system and add this configuration:

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-6.1-sol",
        list: [{ id: "background", model: "openai/gpt-6-luna" }],
      },
      compaction: { reserveTokens: 128000 },
    },
  },
  models: {
    mode: "merge",
    providers: {
      openai: {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "${CODEX_POOLER_API_KEY}",
        api: "openai-responses",
        agentRuntime: { id: "openclaw" },
        timeoutSeconds: 300,
        models: [
          {
            id: "gpt-6-luna",
            name: "GPT-6 Luna via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 828400,
            contextTokens: 828400,
            maxTokens: 128000,
          },
          {
            id: "gpt-6.1-sol",
            name: "GPT-6.1 Sol via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 828400,
            contextTokens: 828400,
            maxTokens: 128000,
          },
          {
            id: "gpt-6-astra",
            name: "GPT-6 Astra via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 828400,
            contextTokens: 828400,
            maxTokens: 128000,
          },
        ],
      },
    },
  },
}

Restart OpenClaw and start a new conversation.

Full setup & extras — background tasks, more models and advanced options.

System	Folder for .env and config.yaml
macOS / Linux	~/.hermes/
Windows	%LOCALAPPDATA%\hermes\

Open .env in the folder for your system and add your Pool API key and Codex Pooler address. If you set HERMES_HOME, use that folder instead:

OPENAI_API_KEY=<pool-api-key>
OPENAI_BASE_URL=http://localhost:4000/v1
STT_OPENAI_BASE_URL=http://localhost:4000/v1

Add this to config.yaml in the same folder, then restart Hermes:

model:
  default: gpt-6.1-sol
  provider: openai-api
  base_url: http://localhost:4000/v1
  api_mode: codex_responses
  context_length: 828400
  supports_vision: true

agent:
  image_input_mode: native
  api_max_retries: 2
  auto_recovery_cycles: 1

image_gen:
  provider: openai
  openai:
    model: gpt-image-2.6-flare

stt:
  enabled: true
  provider: openai
  openai:
    model: gpt-4o-transcribe

compression:
  threshold: 0.95

auxiliary:
  compression:
    timeout: 900

This setup includes image generation and voice-to-text. To switch the chat model, set model.default to a model available to your Pool. Keep all three addresses pointed at your Codex Pooler instance. Your Pool must also offer the image and transcription models to use those features.

Full setup & extras — images, speech-to-text, priority processing and troubleshooting.

System	Configuration file
macOS / Linux	~/.pi/agent/models.json
Windows	%USERPROFILE%\.pi\agent\models.json

Open models.json at the path for your system and add this configuration:

{
  "providers": {
    "codex-pooler": {
      "name": "Codex Pooler",
      "baseUrl": "http://localhost:4000/v1",
      "api": "openai-responses",
      "apiKey": "$CODEX_POOLER_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "gpt-6-luna",
          "name": "GPT-6 Luna via Codex Pooler",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 828400,
          "maxTokens": 128000,
          "thinkingLevelMap": { "xhigh": "xhigh" }
        },
        {
          "id": "gpt-6.1-sol",
          "name": "GPT-6.1 Sol via Codex Pooler",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 828400,
          "maxTokens": 128000,
          "thinkingLevelMap": { "xhigh": "xhigh" }
        },
        {
          "id": "gpt-6-astra",
          "name": "GPT-6 Astra via Codex Pooler",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 828400,
          "maxTokens": 128000,
          "thinkingLevelMap": { "xhigh": "xhigh" }
        }
      ]
    }
  }
}

Add these defaults to settings.json in the same folder:

{
  "defaultProvider": "codex-pooler",
  "defaultModel": "gpt-6.1-sol",
  "enabledModels": [
    "codex-pooler/gpt-6-luna",
    "codex-pooler/gpt-6.1-sol",
    "codex-pooler/gpt-6-astra"
  ],
  "compaction": { "reserveTokens": 128000 }
}

Then start Pi:

pi

Full setup & extras — installation, default models and extra options.

System	Configuration file
macOS / Linux	~/.omp/agent/models.yml
Windows	%USERPROFILE%\.omp\agent\models.yml

Open models.yml at the path for your system and add this configuration:

providers:
  codex-pooler:
    baseUrl: http://localhost:4000/v1
    api: openai-responses
    apiKey: CODEX_POOLER_API_KEY
    authHeader: true
    remoteCompaction:
      enabled: true
      api: openai-codex-responses
      endpoint: http://localhost:4000/backend-api/codex/responses/compact
      v2StreamingEnabled: true
      v2Endpoint: http://localhost:4000/backend-api/codex/responses
    models:
      - id: gpt-6-luna
        name: GPT-6 Luna via Codex Pooler
        reasoning: true
        input: [text, image]
        compat:
          streamIdleTimeoutMs: 300000
        contextWindow: 828400
        maxTokens: 128000
      - id: gpt-6.1-sol
        name: GPT-6.1 Sol via Codex Pooler
        reasoning: true
        input: [text, image]
        compat:
          streamIdleTimeoutMs: 300000
        contextWindow: 828400
        maxTokens: 128000
      - id: gpt-6-astra
        name: GPT-6 Astra via Codex Pooler
        reasoning: true
        input: [text, image]
        compat:
          streamIdleTimeoutMs: 300000
        contextWindow: 828400
        maxTokens: 128000

Add these defaults to config.yml in the same folder:

startup:
  setupWizard: fa