Using opencode with SoAI

opencode can use SoAI for both models and tools. The provider configuration calls SoAI's OpenAI-compatible API, and the MCP configuration calls SoAI's tool server. Keep the two credentials separate.

Connect the model API

In the SoAI WebUI, open Models from the sidebar and copy the exact model ID shown by the catalog. This requires Model read access (MODEL_READ). You can also query it from the machine where opencode will run: 

export SOAI_OPENAI_API_KEY='YOUR_SOAI_API_KEY'
curl http://SOAI_HOST:5090/v1/models \
  -H "Authorization: Bearer $SOAI_OPENAI_API_KEY"

Create the SoAI API key in Settings > OpenAI. This tab appears to administrators with the API key management (OPENAI_API_ADMIN) permission. Open the model's Capabilities card before selecting it in opencode; SoAI checks that profile for chat, tool calls, structured output, and other requested fields.

Configure the provider

Create opencode.json in the project directory, or place the same provider block in your global opencode configuration. Replace YOUR_MODEL_ID with the ID returned by /v1/models and keep the key in the environment. 

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "soai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "SoAI",
      "options": {
        "baseURL": "http://SOAI_HOST:5090/v1",
        "apiKey": "{env:SOAI_OPENAI_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "SoAI model"
        }
      }
    }
  }
}

The provider must use @ai-sdk/openai-compatible for SoAI's chat-completions surface. For current provider fields and configuration precedence, see the official opencode documentation linked below.

Finish in the opencode interface

  1. Start opencode and enter /connect.
  2. Select Other, enter soai as the provider ID, and paste the SoAI API key. The ID must match the soai key in opencode.json.
  3. Enter /models and select SoAI > YOUR_MODEL_ID, then send a short prompt.

The /connect dialog stores the credential only; it does not create the provider definition or base URL. Keep the opencode.json block above. For a non-interactive run, use opencode -m soai/YOUR_MODEL_ID.

Add SoAI tools through MCP

In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, then open MCP > MCP configuration and enable the MCP runtime and server mode. 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 in MCP > MCP tokens. Token creation also requires MCP usage (MCP_USE). Set Tools exposed by server mode, Resources exposed by server mode, and Prompts exposed by server mode for the operations opencode may use. Then merge this mcp block into the same top-level object as provider. Set oauth to false because SoAI uses the bearer token in this configuration rather than an OAuth flow. Set SOAI_MCP_TOKEN in the environment before starting opencode. 

{
  "mcp": {
    "soai": {
      "type": "remote",
      "url": "http://SOAI_HOST:5090/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:SOAI_MCP_TOKEN}"
      }
    }
  }
}

Use opencode mcp list to inspect the connection. The official opencode documentation covers its remote-server configuration; MCP overview explains SoAI-side permissions.

Check failures

A model-list failure can mean the base URL is wrong, the SoAI API key is missing, or the SoAI model is not available. If soai/YOUR_MODEL_ID returns an unsupported-capability error, select a model or plugin whose Capabilities card includes the requested operation. An MCP failure is separate: check the /mcp URL, token, server-mode setting, and exposed tools. Do not place the MCP URL under the provider's baseURL; they are different protocols.

Related documentation