Use SoAI as an MCP server | SoAI Documentation

Server mode exposes a selected subset of SoAI tools, resources, and prompts at /mcp over MCP Streamable HTTP. It is not a WebSocket tunnel and does not use SoAI-specific protocol envelopes.

Configure server exposure

In the SoAI WebUI, select the Settings button at the right of the header, then Settings > MCP.
Under MCP configuration, confirm that the MCP runtime and server mode are enabled.
Review Tools exposed by server mode, Resources exposed by server mode, and Prompts exposed by server mode.
Select Save after making a deliberate change.

The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN). Reading runtime status and the Tools, Resources, and Prompts panels also requires MCP usage (MCP_USE). Saving exposure changes requires Configuration changes (CONFIG_PATCH). Server mode is enabled by default, but it exposes a curated list rather than every built-in tool.

This exposure list governs MCP clients only. Chat, agent turns, and automations run against the built-in tool catalog described in Agent tools overview, so narrowing TOOLS.MCP.SERVER_MODE.EXPOSED_TOOLS, or turning server mode off entirely, removes capabilities from connected clients without taking them away from the workspace.

Know the default boundary

The default resource list contains models, plugins, and system_status. Mail and calendar resources require explicit opt-in. The default prompts are system_overview, model_selection, plugin_info, rag_document_summary, rag_topic_extraction, rag_question_answering, and rag_compare_sources.

The 19 tools exposed by default are:

Purpose	Default tool names
Web search and retrieval	`web_fetch`, `web_search_duckduckgo`, `web_search_searxng`, `web_search_brave`, `web_search_tavily`, `web_search_serper`, `web_search_google`
Feeds and conditions	`rss_read`, `news`, `weather`
Utility operations	`calculator`, `datetime_current`, `wait`, `random_generate`, `hash`, `base64`, `text_stats`, `unit_convert`
Hardware inspection	`hardware_snapshot`

The default tool list favors lower-impact read-only and computational capabilities. Shell, server files, browser sessions, linked mail and calendars, credentials, private knowledge, memory, plans, connected MCP resources, automations, subagents, arbitrary HTTP methods, persistent mutations, and resource-intensive media or image work require explicit opt-in. Internal administration tools cannot be exposed through server mode.

The generated Built-in tool reference lists every built-in tool and its exact arguments. Compare that inventory with TOOLS.MCP.SERVER_MODE.EXPOSED_TOOLS when deciding whether to expose anything beyond the defaults above.

Personal skills are available to ordinary SoAI chats. MCP server clients do not inherit an account's library or conversation selection, and skill_read is not part of the public server catalog. Use the client's own instruction mechanism for its workflows.

Create a client token

Open MCP tokens and select Create token.
Enter a Label and choose 90 days or Never.
Copy the secret from the confirmation. SoAI does not display the full value again.
Send it as Authorization: Bearer YOUR_MCP_TOKEN to /mcp.

Creating a token also requires MCP usage (MCP_USE). The MCP tokens panel is on Settings > MCP, which appears only to an Administrator with MCP administration (MCP_ADMIN).

Revoke a token when a client no longer needs access. A server-mode token has no per-tool scopes. Every listed tool is available to that token only when the token owner's MCP usage (MCP_USE), any tool-specific ACL, and the feature's runtime requirements also permit it.

Secure and verify remote clients

Exposed tools run on the SoAI host. Shell execution inherits the SoAI process identity and does not pause for a WebUI approval dialog. Shell tools also require Terminal and shell access (TERMINAL_USE). The TOOLS.MCP.SHELL.COMMAND_BLACKLIST setting can reduce accidental misuse, but it is not a sandbox or security boundary. Keep high-impact exposure on a trusted local-client and local-server boundary.

Configure browser origins only when needed

Server mode has no browser origins configured by default. If a browser-based MCP client runs from another origin, add that exact origin to TOOLS.MCP.SERVER_MODE.ALLOWED_ORIGINS. This is a browser-origin check, not a replacement for TLS, bearer authentication, network isolation, or narrow exposure lists.

Verify a connection

Connect the client to http://127.0.0.1:5090/mcp for a local default installation, or to the private TLS origin followed by /mcp. List tools, resources, and prompts before invoking anything. The client should see only names present in the three exposure lists and permitted by current runtime state.