Using Open WebUI with SoAI

Open WebUI can use SoAI as an OpenAI-compatible model connection and native Streamable HTTP MCP tool server.

Connect the model API

  1. In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, and open OpenAI. This tab appears only to an Administrator with API key management (OPENAI_API_ADMIN). Select Create key and copy the key when it is shown.
  2. Open MCP > MCP tokens. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN), and creating a separate personal token also requires MCP usage (MCP_USE).
  3. Open Models and confirm the models intended for Open WebUI advertise Chat Completions and the tool/structured-output capabilities the UI will request. This requires Model read access (MODEL_READ).

Add the model connection

  1. Sign in to Open WebUI as an administrator.
  2. Open Admin Settings > Connections > OpenAI and add a connection.
  3. Set the URL to https://SOAI_HOST:5090/v1 and paste the SoAI API key.
  4. Save, refresh the model list, and select an exact model ID in a new chat.

A populated picker confirms model discovery; send a message to confirm inference.

Add native MCP tools

Native MCP requires Open WebUI 0.6.31 or newer.

  1. As an Open WebUI administrator, open Admin Settings > Integrations and select +.
  2. Select MCP (Streamable HTTP), enter https://SOAI_HOST:5090/mcp, and configure Bearer authentication with the personal MCP token in the Key field.
  3. Select Save, then use Verify Connection and confirm that the server returns its exposed tools.
  4. Open a chat, select + > Integrations > Tools, and enable the SoAI integration for that chat.

Only an Open WebUI administrator can register an MCP server. Use the integration's Access Control settings when it should be available only to particular Open WebUI users or groups. These permissions are distinct from SoAI's MCP permissions.

Deployment and troubleshooting

The Open WebUI server process (including one in a container), rather than only the browser, must trust the server CA. When Open WebUI also accesses public HTTPS services, use a combined bundle containing the operating-system roots and that CA. Replacing the system bundle with only that CA can break unrelated downloads. Never disable TLS verification.

Troubleshooting

If models appear but chat fails, inspect the selected model's capabilities and the SoAI API key. If MCP verification fails, inspect the separate MCP token, URL, server-mode switch, and exposed-tool list. Do not paste the MCP token into the OpenAI connection or the SoAI API key into the MCP connection.

Related documentation