MCP 服务器

在 Halo 的能力库里接入 MCP 服务器：手动添加或粘贴 JSON 一次导入多个，测试连接、逐个开关工具，并决定哪些工作区和数字人能用。

直接对 Halo 说

从商店装一个 GitHub 的 MCP 服务器。

Halo 会在商店里搜索 MCP 条目，选中后替你安装，装好后新的消息就能用上它的工具。需要令牌的服务器，装好后到它的详情里补上，再测试连接。

前提：在输入框 ＋ › 能力 里打开 操作 Halo。

AI 只能从商店安装 MCP 服务器。用命令或网址接入一个自己的服务器，需要你按下面的步骤手动添加，AI 帮不上。

MCP 是什么

MCP（Model Context Protocol，模型上下文协议）是一种开放标准，让 AI 用统一的方式调用外部程序提供的工具。一个 MCP 服务器就是一个工具提供者，比如查数据库、读写某个系统的工单、调用第三方 API。在 Halo 里接入一个 MCP 服务器，AI 在会话中就能调用它的工具。

名称	是什么	打个比方
MCP 服务器	AI 能调用的一组外部工具	员工手里的工具箱
技能	一套写好的做法和说明，用 `/命令` 或由 AI 自动调用	员工会的一项本事
数字人	有身份、记忆和任务的 AI 同事，会用 MCP 和技能	员工本人

网页搜索、Halo 文档查询、数字人管理这些工具也是以 MCP 的形式内置在 Halo 里的，但它们不是你添加的 MCP 服务器，不会出现在 MCP 连接 里，也不需要你配置。见不用开关就有的工具。

完整的配置字段和格式见 MCP 配置参考。

开始之前

MCP 服务器都在 数字人 › 能力库 › MCP 连接 里管理。2.x 的「我的MCP」（更早的版本叫「我的应用」）入口已经没有了。
命令行（stdio）类的服务器由 Halo 在运行它的那台电脑上启动，命令要先装好。比如 npx 需要 Node.js，uvx 需要 uv。
通过远程访问添加的命令行服务器，同样在运行 Halo 的那台电脑上启动。
Halo 会提示：「MCP 服务器作为系统工具被注入到智能体中。不稳定的 MCP 服务器会影响智能体的可靠性。仅在您知道自己在做什么的情况下继续。」只接入你信任、能稳定运行的服务器。

手动添加一个 MCP 服务器

打开 数字人 › 能力库，切到 MCP 连接，点 手动添加MCP。弹出 添加MCP服务器 窗口，默认是 可视化 模式。
在 安装到 里选范围：全局（所有空间）（默认）或某个工作区。两者的区别见全局还是工作区。
填名称，比如 my-mcp-server。
在 传输方式 里选连接方式（见下表），再填对应字段。
点 创建连接。窗口显示「连接已保存。」和「请单独测试连接。已保存的配置并不能保证任务能够使用它。」
点这个服务器旁边的 测试连接。显示 已连接 就说明 Halo 能连上它。点完成关闭窗口。

传输方式（界面原样）	适合	要填的字段
命令行(stdio)	在本机运行的服务器，最常见	命令（如 `npx`）、参数（每个参数一行，点添加参数加一行）、环境变量
SSE (Server-Sent Events)	通过网址连接的服务器（SSE 协议）	URL、请求头、环境变量
HTTP (Streamable)	通过网址连接的服务器（可流式 HTTP）	URL、请求头、环境变量

环境变量 和 请求头 都按 KEY=VALUE 填，每行一个。API Key 这类密钥通常放在环境变量里，比如 API_KEY=<YOUR_TOKEN>。
网址类服务器的登录令牌放在 请求头 里，例如 Authorization=Bearer <YOUR_TOKEN>。

完成

MCP 连接 里出现这个服务器的卡片，状态写着「已连接 · 5 个工具」这样的字样，就说明接好了。从你的下一条消息起，相应范围内的会话就能用上它的工具，不需要重启 Halo。

粘贴 JSON 一次导入多个

如果你在 Cursor 或 Claude Desktop 里已经配好了 MCP 服务器，可以直接把配置粘贴过来，一次装好好几个。

在 添加MCP服务器 窗口顶部切到 JSON。
在 配置(JSON) 里粘贴配置。外层的 mcpServers 包装可以保留，Halo 会自动处理。
粘贴了多个服务器时，窗口显示「检测到 2 个服务器 — 每个都将以其自己的名称安装。」按钮变成 安装 2 个服务器。点它。
在完成页面逐个点 测试连接。

可以粘贴三种形状：只有一个服务器的配置、{"名称": {...}}，或者完整的 {"mcpServers": {...}}。例如：

json

{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": ["-y", "@example/notes-mcp"],
      "env": { "NOTES_TOKEN": "<YOUR_TOKEN>" }
    },
    "tickets": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

<YOUR_TOKEN> 换成你自己的令牌。网址类服务器要同时写 type（http 或 sse）和 url。每个服务器以它的键名作为名称安装，比如上例的 notes 和 tickets。

在 可视化 和 JSON 之间切换时，已经填好的内容会互相同步。

测试连接和连接状态

测试连接 会真的和服务器握手并读取它的工具列表。它不消耗模型 token，最多等 15 秒。安装、启用和修改配置后，Halo 也会自动测一次。

卡片和详情页上的状态：

状态（界面原样）	意思	怎么办
已连接 · N 个工具	连上了，读到 N 个工具	不用处理
尚未测试	还没测过	点测试连接
连接失败	连不上服务器	见遇到问题
需要登录	服务器拒绝了身份验证	在配置里更新令牌，再测一次
将在下一条消息时重试	服务器连得上，但上一次会话没能用上它	Halo 已经清掉遗留状态，下一条消息会重新接上
MCP 服务器已全局禁用	你在卡片上把它关了	需要时点电源图标重新启用
未安装	数字人声明了它，但这个范围里没有装	安装它，或从数字人的依赖里移除

点卡片打开详情，能看到传输方式、命令或 URL、参数、请求头，以及它提供的工具。还没读到工具时，详情页显示「尚未加载工具 — 请使用「测试连接」获取工具列表。」

单独开关每个工具

一个服务器的工具不一定都要给 AI。打开它的详情，在 此服务器提供的工具 里，每个工具都有自己的开关：

标题旁显示「8 个工具中已启用 5 个」这样的计数。
全部开启 和 全部关闭 一次切换全部工具。
界面说明：「关闭的工具将从每个对话和数字人运行中排除。已打开的对话将从下一条消息开始应用此更改。」

注意

使用 DSH 引擎时，单个工具的开关不生效，界面会提示：「DSH 引擎无法单独排除 MCP 工具：在此处关闭的工具在其对话中仍可用。」想彻底不给某个工具，就禁用整个服务器，或换用其他引擎。引擎的区别见 Agent 引擎。

全局还是工作区：谁能用到

每个 MCP 服务器装在一个范围里，范围决定哪些会话能用到它：

安装到	卡片上的提示	谁能用
全局（所有空间）	「在所有工作区中可用」	每个工作区里的会话
某个工作区	「仅在此工作区中可用：工作区名」	只有这个工作区里的会话

一个工作区里的每个会话，都会拿到所有已启用的全局 MCP 服务器和本工作区的 MCP 服务器，只有你禁用的服务器和关掉的工具除外。你不用在会话里再打开它们。
全局和工作区里有同名的服务器时，工作区的那个优先。从数字人的 MCP 工具 里新建全局连接时，如果本工作区已有同名连接，Halo 会拦下，提示「使用此名称的工作区连接将会覆盖全局连接。请选择其他名称，或使用现有连接。」
数字人的规则不同，界面写着：「对话会继承其工作区的连接，但明确禁用的连接除外。独立任务使用已声明的连接。」见给数字人用 MCP。
添加、修改、启用或禁用之后，已经打开的会话从下一条消息起生效，不需要重启 Halo。

管理已接入的服务器

在 MCP 连接 里可以用「搜索 MCP 服务器或工具」查找，也可以按 作用域（所有工作区、全局或某个工作区）和来源（商店、自定义、内置）筛选。每张卡片上：

测试连接、电源图标（启用 / 禁用）和 重新安装。
更多菜单里有 编辑配置、移动到工作区 和卸载。
有数字人声明了它时，卡片上显示「由 2 个数字人申报」。卸载时会提醒有多少数字人依赖它，它们将无法使用其工具。

MCP 服务器是共享的，改动会影响这个范围里的所有会话和数字人，所以保存修改前 Halo 会问「保存共享资源的更改？」。卸载的服务器进入 已卸载 分组，之后可以从那里重新安装。

在会话里查看能用哪些 MCP

在会话里点「展开工作区资源」，切到 MCP 标签，能看到当前工作区实际生效的 MCP 服务器（全局加本工作区）。这里只能查看，点一行会跳到能力库里它的详情。一个都没有时显示「暂无可用的 MCP 服务器。」资源栏的其他标签见文件与画布。

从商店安装

商店的 MCP 标签可以浏览 MCP 服务器，但在商店页面上装不了：详情里的按钮是灰色的 即将推出，提示「MCP商店安装功能即将推出。请使用“手动添加”来配置MCP服务器。」MCP 连接 空白时的 从市场安装 也是打开这个商店页面。

要从商店装 MCP 服务器，有两种办法：

在数字人里装：打开 数字人 › 我的数字人，选一位数字人，进 能力与设置 › 工具与资源 › MCP 工具，点 浏览MCP商店。在「搜索商店」里找到条目并安装。它会装进这位数字人所在的工作区，并加为这位数字人的依赖。
让 AI 装：在 ＋ › 能力 里打开 操作 Halo，然后说「从商店装一个 GitHub 的 MCP 服务器」。见本页开头的直接对 Halo 说。

说明

公司提供的 Halo 可能限制 MCP 服务器：命中安全策略的命令会被拒绝，提示 This MCP server command is blocked by security policy.；有的版本也不允许从远程客户端安装 MCP 服务器。

商店怎么浏览和更新，见商店。

给数字人用 MCP

数字人用 MCP 服务器分两种情况：

场景	能用哪些 MCP 服务器
和数字人聊天	继承它所在工作区的全部连接，你对这位数字人禁用的除外
数字人独立运行（计划任务、触发器等）	只有它声明的依赖

所以添加连接时界面会提示「数字人需单独启用。」要让数字人在独立运行时用上一个服务器，就把它加为这位数字人的依赖：

打开 数字人 › 我的数字人，选一位数字人，进 能力与设置 › 工具与资源 › MCP 工具。
用 添加依赖 选一个本工作区已装好的服务器；或者用 浏览MCP商店、新建连接、导入 JSON 装一个新的，装好后自动加为依赖。
每个依赖旁都有开关（对此数字人启用 / 对此数字人禁用）。「此开关仅影响此数字人——不会更改 MCP 服务器本身。」
点 测试连接 确认可用。要改服务器本身的配置，点 共享连接设置。

缺少依赖时会有提示：

声明了但这个工作区没装的依赖显示「此依赖已声明但未安装在此工作区中。在安装之前，运行将缺少其工具。」
服务器被全局禁用时，为何禁用？ 会说明这位数字人运行时不会注入它的工具。
依赖不可用时，运行记录可能显示 未启动，并列出原因，比如「notes：未安装」，旁边有 打开工具与资源。

从商店装的数字人可能自带 MCP 依赖。每一项设置的说明见能力与设置。

从 Claude CLI 导入

仅桌面版

已经在 Claude Code CLI 里配过 MCP 服务器，可以直接搬过来：

打开 设置 › 高级 › Claude CLI 集成，在 从 Claude CLI 迁移 MCP 服务器 里点扫描。Halo 读取 ~/.claude.json 里的服务器。
已经在 Halo 里有同名服务器的，标着「已在 Halo 中存在」。这时会保留 Halo 里原来的配置，选覆盖也不会替换。要换成 CLI 里的配置，先在能力库里卸载原来的服务器，再迁移。
点迁移。导入的服务器作为全局连接出现在 MCP 连接 里。
逐个点 测试连接 确认。

配置目录等其他选项见设置参考。

遇到问题

卡片显示「连接失败」

命令行服务器：确认命令在运行 Halo 的电脑上能用，比如用 npx 要先装 Node.js。再检查参数和 环境变量 有没有写错。
网址类服务器：确认 URL 能访问，传输方式 选对了 SSE 还是 HTTP (Streamable)。
改完配置后点 测试连接 再测一次。

卡片显示「需要登录」

服务器拒绝了令牌。详情页提示「MCP 服务器拒绝了身份验证。请在下方配置中更新令牌，然后重试。」在 编辑配置 里更新 请求头 或 环境变量 中的令牌，保存后再测试。

粘贴 JSON 后提示 `command must be a non-empty string`

通常是网址类服务器少写了 type。给它加上 "type": "http" 或 "type": "sse"，和 url 写在一起。

服务器明明已连接，AI 却用不到它的工具

确认会话所在的工作区在这个服务器的范围里，见全局还是工作区。
确认相关工具没有被关掉，见单独开关每个工具。
名称和 Halo 内置工具相同的服务器（比如 web-search）会被内置工具顶替。换一个名称重新添加。
数字人独立运行时，只用它声明的依赖，见给数字人用 MCP。

关掉的工具 AI 还在用

你可能在用 DSH 引擎，它不能单独排除 MCP 工具。禁用整个服务器，或换用其他引擎。

下一步

技能：给 AI 装一套固定做法，有的技能需要先接好对应的 MCP 服务器
能力开关：分清 Halo 自带的能力和你接入的 MCP 服务器
MCP 配置参考：查完整的配置字段、传输方式和数字人的依赖声明

MCP 服务器 ​

MCP 是什么 ​

开始之前 ​

手动添加一个 MCP 服务器 ​

粘贴 JSON 一次导入多个 ​

测试连接和连接状态 ​

单独开关每个工具 ​

全局还是工作区：谁能用到 ​

管理已接入的服务器 ​

在会话里查看能用哪些 MCP ​

从商店安装 ​

给数字人用 MCP ​

从 Claude CLI 导入 ​

遇到问题 ​

卡片显示「连接失败」 ​

卡片显示「需要登录」 ​

粘贴 JSON 后提示 command must be a non-empty string ​

服务器明明已连接，AI 却用不到它的工具 ​

关掉的工具 AI 还在用 ​

下一步 ​