Coding agents can use this server in three ways. Run the agent in the browser terminal, point a supported
OpenAI-compatible or Anthropic-compatible client at its /v1 APIs, or register its /mcp
endpoint as an MCP server. The terminal provides a shell, the API provides model inference, and MCP provides tools,
resources, and prompts to an external agent.
Choose the connection
| Method | What the agent gets | When to use it |
|---|---|---|
| WebUI terminal | A real shell on the SoAI host through an interactive PTY. | Use a CLI that you want to run on the server's files and processes. The CLI keeps its own model and provider configuration. |
| Compatible model API | SoAI's routed models through /v1. |
Use a client that accepts a custom base URL, model ID, and API key. Codex and opencode use the OpenAI routes; Claude Code uses the Anthropic-compatible Messages routes. |
| MCP server | SoAI tools, resources, and prompts over Streamable HTTP. | Use an MCP-capable agent when you want it to call SoAI's browser, files, knowledge, hardware, or other enabled tools. The agent's model remains configured in the agent. |
Supported clients and surfaces
"Model API" means the client can send inference requests through SoAI. "MCP" means the client can connect to SoAI's Streamable HTTP tool server. An MCP-only client keeps using its own model provider. Each client page includes its official graphical, browser, or interactive-terminal setup flow when that client exposes one. If the official client only supports a configuration file or command, the page documents that supported route without inventing a UI workflow.
| Client | Model API | MCP | Important boundary |
|---|---|---|---|
| aider | OpenAI Chat Completions | No native MCP client | Prefix the model with openai/. |
| Antigravity CLI | No compatible custom provider | Yes | Connect SoAI as an MCP server. |
| AnythingLLM | OpenAI Chat Completions | Yes | MCP definitions originate in its storage configuration file. |
| Claude Code | Anthropic Messages | Yes | Use the SoAI origin without /v1 for ANTHROPIC_BASE_URL. |
| Cline | OpenAI Chat Completions | Yes | Its settings UI exposes provider capabilities and remote MCP. |
| Codex | OpenAI Responses | Yes | The selected SoAI model must advertise Responses support. |
| Crush | OpenAI Chat Completions | Yes | Use provider type openai-compat. |
| Cursor Editor and CLI | No arbitrary compatible endpoint | Yes | Connect SoAI as an MCP server. |
| DeepSeek Harness | OpenAI Chat Completions | No remote MCP setup | Use its custom model provider. |
| Gemini CLI | No compatible custom provider | Yes | Connect SoAI as an MCP server. |
| GitHub Copilot | Yes, in the Copilot app | Yes | The app, editor, CLI, and cloud agents have different connection boundaries. |
| goose | OpenAI Chat Completions | Yes | SoAI is a custom OpenAI host and a separate extension. |
| Hermes Agent | OpenAI Chat Completions | Yes | Use a custom provider and its CA-bundle setting. |
| Kilo Code | OpenAI Chat Completions | Yes | Custom provider and MCP settings are available in the extension UI. |
| LibreChat | OpenAI Chat Completions | Yes | Declare static bearer authentication explicitly so LibreChat does not start OAuth discovery. |
| LiteLLM | OpenAI Chat Completions | Yes | It adds another gateway and credential boundary in front of SoAI. |
| LM Studio | Not a SoAI model client | Yes, with server permission | LM Studio hosts its own model and can call SoAI MCP tools. |
| OpenClaw | OpenAI Chat Completions or Responses | Yes | Declare only capabilities the selected model supports. |
| opencode | OpenAI Chat Completions | Yes | Model and MCP credentials are separate. |
| OpenHands CLI | OpenAI Chat Completions | Yes | Use --override-with-envs when supplying the model through environment variables. |
| Open WebUI | OpenAI Chat Completions | Yes | Both connections are configured by an Open WebUI administrator. |
| Pi | OpenAI Chat Completions | No native MCP client | Add SoAI to Pi's custom model catalog. |
| Qwen Code | OpenAI Chat Completions | Yes | Use its OpenAI model-provider entry, not a Google endpoint. |
| Roo Code | OpenAI Chat Completions | Yes | Agent tool use requires a model with native tool calling. |
| SillyTavern | OpenAI Chat Completions | No native MCP client | Use its Custom OpenAI-compatible connection. |
| Devin Desktop | No arbitrary compatible endpoint | Yes | Use the current Devin Local MCP configuration; Cascade uses a separate legacy file. |
| Zed Agent | OpenAI Chat Completions or Responses | Yes | ACP-hosted external agents keep separate model configuration. |
Prepare credentials
Finish the setup wizard first. Select the Settings button at the right of the header, then choose
Settings. The OpenAI tab is visible to administrators with
API key management (OPENAI_API_ADMIN). Create a SoAI API key there when the agent
will call /v1. Once SoAI stores an API-key record, the OpenAI-compatible and Anthropic-compatible routes
require that key. The MCP tab appears only to an Administrator with
MCP administration (MCP_ADMIN).
Create a separate personal token in MCP > MCP tokens; token creation also requires
MCP usage (MCP_USE). Changing the MCP
runtime, server-mode, or exposure settings also requires Configuration changes
(CONFIG_PATCH).
Do not put either secret in a project file that will
be committed.
Replace SOAI_HOST with the hostname or LAN address reachable from the agent. Local clients (on the same machine) can use
http://127.0.0.1:5090. For a client on another trusted device, use
https://SOAI_HOST:5090 over a controlled LAN or VPN. A private reverse proxy that terminates TLS on
the standard HTTPS port can expose the same paths at https://SOAI_HOST. Do not publish the complete
SoAI interface to the internet. Read
Security hardening for the deployment boundary and
Network and TLS for certificate and proxy configuration.
Method 1: use the SoAI WebUI terminal
The Terminal route is available to users with the Terminal and shell access (TERMINAL_USE)
permission while
SERVER.WEBUI.TERMINAL.ENABLED
is enabled. An administrator with the Configuration changes (CONFIG_PATCH) permission selects the
Settings button at the right of the header, chooses Settings, selects
Advanced in the page header, then opens Server and changes the
Terminal setting before selecting Save.
Terminal appears in the default sidebar for an Administrator or a Standard user who has been
granted that permission, unless that user has hidden the item in their sidebar settings. Open the direct route at
/#terminal and start the agent from the project directory. The terminal runs with the SoAI service
account's permissions. The Terminal page describes its PTY boundary and audit
behavior. This method does not route the CLI's model requests through SoAI.
Method 2: use a compatible model API
For an OpenAI-compatible client on another device, configure the base URL https://SOAI_HOST:5090/v1, a model
ID returned by GET /v1/models, and the SoAI API key. Use http://127.0.0.1:5090/v1 only for
a same-machine connection. The client must use endpoints and request fields that the selected SoAI model and plugin
support. Streaming responses follow the OpenAI SSE format.
export SOAI_OPENAI_API_KEY='YOUR_SOAI_API_KEY'
curl https://SOAI_HOST:5090/v1/models \
-H "Authorization: Bearer $SOAI_OPENAI_API_KEY"
curl https://SOAI_HOST:5090/v1/chat/completions \
-H "Authorization: Bearer $SOAI_OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Reply with one word."}]}'
For Claude Code, set ANTHROPIC_BASE_URL to https://SOAI_HOST:5090 without /v1;
Claude Code appends /v1/messages. Supply the same SoAI API key through
ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY. See the
Claude Code page for the complete configuration and TLS requirements.
See the individual Claude Code, opencode, and Codex pages for client-specific configuration.
Method 3: use MCP
Register http://127.0.0.1:5090/mcp for a same-machine client. A lower-impact remote client on the
private network can use https://SOAI_HOST:5090/mcp. Send
Authorization: Bearer YOUR_MCP_TOKEN.
An Administrator with MCP administration
(MCP_ADMIN) and Configuration changes (CONFIG_PATCH) selects the
Settings button at the right of the header, chooses Settings, then opens
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 the agent. An MCP
token authenticates MCP requests only. It does not authenticate /v1 requests or create a WebUI session.
After registration, ask the client to list its MCP tools or run its MCP status command. A successful connection should show the SoAI server and its enabled tools, resources, and prompts. If the client reports an HTTP or protocol error, check the endpoint, token, server-mode setting, origin policy, and the client log before changing model settings. The MCP overview covers server configuration and security.
Keep high-impact MCP tools, especially shell and host-affecting tools, for a trusted local client connected to a local SoAI instance when that deployment is safe. Do not expose them to remote clients. Review Security hardening before choosing the server-mode tool list or network boundary.
Related documentation
- Using Claude Code with SoAI
- Using opencode with SoAI
- Using Codex with SoAI
- Security hardening
- MCP overview
- Terminal
- Using Open WebUI with SoAI, Using LibreChat with SoAI, and Using LM Studio with SoAI
- Using Cline with SoAI, Using Roo Code with SoAI, Using Kilo Code with SoAI, and Using Zed Agent with SoAI
- Using Cursor with SoAI, Using Devin Desktop with SoAI, and Using GitHub Copilot with SoAI
- Using AnythingLLM with SoAI, Using LiteLLM with SoAI, Using SillyTavern with SoAI, and Using OpenClaw with SoAI