Using Claude Code with SoAI

Claude Code can use SoAI as its model provider through the Anthropic-compatible Messages API. It can also connect to the same server's tools, resources, and prompts through MCP. These are independent connections and can be used separately or together.

Connect SoAI as Claude Code's model provider

  1. Complete the setup wizard and select a chat model or virtual model that supports the capabilities Claude Code needs, especially tool calling.
  2. In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, select OpenAI, and create a SoAI API key. This tab appears to administrators with the API key management (OPENAI_API_ADMIN) permission. Copy the secret when the WebUI shows it.
  3. Set ANTHROPIC_BASE_URL to the server origin, without /v1, and select the model identifier. Claude Code appends /v1/messages itself.
export ANTHROPIC_BASE_URL='https://SOAI_HOST:5090'
export ANTHROPIC_AUTH_TOKEN='YOUR_SOAI_API_KEY'
export ANTHROPIC_MODEL='YOUR_SOAI_MODEL_ID'
claude

ANTHROPIC_API_KEY is also accepted and is sent as x-api-key. When both credential forms are present, they must contain the same key. A local server certificate authority can be supplied to Claude Code's Node.js runtime with NODE_EXTRA_CA_CERTS. Do not disable TLS verification.

The server implements POST /v1/messages and POST /v1/messages/count_tokens. The Messages route supports streaming plus the text, image, tool, reasoning, and structured-output fields listed in the HTTP API reference. It rejects unsupported Anthropic fields before inference starts.

Connect SoAI as an MCP server

  1. In the SoAI WebUI, complete the setup wizard. 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. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN); changing these server settings also requires Configuration changes (CONFIG_PATCH).
  2. Open MCP > MCP tokens and create a personal access token. Token creation also requires MCP usage (MCP_USE). Copy the secret when the WebUI shows it; the full value is not displayed again.
  3. Run claude mcp add with the Streamable HTTP endpoint and bearer header. Keep the token in an environment variable rather than putting it in shell history or a project file.
export SOAI_MCP_TOKEN='YOUR_MCP_TOKEN'
claude mcp add --transport http \
  --header "Authorization: Bearer $SOAI_MCP_TOKEN" \
  soai https://SOAI_HOST:5090/mcp

Use https://SOAI_HOST/mcp when a TLS reverse proxy fronts the server (and terminates TLS). A local installation can use http://127.0.0.1:5090/mcp. Claude Code stores the server entry in its own configuration; the token authenticates MCP requests only.

Verify the connection

Start Claude Code and send a short prompt, then ask it to perform a harmless read-only tool action in a test workspace. For MCP, run claude mcp list, confirm that soai is configured, and use the /mcp panel to inspect exposed tools. A model response verifies the Messages connection; the MCP tool list verifies the separate MCP connection.

Limits and troubleshooting

The server does not expose an Anthropic-shaped Models endpoint. Configure ANTHROPIC_MODEL explicitly with an ID from the Models page or GET /v1/models. Opening the page requires Model read access (MODEL_READ).

If model requests return 404, remove /v1 from ANTHROPIC_BASE_URL. For certificate failures, trust the server certificate authority with NODE_EXTRA_CA_CERTS. For model-provider authentication failures, verify the SoAI API key. MCP uses its own personal access token: if that server is missing, check that the MCP runtime and server mode are enabled and that its URL ends in /mcp. For an absent MCP tool, review the server-mode exposed-tool list and the tool's own availability requirements.

Claude Code can also run inside the WebUI terminal, but that gives it a shell on the host and keeps its model configuration unchanged. See Connect coding agents to SoAI, MCP, and Terminal for the surrounding permissions.

Related documentation