MCP Configuration
MCP (Model Context Protocol) enables MaiBot to connect with external tools, transforming it from "just chatting" to "both speaking and acting" — checking weather, searching news, reading files, calling APIs, and more, all within reach. All of the configuration lives under the [mcp] section of bot_config.toml, covered below in the order "master switch → client capabilities → server list".
💡 Understand the Concepts First
If you are not yet familiar with what MCP is, start with Configuration Structure and Server Configuration.
Managing MCP Services in the WebUI
The visual entry point for MCP services is the 插件扩展 (Plugin Extensions) page: sidebar "扩展集成 (Extensions) → 插件扩展 (Plugin Extensions)". Above the plugin list there is an extra MCP 服务 (MCP Services) section (a sky-blue dot plus the service count); click any service or "管理服务" (Manage services) in the top-right corner to open the MCP settings.
- Each service is one row showing its name, transport, connection state (connected / not connected / connection error / disabled), and tool count, with the state refreshing every 5 seconds
- The top of the page searches by name and transport; with no services configured it prompts "尚未添加 MCP 服务，点击『管理服务』连接更多工具" (No MCP services yet, click "Manage services" to connect more tools)
- On the MCP settings page, click "返回插件扩展" (Back to plugin extensions) in the top-left corner to return to the plugin list; unsaved changes are confirmed first
- The standalone sidebar MCP 设置 entry from before 1.3.1 is gone, and the old address
/mcp-settingsredirects to the plugin extensions page; the MCP service group is not shown on the "适配器设置" (Adapter Settings) path - The MCP service list's description reads "连接本地或远程工具服务，保存后即可供麦麦调用" (Connect local or remote tool services; they become available to MaiBot after saving)
This page edits the same [mcp] configuration, whose fields are covered below; saving the file rebuilds the MCP connections automatically — no restart needed.
Configuration Structure Overview
MCP configuration is located under the [mcp] section in bot_config.toml, divided into three levels:
[mcp]
enable = true # Master switch
[mcp.client] # Client host capabilities
client_name = "MaiBot"
client_version = "1.0.0"
[mcp.client.roots] # Roots capability (exposing local paths to the server)
enable = false
[mcp.client.sampling] # Sampling capability (allowing the server to call your model)
enable = false
task_name = "planner"
[mcp.client.elicitation] # Elicitation capability (allowing the server to request users to fill out forms)
enable = false
allow_form = true
allow_url = false
[[mcp.servers]] # MCP server list (multiple allowed)
name = "my-server"
enabled = true
transport = "stdio"
command = "uvx"
args = ["some-mcp-server"]
env = { }
url = ""
headers = { }
http_timeout_seconds = 30.0
read_timeout_seconds = 300.0
[mcp.servers.authorization]
mode = "none"
bearer_token = ""Master Switch
enable— Whether to enable MCP. When set tofalse, no MCP servers will be connected. Enabled by default.
Client Capabilities
This section configures MaiBot's capabilities when acting as an MCP client, declaring them to the server.
Basic Information
[mcp.client]
client_name = "MaiBot"
client_version = "1.0.0"Generally, no changes are needed unless you want the MCP server to see a different client identifier.
client_name— The client implementation name. Default:"MaiBot"client_version— The client implementation version. Default:"1.0.0"
Roots Capabilities
Roots allow you to expose local file system paths to the MCP server, enabling the server to read and write files within those paths.
[mcp.client.roots]
enable = true
[[mcp.client.roots.items]]
enabled = true
uri = "file:///home/mai/data"
name = "MaiMai's Data Directory"enable— Whether to expose Roots capabilities to the MCP server. Default: disableditems— The list of Roots. Default: empty
Each Root item:
enabled— Whether to enable. Default: enableduri— The Root URI, typically afile://path. Required when enabled. Default: emptyname— The display name. Default: empty
💡 What are Roots used for?
If connected to a file system MCP server (e.g., @modelcontextprotocol/server-filesystem), enabling Roots allows the server to know where your data directory is, thereby reading and writing files within that directory.
Sampling Capabilities
Sampling allows the MCP server to request MaiBot to call a large language model in reverse to complete certain tasks. This is an advanced bidirectional capability.
[mcp.client.sampling]
enable = true
task_name = "planner"
include_context_support = false
tool_support = trueenable— Whether to enable the Sampling capability declaration. Default: disabledtask_name— The main program model task name used when executing Sampling requests. Default:"planner"include_context_support— Whether to declare support forincludeContextsemantics other thannone. Default: disabledtool_support— Whether to declare support for continuing to use tools within Sampling. Default: disabled
⚠️ Sampling consumes Tokens
Enabling Sampling means the MCP server can trigger MaiBot's model calls, incurring additional API costs. Ensure task_name points to a configured model task.
Elicitation Capabilities
Elicitation allows the MCP server to request users to fill out forms or open URLs in a browser.
[mcp.client.elicitation]
enable = true
allow_form = true
allow_url = falseenable— Whether to enable the Elicitation capability declaration. Default: disabledallow_form— Whether to allow form-mode Elicitation. Default: enabledallow_url— Whether to allow URL-mode Elicitation. Default: disabled
At least one mode (allow_form or allow_url) must be allowed when enabled.
Server Configuration
This is the most commonly used section — configure the MCP servers you want to connect to. Multiple servers can be configured, with each [[mcp.servers]] block corresponding to one server.
Common Fields
[[mcp.servers]]
name = "playwright"
enabled = true
transport = "stdio" # or "streamable_http", "sse"
http_timeout_seconds = 30.0
read_timeout_seconds = 300.0name— Required. Server name, must be unique within the same configuration. Defaults to empty.enabled— Whether to enable the current server. Defaults to enabled.transport— Transport method,"stdio"(default),"streamable_http","sse"http_timeout_seconds— HTTP request timeout (seconds). Defaults to 30.0read_timeout_seconds— Session read timeout (seconds). Defaults to 300.0
stdio Mode
Runs the MCP server by launching a local subprocess, suitable for locally installed tools. Key fields:
command— Startup command, such asuvx,npx,pythonargs— List of command argumentsenv— Additional environment variables
Running via uvx (Recommended)
uvx is a runner tool included with uv that automatically manages dependencies:
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"][[mcp.servers]]
name = "mcp-sse"
transport = "stdio"
command = "uvx"
args = ["mcp-sse-server", "--port", "8080"]Running via npx
Node.js must be installed first:
[[mcp.servers]]
name = "github"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token_here" }[[mcp.servers]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]Running via Python
[[mcp.servers]]
name = "my-python-mcp"
transport = "stdio"
command = "python"
args = ["-m", "my_mcp_server"]
env = { PYTHONUNBUFFERED = "1" }streamable_http Mode
Connects to remote MCP services (HTTP endpoints), suitable for cloud services or tools deployed by others. Key fields:
url— MCP endpoint address, requiredheaders— Additional HTTP request headersauthorization— HTTP authentication configuration
Remote Service Without Authentication
[[mcp.servers]]
name = "public-weather-mcp"
transport = "streamable_http"
url = "https://mcp.example.com/weather"
[mcp.servers.authorization]
mode = "none"Remote Service With Bearer Token
[[mcp.servers]]
name = "private-api-mcp"
transport = "streamable_http"
url = "https://api.example.com/mcp"
headers = { "X-Custom-Header" = "custom-value" }
[mcp.servers.authorization]
mode = "bearer"
bearer_token = "sk-your-bearer-token"Remote Service With Custom Request Headers
[[mcp.servers]]
name = "enterprise-mcp"
transport = "streamable_http"
url = "https://internal.example.com/mcp/v1"
headers = {
"X-API-Key" = "your-api-key",
"X-Tenant-ID" = "tenant-001",
}Complete Example
Basic Configuration: Connect to a Single Service
[mcp]
enable = true
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"]This is the simplest configuration — just one line enable = true plus a single service, with everything else using default values.
Daily Use Configuration: Two Services + Basic Capabilities
[mcp]
enable = true
[mcp.client]
client_name = "MaiBot"
client_version = "1.0.0"
# Connect to Playwright (browser automation)
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"]
# Connect to the filesystem server
[[mcp.servers]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]Advanced Configuration: Enable Sampling + Roots
[mcp]
enable = true
[mcp.client]
client_name = "MaiBot"
client_version = "1.0.0"
[mcp.client.roots]
enable = true
[[mcp.client.roots.items]]
enabled = true
uri = "file:///home/mai/data"
name = "Data Directory"
[mcp.client.sampling]
enable = true
task_name = "planner"
tool_support = true
# Local service
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"]
# Remote service
[[mcp.servers]]
name = "weather-api"
transport = "streamable_http"
url = "https://mcp.example.com/weather"Tool Naming and Conflicts
MaiBot hands MCP tools to the model under their original names — there is no server prefix, so read_file from the filesystem server is simply read_file. Name conflicts are resolved in three layers, and every layer only logs a warning instead of failing:
- Built-in reserved names — a tool whose name collides with a MaiBot built-in is skipped entirely; the reserved names are
reply,no_action,stop,create_table,list_tables,view_table - Between servers — when several servers expose the same tool name, the one configured first wins and later duplicates are skipped
- Against plugin tools — the final aggregation deduplicates in the order "built-in tools → plugin tools → MCP tools", so on a name clash the plugin tool wins and the MCP tool is completely invisible to the model
When a conflict happens the console prints warnings such as 与内置工具冲突, 与 <server> 冲突 or 检测到重复工具名, which tell you which layer blocked it. To be sure a tool stays available, rename it on the server side, or verify that no plugin has claimed the name.
Only tools are discovered in the current release
MCP Prompts and Resources are not discovered in the current release — their counters in the console stay at 0. Only Tools are actually available.
Frequently Asked Questions
Q: Configuration changes are not taking effect?
MCP connections are rebuilt automatically after you save — no restart needed. The rebuild result is logged exactly as it is at startup:
✓ MCP server 'playwright' connected (Tools 12 / Prompts 0 / Resources 0 / Templates 0)If the connection fails, a warning log will appear:
⚠️ MCP server 'playwright' connection failed: ...Q: How many services can be configured?
There is no hard limit, but each service consumes resources. It is recommended to configure only the services you actually need.
Q: How to find MCP services online?
- Search for projects under the
modelcontextprotocolorganization on GitHub - Search for
@modelcontextprotocolpackages on npm - The Python community has server implementations within the
mcpecosystem
Q: How to choose between stdio, streamable_http, and sse?
- stdio: Locally installed tools with low latency and no network requirement. Suitable for file operations, local computations, etc.
- streamable_http: Remote HTTP services requiring network access. Suitable for cloud APIs and services deployed by others.
- sse: Remote SSE (Server-Sent Events) services, suitable for scenarios requiring server-side event pushing.
Q: Where to obtain the API Token?
It depends on the service you are connecting to. For GitHub MCP, go to GitHub Settings → Developer settings → Personal access tokens to generate one. For other third-party services, obtain the token from the management console of the respective service.
Next Steps
- Duplicate tool names, or fewer tools than expected → Tool Naming and Conflicts
- To view all configuration options → Bot Configuration
- To change configuration in the browser → Configuration Management; for the WebUI Settings and Plugin Extensions entry points see Login & Settings