OpenCode

OpenCode should use Codex Pooler through the narrow OpenAI-compatible /v1 surface. The Pool API key authenticates model requests. A separate operator MCP token authenticates the remote MCP endpoint.

For a deployed instance, use these URLs:

OpenCode provider base URL:
https://pooler.example.com/v1

Remote MCP URL:
https://pooler.example.com/mcp

For local setup, replace the host with http://localhost:4000.

Provider example

Store the Pool API key outside the config and read it through environment expansion.

{
  "provider": {
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "Codex Pooler",
      "options": {
        "baseURL": "https://pooler.example.com/v1",
        "apiKey": "{env:CODEX_POOLER_API_KEY}",
        "reasoningEffort": "high",
        "reasoningSummary": "auto",
        "textVerbosity": "medium",
        "include": ["reasoning.encrypted_content"],
        "store": false
      },
      "models": {
        "gpt-5.5": {
          "id": "gpt-5.5",
          "name": "GPT-5.5 via Codex Pooler",
          "family": "gpt",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 400000,
            "input": 256000,
            "output": 128000
          }
        }
      }
    }
  }
}

Define only model ids your assigned Pool can serve. If you run Codex Pooler locally, set baseURL to http://localhost:4000/v1.

Remote MCP example

Add Codex Pooler as a remote MCP server when the OpenCode host should inspect metadata that the operator can already see in the admin UI.

{
  "mcp": {
    "codex_pooler": {
      "type": "remote",
      "url": "https://pooler.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <operator-mcp-token>"
      },
      "enabled": true,
      "timeout": 30000
    }
  }
}

Use a dedicated operator MCP token for hosts that persist remote MCP headers. Don’t use a Pool API key for /mcp.

Compatibility notes

Codex Pooler provides narrow OpenAI-compatible /v1 support for selected SDK routes. Supported OpenCode traffic should stay on /v1/responses or /v1/chat/completions, depending on the OpenAI provider path OpenCode uses.

GET /v1/responses is narrow Responses websocket compatibility, not /v1/realtime support. /v1/realtime and OpenAI Realtime SDK websocket or session routes are unsupported.

Unsupported /v1 routes return deterministic OpenAI-shaped unsupported endpoint errors when explicitly routed. Don’t treat Codex Pooler as full OpenAI API parity.