Host mode lets SoAI connect to an external MCP server, discover its tools, resources, and prompts, and make eligible items available to conversations. Adding a server does not automatically authorize every chat to use every tool.
Add and operate an external server
- In the SoAI WebUI, select the Settings button at the right of the header, then Settings > MCP.
- Under MCP servers, select Add server.
- Choose Remote (HTTP) for Streamable HTTP or STDIO for a local command.
- Enter a Name and Endpoint. For HTTP, choose OAuth (recommended), API key, or None. The STDIO form does not use remote authentication.
- Set Timeout (seconds) and Auto reconnect if the defaults do not fit the service.
- For OAuth, select Save & authorize and complete the provider flow. For API key, None, or STDIO connections, select Save & connect.
The MCP tab appears only to an Administrator with
MCP administration
(MCP_ADMIN), and the same requirement applies when
adding or changing a server. Host mode must also remain enabled by
TOOLS.MCP.HOST_MODE.ENABLED.
Operate a saved connection
Use the Enabled switch to exclude a server without deleting its settings. Use
Connect and Disconnect for the live session, Edit for its transport
or credentials, and Delete to remove the record. Connections shows live session
state. Resources and Prompts show capabilities discovered from external servers.
Tools combines discovered remote tools with SoAI's registered built-in tools; the server name on
each entry identifies its source. Reading runtime status and the discovered Resources, Prompts, and Tools panels requires
MCP usage (MCP_USE).
Automatic startup connection and bounded retry behavior are governed by
TOOLS.MCP.HOST_MODE.AUTO_CONNECT_ON_STARTUP,
TOOLS.MCP.HOST_MODE.RECONNECT_DELAY_SEC,
and
TOOLS.MCP.HOST_MODE.MAX_RECONNECT_ATTEMPTS.
A disconnected server remains visible with its connection state; SoAI does not present retained discovery data as a
current healthy connection.
Configure client capabilities
Under client roots, enter a Root URI and optional Name, then select
Save. Roots tell connected servers about locations the MCP client considers relevant; they do not
bypass SoAI file permissions or the external server's own access controls. The saved list maps to
TOOLS.MCP.HOST_MODE.ROOTS.
Reading or changing roots also requires MCP usage
(MCP_USE).
Control server-initiated interactions
External servers can request model sampling only when
TOOLS.MCP.HOST_MODE.SAMPLING.ENABLED
is enabled. They can request user input only when
TOOLS.MCP.HOST_MODE.ELICITATION.ENABLED
is enabled. Both are off by default. Administrators resolve waiting elicitation requests under
Pending interactions; unresolved requests reach an explicit timeout instead of waiting forever.
Viewing or resolving these requests requires MCP usage
(MCP_USE).
Use discovered tools in Chat
Open Chat's tool configuration and choose only the discovered capabilities the conversation needs. Tool availability
still depends on the signed-in user's
MCP usage
(MCP_USE), the current connection, the selected Chat
mode, and the tool's own requirements. See Agent mode, tool approvals, and checkpoints
for conversation-level selection and approval behavior.