Using Crush with SoAI

Crush can use SoAI through a custom openai-compat provider and through its HTTP MCP client.

Create credentials in SoAI

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. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN). Create a separate personal token under MCP > MCP tokens; token creation also requires MCP usage (MCP_USE). Open Models and copy the exact model ID and its real context/output limits; this requires Model read access (MODEL_READ).

Configure Crush

Put the following commands in ~/.config/crush/crushrc. Crush distinguishes the official OpenAI provider from other compatible servers; SoAI must use openai-compat. 

provider add soai --type openai-compat --name SoAI \
  --base-url "https://SOAI_HOST:5090/v1" \
  --api-key "${SOAI_OPENAI_API_KEY:?set SOAI_OPENAI_API_KEY}" \
  --discover-models false

model add soai/YOUR_MODEL_ID --name "SoAI model" \
  --context-window 65536 --default-max-tokens 4096 --can-reason true
model large soai/YOUR_MODEL_ID --max-tokens 4096
model small soai/YOUR_MODEL_ID --max-tokens 1024

mcp add soai --type http --url "https://SOAI_HOST:5090/mcp" \
  --header Authorization "Bearer ${SOAI_MCP_TOKEN}"
export SOAI_OPENAI_API_KEY='YOUR_SOAI_API_KEY'
export SOAI_MCP_TOKEN='YOUR_MCP_TOKEN'
export SSL_CERT_FILE='/path/to/ca-bundle-containing-soai.pem'
crush run 'Explain what this project does.'

Set context, output, reasoning, and image flags to the selected SoAI model's actual capabilities. Ask Crush to invoke a harmless exposed tool to verify MCP after loading the configuration.

Troubleshooting

If model discovery is enabled, an unavailable or filtered model can change the resulting catalog; the example pins one model deliberately. Model authentication uses the SoAI API key. MCP uses its separate token. Do not place either secret directly in a committed crushrc, and do not disable TLS verification.

Related documentation