data-ai MCP Server
The full featured self-hosted Codex gateway, for teams, agents and you
Discovered via github-topic:mcp and last synced 2mo ago.
Install instructions not detected yet
Check the source repository for the latest setup steps.
Default config file
`$HOME/.codex/config.toml`
`$HOME/.codex/config.toml`
`$HOME\.codex\config.toml`, normally `%USERPROFILE%\.codex\config.toml`
Value
On when the Pool model supports image input
In Trae CN, the same flow appears as Settings -> Models and custom configuration in the localized UI. Use the same URL, model id, Pool API key, and context values. If Full URL is enabled instead, use the full `https://codex-pooler.example.com/v1/chat/completions` endpoint. Check the Pool API key and model with a direct chat-completions request before saving the client model: ```bash curl -sS -X POST \ -H "Authorization: Bearer $CODEX_POOLER_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "gpt-5.6-terra", "messages": [ { "role": "user", "content": "Reply with exactly: trae ok" } ], "stream": false, "max_completion_tokens": 16 }' \ https://codex-pooler.example.com/v1/chat/completions ``` For local setup, use `http://localhost:4000/v1` with Full URL off. Treat the setup as working only when Trae's model add/check step succeeds and a real chat can answer `trae ok` through the configured model. After saving the custom model, open the agent model picker and turn Auto Mode off. The model list is hidden behind Auto Mode by default; select the Codex Pooler model under Custom Models. Do not point Trae at `/backend-api/codex`, `/v1/responses`, `/mcp`, or a Codex Pooler admin URL. Codex Pooler model use does not require MCP. </details> <details> <summary><img src=".github/assets/aider-favicon.png" alt="Aider logo" width="16" height="16"> Aider <code>~/.aider.conf.yml</code></summary> Aider uses the OpenAI-compatible route with the `openai/` model prefix. Put the stable route settings in `.aider.conf.yml`; Aider loads this file from your home directory, then the git repo root, then the current directory, with later files taking priority. ```yaml # ~/.aider.conf.yml or <repo>/.aider.conf.yml model: openai/gpt-5.6-terra openai-api-base: http://localhost:4000/v1 ``` Aider's `.aider.conf.yml` route settings do not carry context or output limits. If your installed Aider version does not recognize `gpt-5.6-terra`, use Aider's separate model metadata JSON file for model behavior and limits instead of adding unsupported context fields to the main config. ```jsonc // .aider.model.metadata.json { "openai/gpt-5.6-luna": { "max_tokens": 353400, "max_input_tokens": 225400, "max_output_tokens": 128000, "litellm_provider": "openai", "mode": "chat", "supports_function_calling": true, "supports_vision": true, "supports_reasoning": true }, "openai/gpt-5.6-terra": { "max_tokens": 353400, "max_input_tokens": 225400, "max_output_tokens": 128000, "litellm_provider": "openai", "mode": "chat", "supports_function_calling": true, "supports_vision": true, "supports_reasoning": true }, "openai/gpt-5.6-sol": { "max_tokens": 353400, "max_input_tokens": 225400, "max_output_tokens": 128000, "litellm_provider": "openai", "mode": "chat", "supports_function_calling": true, "supports_vision": true, "supports_reasoning": true } } ``` Keep the Pool API key out of the YAML file. Export it in the shell, or put it in a gitignored `.env` file that Aider can load: ```bash export OPENAI_API_KEY="$CODEX_POOLER_API_KEY" ``` Check Aider from a repository with a real file edit. The command should only need the one-off prompt when the config file is present: ```bash aider \ --message 'Create a file named aider-ok.txt containing exactly: aider ok. After the file exists, reply with exactly: aider ok' \ --yes-always \ --no-auto-commits \ --no-git \ --no-browser \ --no-gui \ --no-analytics ``` The check is only useful if the file exists with the expected content; a text reply alone does not prove Aider can edit through the configured model path. For deployed instances, change `openai-api-base` to `https://codex-pooler.example.com/v1`. </details> <details> <summary><img src=".github/assets/continue-favicon.png" alt="Continue logo" width="16" height="16"> Continue <code>~/.continue/config.yaml</code></summary> Continue can use Codex Pooler as an OpenAI-compatible provider by setting `provider: openai`, `apiBase` to `/v1`, and the Pool API key as a Continue secret. For `gpt-5*` models, Continue uses the Responses API by default. For local Continue configs, put the assistant in `~/.continue/config.yaml` on macOS/Linux or `%USERPROFILE%\.continue\config.yaml` on Windows. In the IDE extension, open the Continue chat sidebar, use the config selector above the chat input, then click the gear icon beside **Local Config**. Continue CLI resolves `--config` first, then its saved last-used config, then the default assistant or `~/.continue/config.yaml` when not logged in. ```yaml name: Codex Pooler version: 1.0.0 schema: v1 models: - name: GPT-5.6 Terra via Codex Pooler provider: openai model: gpt-5.6-terra apiBase: http://localhost:4000/v1 apiKey: "${{ secrets.CODEX_POOLER_API_KEY }}" contextLength: 353400 defaultCompletionOptions: maxTokens: 128000 roles: - chat - edit - apply - summarize capabilities: - tool_use - image_input # Optional operator-only MCP metadata add-on. Omit for model/runtime use. mcpServers: - name: codex_pooler type: streamable-http url: http://localhost:4000/mcp requestOptions: timeout: 30000 headers: Authorization: "Bearer ${{ secrets.CODEX_POOLER_MCP_KEY }}" ``` For deployed instances, change `apiBase` to `https://codex-pooler.example.com/v1`; if you keep the optional operator MCP add-on, change the MCP `url` to `https://codex-pooler.example.com/mcp`. Continue uses `contextLength` for request pruning and `defaultCompletionOptions.maxTokens` for the completion budget. It prunes rather than summarizing/compacting locally, so keep the context length at Codex Pooler's 353.4k `gpt-5.6-terra` window instead of stale or generic provider metadata. Check the headless CLI path after saving the config: ```bash export CODEX_POOLER_API_KEY=<pool-api-key> npx -y @continuedev/cli@latest -p \ --config ~/.continue/config.yaml \ --silent \ 'Reply with exactly: continue ok' ``` The Pool API key authenticates model requests. The MCP token authenticates only the operator metadata endpoint. </details> <details> <summary><img src=".github/assets/cline-favicon.png" alt="Cline logo" width="16" height="16"> Cline <code>~/.cline</code> + <code>~/.cline/mcp.json</code></summary> Cline CLI accepts `openai` as shorthand for its OpenAI-compatible provider and stores it as `openai-compatible`. Configure it with the Pool API key, the Codex Pooler `/v1` base URL, and the model id that your assigned Pool can serve. ```bash cline auth \ --provider openai \ --apikey "$CODEX_POOLER_API_KEY" \ --baseurl http://localhost:4000/v1 \ --modelid gpt-5.6-terra ``` Cline's model metadata names are `contextWindow`, `maxInputTokens`, and `maxTokens`. If you add a manual Codex Pooler model entry in Cline settings, use `contextWindow: 353400`, `maxInputTokens: 225400`, and `maxTokens: 128000` so Cline's compaction trigger leaves room for a long completion inside the 353.4k Pooler window. Check the headless CLI path after saving auth: ```bash cline --provider openai \ --model gpt-5.6-terra \ --json \ --auto-approve false \ 'Reply with exactly: cline ok' ``` For optional operator MCP in Cline CLI, add the remote server to `~/.cline/mcp.json`. Codex Pooler does not require this for model use. The VS Code extension opens its own MCP settings JSON from the Cline MCP Servers panel; use the same `mcpServers` shape there. ```json { "mcpServers": { "codex_pooler": { "url": "http://localhost:4000/mcp", "headers": { "Authorization": "Bearer <operator-mcp-token>" }, "disabled": false, "autoApprove": [] } } } ``` For deployed instances, change `--baseurl` to `https://codex-pooler.example.com/v1` and, if you keep the optional operator MCP add-on, change the MCP `url` to `https://codex-pooler.example.com/mcp`. Use a Pool API key for `/v1` model requests and an operator MCP token for `/mcp`. Do not reuse the Pool API key for MCP. </details> <details> <summary><img src=".github/assets/goose-favicon.png" alt="Goose logo" width="16" height="16"> Goose <code>~/.config/goose/config.yaml</code></summary> Configure Goose's OpenAI provider for Codex Pooler's OpenAI-compatible chat-completions path. Keep the Pool API key in `OPENAI_API_KEY` or Goose's secret storage. Put persistent Goose provider and extension settings in `~/.config/goose/config.yaml` on macOS/Linux or `%APPDATA%\Block\goose\config\config.yaml` on Windows. Goose also keeps related files in that config area: `permission.yaml` for tool permission levels, `secrets.yaml` when file-based secret storage is used, `permissions/tool_permissions.json` for runtime permission decisions, and `prompts/` for prompt templates. Environment variables have higher precedence than the config file, so `OPENAI_API_KEY` can stay outside YAML. ```yaml GOOSE_PROVIDER: openai GOOSE_MODEL: gpt-5.6-terra OPENAI_HOST: http://localhost:4000 OPENAI_BASE_PATH: v1/chat/completions GOOSE_CONTEXT_LIMIT: 353400 GOOSE_MAX_TOKENS: 128000 GOOSE_AUTO_COMPACT_THRESHOLD: 0.63 ``` Goose reads `GOOSE_CONTEXT_LIMIT` and `GOOSE_MAX_TOKENS` into its model config. Its auto-compaction threshold is a ratio of the context limit, not an output reserve, so `0.63` compacts before prompt history can crowd out a 128k completion in Codex Pooler's 353.4k `gpt-5.6-terra` window. Check the headless CLI path with tool access enabled: ```bash export OPENAI_API_KEY="$CODEX_POOLER_API_KEY" goose run \ --no-session \ --provider openai \ --model gpt-5.6-terra \ --with-builtin developer \ --text 'Use your developer tool to create goose-ok.txt containing exactly: goose ok. Then reply with exactly: goose ok' ``` For optional operator MCP metadata access, add a remote Streamable HTTP extension. Codex Pooler model use does not require this. Goose stores remote extension headers in its config, so use a dedicated MCP token. ```yaml # Optional operator-only MCP metadata add-on. Omit for model/runtime use. extensions: codex_pooler: enabled: true type: streamable_http name: codex_pooler uri: http://localhost:4000/mcp headers: Authorization: "Bearer <operator-mcp-token>" timeout: 300 bundled: null available_tools: [] ``` For deployed instances, change `OPENAI_HOST` to `https://codex-pooler.example.com`; if you keep the optional operator MCP add-on, change the extension `uri` to `https://codex-pooler.example.com/mcp`. Use a Pool API key for OpenAI-compatible model requests and an operator MCP token for `/mcp`. Do not reuse the Pool API key for MCP. </details> <details> <summary><img src=".github/assets/windmill-favicon.png" alt="Windmill logo" width="16" height="16"> Windmill AI <code>customai</code> workspace provider</summary> Windmill AI can use Codex Pooler through Windmill's `customai` provider. Point the resource at Codex Pooler's OpenAI-compatible `/v1` surface, store the Pool API key as a Windmill secret variable, and make the workspace AI settings use that resource for chat and metadata generation. Use a dedicated Pool API key for Windmill: ```bash wmill variable add '<pool-api-key>' \ u/<owner>/codex_pooler_windmill_codegen \ --workspace <workspace> ``` Create a matching `customai` resource: ```yaml description: Codex Pooler API credentials for Windmill AI value: api_key: '$var:u/<owner>/codex_pooler_windmill_codegen' base_url: http://localhost:4000/v1 headers: {} resource_type: customai ``` Then set the Windmill workspace AI config to use the resource: ```yaml providers: customai: resource_path: u/<owner>/codex_pooler_windmill_codegen models: - gpt-5.6-luna - gpt-5.6-terra - gpt-5.6-sol default_model: provider: customai model: gpt-5.6-terra metadata_model: provider: customai model: gpt-5.6-terra ``` Windmill's agent request field is `max_completion_tokens`; provider adapters map that to OpenAI Responses `max_output_tokens` or chat `max_completion_tokens` as needed. Do not use `max_tokens` for GPT-5/O-series Windmill AI requests. For deployed Codex Pooler instances, change `base_url` to `https://codex-pooler.example.com/v1`. If Windmill is self-hosted and that URL resolves to a private or internal address from the Windmill app pod or server, set `ALLOW_PRIVATE_AI_BASE_URLS=true` on the Windmill app/server environment. Leave Windmill's code completion model unset unless you have separately configured a provider with fill-in-the-middle autocomplete support. Codex Pooler's `customai` setup is for Windmill chat, script/flow/app generation, fixes, summaries, metadata generation, and form-filling features that use chat completion style requests. </details> <details> <summary><img src=".github/assets/openhands-favicon.png" alt="OpenHands logo" width="16" height="16"> OpenHands <code>~/.openhands/</code></summary> OpenHands CLI can use Codex Pooler through the narrow OpenAI-compatible `/v1` surface. Keep the Pool API key in the environment, set the OpenHands base URL to `/v1`, and use the OpenAI model prefix that OpenHands expects. The command below uses `--override-with-envs`, so it does not persist Pool settings to OpenHands' local state. OpenHands CLI stores local state under `~/.openhands/`, created on first run. Current OpenHands CLI docs list `agent_settings.json` for LLM configuration and agent settings, `cli_config.json` for CLI preferences, `mcp.json` for MCP server configuration, and `conversations/` for conversation history. On Windows, OpenHands CLI runs through WSL in the upstream install docs, so those paths live in the WSL user's home directory. ```bash export LLM_API_KEY=<pool-api-key> export LLM_BASE_URL=http://localhost:4000/v1 export LLM_MODEL=openai/gpt-5.6-terra uvx --python 3.12 --from openhands openhands \ --headless \ --override-with-envs \ -t 'Check the repository and summarize what you can do.' ``` For deployed instances, change `LLM_BASE_URL` to `https://codex-pooler.example.com/v1`. The model name should stay `openai/gpt-5.6-terra` so OpenHands selects its OpenAI-compatible provider path while Codex Pooler routes the request through the assigned Pool. </details> <details> <summary><img src=".github/assets/python-favicon.png" alt="Python logo" width="16" height="16"> OpenAI Python SDK</summary> OpenAI Python SDK clients can use the OpenAI-compatible `/v1` surface by setting `base_url` to the Codex Pooler `/v1` URL and using the Pool API key as the API key. ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["CODEX_POOLER_API_KEY"], base_url="http://localhost:4000/v1", ) response = client.responses.create( model="gpt-5.6-terra", input="Write a one-sentence status update.", ) print(response.output_text) ``` For deployed instances, change `base_url` to `https://codex-pooler.example.com/v1`. </details> <details> <summary><img src=".github/assets/nodejs-favicon.png" alt="Node.js logo" width="16" height="16"> OpenAI Node SDK</summary> OpenAI Node SDK clients use the same OpenAI-compatible `/v1` surface. Configure `baseURL` with the Codex Pooler `/v1` URL and pass the Pool API key as the API key. ```js import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.CODEX_POOLER_API_KEY, baseURL: "http://localhost:4000/v1", }); const response = await client.responses.create({ model: "gpt-5.6-terra", input: "Write a one-sentence status update.", }); console.log(response.output_text); ``` For deployed instances, change `baseURL` to `https://codex-pooler.example.com/v1`. </details> <details> <summary><img src=".github/assets/vercel-favicon.png" alt="Vercel logo" width="16" height="16"> Vercel AI SDK</summary> Vercel AI SDK can point its OpenAI provider at Codex Pooler by creating a custom provider with `createOpenAI`. The provider calls the OpenAI-compatible `/v1` surface with the Pool API key. ```ts import { createOpenAI } from "@ai-sdk/openai"; import { generateText } from "ai"; const pooler = createOpenAI({ apiKey: process.env.CODEX_POOLER_API_KEY, baseURL: "http://localhost:4000/v1", }); const { text } = await generateText({ model: pooler.responses("gpt-5.6-terra"), prompt: "Write a one-sentence status update.", }); console.log(text); ``` For deployed instances, change `baseURL` to `https://codex-pooler.example.com/v1`. `GET /v1/models` may include `context_length` for clients that probe OpenAI-compatible model lists, such as Hermes. The official OpenAI SDK request APIs and Vercel AI SDK generation APIs do not expose Codex model-catalog context controls. Use their output-budget fields only when your application needs one: `max_output_tokens` in OpenAI Responses, `max_completion_tokens` in Chat Completions, and `maxOutputTokens` at the Vercel AI SDK layer. Codex Pooler's public `/v1/responses` currently rejects `context_management`, and public `/v1/responses/compact` is routed but unsupported, so do not document SDK-side compaction as a Codex Pooler feature. </details> <details> <summary><img src=".github/assets/claude-code-favicon.png" alt="Claude Code logo" width="16" height="16"> Claude Code</summary>  </details> ## Quick Start With Docker Compose This runs the published release image with a local Postgres database. It is the fastest way to try Codex Pooler on a laptop or small server. For normal use, run a versioned, tagged stable release from [GitHub Releases](https://github.com/icoretech/codex-pooler/releases). The `latest` image tag follows the most recently published release, but a version tag keeps the installation reproducible; run from source only in [Local Development](#local-development). Prerequisites: - Docker with Compose - Git, if you are cloning the repository - `openssl` Start Codex Pooler: ```bash git clone https://github.com/icoretech/codex-pooler.git cd codex-pooler # Run the latest tagged stable release. Find its version at # https://github.com/icoretech/codex-pooler/releases, then substitute it here. export CODEX_POOLER_IMAGE_TAG=<release-tag> scripts/self-host/generate-env.sh docker compose pull docker compose up -d ``` The first run pulls the app and Postgres images, waits for Postgres health, runs the migration container, then starts the web app. Open `http://localhost:4000`. On the first visit, create the owner account at `/bootstrap`, then sign in and start with `/admin/pools`. To verify the first-run redirect before opening a browser: ```bash curl -sS -D - -o /dev/null http://localhost:4000/
Use it for
Production installs, managed ingress, external Postgres, metrics, and separate runtime roles