Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs(bot): document tools.mcp_servers config (PR #1392) (#1567)

r266-tech5751e389ba77
diff --git a/bot/README.md b/bot/README.md
index c7a9764e3..7fea0c448 100644
--- a/bot/README.md
+++ b/bot/README.md
@@ -222,6 +222,47 @@ Vikingbot provides 7 dedicated OpenViking tools:
| `openviking_glob` | Match OpenViking resources using glob patterns |
| `openviking_memory_commit` | Commit session to ov |
+### External MCP Servers
+
+Vikingbot can also consume tools from third-party [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers (filesystem, GitHub, browsers, databases, etc.). Configure servers under `tools.mcp_servers` in `ov.conf`; each server's tools are registered when the agent starts and appear as `mcp_<server>_<tool>`.
+
+```json
+{
+ "bot": {
+ "tools": {
+ "mcp_servers": {
+ "filesystem": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+ "env": {},
+ "tool_timeout": 30,
+ "enabled_tools": ["*"]
+ },
+ "github": {
+ "type": "streamableHttp",
+ "url": "https://api.githubcopilot.com/mcp/",
+ "headers": {"Authorization": "Bearer $GITHUB_TOKEN"},
+ "enabled_tools": ["search_repositories", "create_issue"]
+ }
+ }
+ }
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `type` | Transport: `stdio` / `sse` / `streamableHttp`. Auto-detected when omitted (`stdio` if `command` is set, otherwise HTTP from `url`). |
+| `command` | (stdio) Command to launch the server process (e.g. `npx`, `uvx`). |
+| `args` | (stdio) Command arguments. |
+| `env` | (stdio) Extra environment variables for the spawned server. |
+| `url` | (sse / streamableHttp) Endpoint URL. |
+| `headers` | (sse / streamableHttp) Custom request headers (e.g. `Authorization`). |
+| `tool_timeout` | Per-call timeout in seconds (default `30`). |
+| `enabled_tools` | Tool allowlist. Accepts raw MCP names or wrapped `mcp_<server>_<tool>` names; `["*"]` exposes every tool. |
+
+> MCP servers are connected when the agent loop starts and closed automatically on shutdown. If a server has neither `command` nor `url`, it is skipped with a warning. Connection failures are logged and the bot continues without that server's tools.
+
### OpenViking Hooks
Vikingbot enables OpenViking hooks by default:
diff --git a/bot/README_CN.md b/bot/README_CN.md
index 928ee86b9..01679ea45 100644
--- a/bot/README_CN.md
+++ b/bot/README_CN.md
@@ -225,6 +225,47 @@ Vikingbot 提供 7 个专用的 OpenViking 工具:
| `openviking_glob` | 使用 glob 模式匹配 OpenViking 资源 |
| `openviking_memory_commit` | 提交session到Openviking|
+### 外部 MCP 服务器
+
+Vikingbot 还可以接入第三方 [MCP(Model Context Protocol)](https://modelcontextprotocol.io/) 服务器的工具(文件系统、GitHub、浏览器、数据库等)。在 `ov.conf` 的 `tools.mcp_servers` 下配置即可,每个服务器的工具会在代理启动时注册,名称前缀为 `mcp_<服务器>_<工具>`。
+
+```json
+{
+ "bot": {
+ "tools": {
+ "mcp_servers": {
+ "filesystem": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+ "env": {},
+ "tool_timeout": 30,
+ "enabled_tools": ["*"]
+ },
+ "github": {
+ "type": "streamableHttp",
+ "url": "https://api.githubcopilot.com/mcp/",
+ "headers": {"Authorization": "Bearer $GITHUB_TOKEN"},
+ "enabled_tools": ["search_repositories", "create_issue"]
+ }
+ }
+ }
+ }
+}
+```
+
+| 字段 | 描述 |
+|------|------|
+| `type` | 传输模式:`stdio` / `sse` / `streamableHttp`。省略时自动探测(有 `command` 走 stdio,否则按 `url` 走 HTTP)。 |
+| `command` | (stdio)启动服务器进程的命令(如 `npx`、`uvx`)。 |
+| `args` | (stdio)命令参数。 |
+| `env` | (stdio)传给服务器进程的额外环境变量。 |
+| `url` | (sse / streamableHttp)接入地址。 |
+| `headers` | (sse / streamableHttp)自定义请求头(如 `Authorization`)。 |
+| `tool_timeout` | 单次工具调用超时(秒),默认 `30`。 |
+| `enabled_tools` | 工具白名单,可使用原始 MCP 名称或包装后的 `mcp_<服务器>_<工具>` 名;`["*"]` 表示全部暴露。 |
+
+> MCP 服务器在代理循环启动时连接,并在关闭时自动清理;若某服务器既没有 `command` 也没有 `url`,则跳过并打印警告。连接失败会记录错误日志,代理会在没有该服务器工具的情况下继续运行。
+
### OpenViking 钩子
Vikingbot 默认启用 OpenViking 钩子: