Codex CLI can use SoAI as its model provider through the OpenAI-compatible Responses API. It can also register the server as an MCP endpoint when you want Codex to call its tools. These connections are independent: the SoAI API key authorizes inference requests, while the MCP token authorizes tool access.
Get a model ID and SoAI API key
In the SoAI WebUI, open Models from the sidebar, select the catalog model, and review its Capabilities
card. This requires Model read access (MODEL_READ). Under Endpoints, Responses must be enabled because Codex uses
/v1/responses. Codex also sends tool definitions on every request, so the same card must
show Tool calling and Parallel tool calls enabled. A model that advertises Responses alone is
rejected during admission, before the request reaches the plugin. Then select the Settings button at the right of the header, choose
Settings, select OpenAI, and create a SoAI API key. The OpenAI tab appears to administrators with the
API key management (OPENAI_API_ADMIN) permission. Use the exact catalog model ID in the Codex configuration,
including the plugin prefix that /v1/models returns. Identifiers look like
llamacpp/unsloth/Qwen3.5-4B-GGUF/Qwen3.5-4B-UD-Q8_K_XL.gguf; the bare model name without its prefix is not a valid ID.
export SOAI_OPENAI_API_KEY='YOUR_SOAI_API_KEY' curl http://SOAI_HOST:5090/v1/models \ -H "Authorization: Bearer $SOAI_OPENAI_API_KEY"
Configure Codex to use SoAI
Add a provider to ~/.codex/config.toml. The wire_api value tells Codex to use the Responses
protocol, which SoAI exposes at /v1/responses. Replace YOUR_MODEL_ID with a catalog ID and
keep the SoAI API key in the environment.
model = "YOUR_MODEL_ID" model_provider = "soai" [model_providers.soai] name = "SoAI" base_url = "http://SOAI_HOST:5090/v1" env_key = "SOAI_OPENAI_API_KEY" wire_api = "responses"
Keep this provider block in the user-level file. Codex ignores model_provider and
model_providers in a project-local .codex/config.toml.
Use https:// in base_url when SoAI serves TLS. If that certificate comes from the SoAI local root CA
rather than a public authority, Codex reports no certificate error and instead retries,
printing Reconnecting... waiting for network until it gives up, so point
Codex at the CA certificate it needs to verify the connection.
export SSL_CERT_FILE=/path/to/soai/data/config/tls/soai-local-root-ca.crt codex exec 'print the current branch'
Start Codex with codex, or use codex exec for a one-shot check. The request still depends
on the selected model and plugin advertising the capabilities Codex asks for. Check the
official Codex configuration documentation when your installed CLI reports an unknown provider field.
Add SoAI MCP tools
In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, then open
MCP > MCP configuration. Enable the MCP runtime and server mode, then set
Tools exposed by server mode, Resources exposed by server mode, and
Prompts exposed by server mode for Codex. The MCP tab appears
only to an Administrator with MCP administration
(MCP_ADMIN); changing those server settings
also requires Configuration changes
(CONFIG_PATCH). Create a personal token under
MCP > MCP tokens, which also requires MCP usage
(MCP_USE). Export it, then register the Streamable HTTP endpoint:
export SOAI_MCP_TOKEN='YOUR_MCP_TOKEN' codex mcp add soai \ --url http://SOAI_HOST:5090/mcp \ --bearer-token-env-var SOAI_MCP_TOKEN codex mcp list
codex mcp list confirms that the entry is saved; it does not prove that a live MCP session completed.
Start Codex, ask it to list or use a harmless read-only tool, and confirm the connection in the client or server
log. The server must expose the requested tool. An MCP token does not authenticate the model provider or a WebUI session.
MCP overview covers server mode, origins, and exposed tools, resources, and prompts.
Separate the failure domains
If Codex cannot load a model, test /v1/models, the SoAI API key, the provider base URL, and the model ID.
If Codex lists the model but a request fails, compare the requested operation with the model's
Capabilities card, checking Responses, Tool calling, and
Parallel tool calls together. A missing capability is refused during admission, and the error body reports only that
validation failed; the SoAI log names the capability that was missing.
MCP errors require a separate check of the /mcp URL, token, server-mode setting, and exposed tools.
Codex can also run inside the WebUI terminal. That gives it a host shell but does not route Codex's model requests through the server unless you configure the provider above. See Connect coding agents to SoAI for the three connection methods.