Using Zed Agent with SoAI

Zed Agent can use a custom OpenAI-compatible SoAI provider and a remote SoAI MCP server. External agents hosted in Zed through ACP keep their own model configuration unless that agent documents otherwise.

Prepare SoAI

  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. Open Models and copy the exact model ID; this requires Model read access (MODEL_READ).
  2. For MCP, select the Settings button at the right of the header, choose Settings, then open MCP > MCP tokens. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN), and creating a token also requires MCP usage (MCP_USE). Changing the MCP runtime, server mode, or exposed capabilities under MCP configuration also requires Configuration changes (CONFIG_PATCH).

Connect Zed Agent to the SoAI model API

  1. Run agent: open settings, then open LLM Providers.
  2. Select Add Provider and choose an OpenAI-compatible provider.
  3. Enter a provider name, https://SOAI_HOST:5090/v1, the SoAI API key, an exact model ID, and the model's real context window.
  4. Choose Chat Completions unless the selected model advertises Responses support. Configure tool, image, parallel-tool, reasoning, and output-token settings only when supported.
  5. Select the model in the Agent Panel and send a short request. Zed stores UI-entered keys in the system keychain, not in settings.json.

Connect Zed Agent to SoAI MCP in Zed Settings

  1. Open Settings > AI > MCP Servers.
  2. Select Add Server > Add Remote Server.
  3. Name it soai, enter https://SOAI_HOST:5090/mcp, and add the Authorization: Bearer YOUR_MCP_TOKEN header.
  4. Confirm the status indicator is green and says Server is active, then enable only the required tools in the Agent profile.
{
  "context_servers": {
    "soai": {
      "url": "https://SOAI_HOST:5090/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" }
    }
  }
}

Related documentation