Using LibreChat with SoAI

LibreChat can use SoAI models through a custom OpenAI-compatible endpoint and its Streamable HTTP MCP server with static bearer authentication.

Connect the model API

  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. If LibreChat will use MCP, open Settings > 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).
  3. Choose a server address reachable from the LibreChat server or container and present in its TLS certificate's subject alternative names.
  4. Make the LibreChat Node.js process trust the server CA, for example with NODE_EXTRA_CA_CERTS. Mount the CA into the container when LibreChat runs in Docker.

Add the custom endpoint

Merge a custom-endpoint entry into librechat.yaml and supply secrets through LibreChat environment interpolation:

version: 1.3.14

endpoints:
  custom:
    - name: SoAI
      apiKey: '${SOAI_OPENAI_API_KEY}'
      baseURL: 'https://SOAI_HOST:5090/v1'
      models:
        default:
          - 'YOUR_MODEL_ID'
        fetch: true
      titleConvo: false
      modelDisplayLabel: SoAI

The YAML holds only the reference, so define SOAI_OPENAI_API_KEY in the environment LibreChat reads. Restart LibreChat after changing its YAML, select the SoAI endpoint, choose a discovered model, and send a short prompt.

Use LibreChat's browser administration

If your deployment includes LibreChat's separate Admin Panel, sign in as a LibreChat administrator, open its configuration editor, and create the same endpoints.custom entry shown above: name SoAI, base URL https://SOAI_HOST:5090/v1, the SoAI API key, and the allowed model IDs. Save the configuration, then sign in again so the login-time configuration takes effect. Select SoAI and the model in a new chat before testing inference.

Connect MCP tools

mcpSettings:
  allowedAddresses:
    - 'SOAI_HOST:5090'

mcpServers:
  soai:
    type: streamable-http
    url: https://SOAI_HOST:5090/mcp
    requiresOAuth: false
    headers:
      Authorization: 'Bearer ${SOAI_MCP_TOKEN}'
    timeout: 120000

The explicit requiresOAuth: false is required for this static-header flow. Without it, LibreChat can interpret the unauthenticated bearer challenge as an OAuth requirement and postpone normal server initialization. Keep allowedAddresses limited to the exact private host and port when LibreChat runs on another machine or in a container.

Connect LibreChat to SoAI MCP in its interface

  1. Open MCP Settings from the right sidebar and select +.
  2. Set the server name to soai, enter https://SOAI_HOST:5090/mcp, and choose Streamable HTTP.
  3. Choose API-key authentication, select Bearer, and enable User provides key so each LibreChat user supplies a personal MCP token.
  4. Create the server, open its connection controls, enter the personal token, and select Initialize. Confirm that its status becomes connected.
  5. In a chat using the SoAI endpoint and a tool-capable model, open the MCP dropdown below the message input and enable soai. Ask for a harmless exposed tool action.

UI-created servers do not require a LibreChat restart. YAML-created servers do. If the settings panel is hidden, the LibreChat administrator must grant the relevant MCP-server permission or define a server that needs user initialization.

Related documentation