Using LM Studio with SoAI

LM Studio is a local model host, not a client for selecting a remote SoAI OpenAI- or Anthropic-compatible model. Its relevant SoAI integration is MCP: a model loaded by LM Studio can call tools from SoAI's Streamable HTTP server.

Prepare SoAI MCP

In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, open MCP > MCP tokens. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN), and creating a personal token also requires MCP usage (MCP_USE). Changing server mode or its exposed tools also requires Configuration changes (CONFIG_PATCH). Trust the SoAI CA on the LM Studio host.

Add the server in LM Studio

  1. For app chat, open the right-side Program tab, select Install, then Edit mcp.json. For local-server use, open Developer > Local Server and select mcp.json.
  2. Add the entry below and replace YOUR_MCP_TOKEN with the actual personal SoAI MCP token.
{
  "mcpServers": {
    "soai": {
      "url": "https://SOAI_HOST:5090/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

LM Studio's documented mcp.json format puts the header value in the file. Restrict access to that file. For app chat, load a tool-capable local model, enable the soai program in the chat, and approve a harmless read-only call.

Enable MCP for the local API server

  1. Open Developer > Local Server > Server Settings.
  2. Enable Require Authentication, then enable Allow calling servers from mcp.json. LM Studio requires authentication before it permits this server-wide MCP setting.
  3. Open Manage Tokens and select Create new token. For that token, set Allow calling servers from mcp.json to Allow, then copy the token.
  4. Start the local server from Developer > Local Server. Requests to LM Studio must use this LM Studio token; it is separate from the SoAI MCP token stored in mcp.json.

Synchronizing mcp.json does not grant the local API server permission to use the integration. If a request returns Permission denied to use plugin, open the LM Studio application and enable Allow calling servers from mcp.json in local-server settings.

In an /api/v1/chat request, attach {"type":"plugin","id":"mcp/soai"} in the integrations array. Use its allowed_tools field to expose only the tools needed for the task; sending a large MCP catalog can exceed a local model's context window.

Architecture and troubleshooting

Do not enter SoAI's /v1 URL as an LM Studio remote model provider: that reverses the intended roles. LM Studio hosts the model; SoAI supplies MCP tools. For a permission error, enable the explicit local-server MCP permission. For connection errors after permission is enabled, check the token, CA trust, server mode, exposed tools, and /mcp URL.

Related documentation