Using GitHub Copilot with SoAI

GitHub Copilot has two separate SoAI connections. The standalone Copilot app can use SoAI as an OpenAI-compatible model provider. VS Code, Copilot CLI, Copilot cloud agent, and Copilot code review can use SoAI as an MCP server. Configure only the surface you use.

Use SoAI models in the Copilot app

GitHub currently labels custom model providers in the GitHub Copilot app as a public preview. This path requires the app and sign-in with a GitHub account. A Copilot plan is not required when you supply the model provider.

  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 Models and copy the exact ID of a model that supports the endpoint and capabilities the Copilot app will use. This requires Model read access (MODEL_READ).
  3. In the Copilot app, open app settings, select Model providers, then Add provider.
  4. Choose Any OpenAI-compatible HTTP endpoint. Enter a display name, base URL https://SOAI_HOST:5090/v1, and the SoAI API key, then select Add provider.
  5. Select the SoAI model in the app's model picker and send a short request. The app stores the credential in the operating system's credential store.

This model-provider setup applies to the standalone Copilot app. It does not change the provider used by Copilot in VS Code, Copilot CLI, Copilot cloud agent, or Copilot code review.

Connect local MCP clients

In the SoAI WebUI, 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).

Local VS Code Agent

This path requires VS Code 1.99 or later and access to Copilot. For an account managed by a GitHub Business or Enterprise organization, an administrator must also enable the MCP servers in Copilot policy.

  1. Open the Command Palette and run MCP: Add Server.
  2. Choose HTTP, enter https://SOAI_HOST:5090/mcp, and choose a user or workspace scope.
  3. Open the generated mcp.json and add a secure prompted input for the bearer token as shown below.
  4. Run MCP: List Servers, start soai, accept the trust prompt, then use Configure Tools in Agent chat to enable only required tools.
{
  "inputs": [
    {
      "type": "promptString",
      "id": "soai-mcp-token",
      "description": "SoAI MCP token",
      "password": true
    }
  ],
  "servers": {
    "soai": {
      "type": "http",
      "url": "https://SOAI_HOST:5090/mcp",
      "headers": {
        "Authorization": "Bearer ${input:soai-mcp-token}"
      }
    }
  }
}

Copilot CLI

Use the interactive /mcp add form, or run:

copilot mcp add --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN" \
  --tools "read_only_tool_a,read_only_tool_b" \
  soai https://SOAI_HOST:5090/mcp

copilot mcp list

User-level configuration is stored in ~/.copilot/mcp-config.json; project configuration may use .mcp.json or .github/mcp.json. Avoid --show-secrets in shared terminals or logs.

Copilot cloud agent and code review

  1. As a repository administrator, open the repository on GitHub. Select Settings, then under Code, planning, and automation, select Copilot > MCP servers.
  2. Add a remote server with type http, its HTTPS URL, and an explicit tools list. The hosted services execute enabled tools autonomously, so prefer a narrow read-only list instead of *.
  3. Create an Agents secret named COPILOT_MCP_SOAI_TOKEN and reference it from the Authorization header, then select Save MCP configuration.
  4. If code review should use the server, open Copilot > Code review and leave Allow Copilot to use MCP tools when reviewing pull requests on. The setting is on by default.
{
  "mcpServers": {
    "soai": {
      "type": "http",
      "url": "https://PUBLIC_SOAI_HOST/mcp",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_SOAI_TOKEN"
      },
      "tools": ["read_only_tool_a", "read_only_tool_b"]
    }
  }
}

Repository MCP configuration is shared by Copilot cloud agent and Copilot code review. Both support MCP tools but not MCP resources or prompts, and neither asks for approval before using an enabled tool. GitHub's hosted services cannot reach a private LAN address such as 192.168.x.x or trust a private SoAI CA automatically. This flow requires a deliberately exposed, publicly resolvable HTTPS endpoint with a publicly trusted certificate and suitable network controls. Do not expose SoAI merely to make this integration work.

Related documentation