---
title: "MCP 服务器：给 Halo 接入外部工具"
description: "在 Halo 的能力库里接入 MCP 服务器：手动添加或粘贴 JSON 一次导入多个，测试连接、逐个开关工具，并决定哪些工作区和数字人能用。"
type: "how-to"
audience: ["developer", "office"]
related: ["features/skills", "features/capabilities", "developers/mcp"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/features/mcp.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# MCP 服务器

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

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

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

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

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

## MCP 是什么 {#what-is-mcp}

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

| 名称 | 是什么 | 打个比方 |
|---|---|---|
| MCP 服务器 | AI 能调用的一组外部工具 | 员工手里的工具箱 |
| [技能](https://hello-halo.cc/docs/features/skills.html) | 一套写好的做法和说明，用 `/命令` 或由 AI 自动调用 | 员工会的一项本事 |
| [数字人](https://hello-halo.cc/docs/digital-humans/overview.html) | 有身份、记忆和任务的 AI 同事，会用 MCP 和技能 | 员工本人 |

网页搜索、Halo 文档查询、数字人管理这些工具也是以 MCP 的形式内置在 Halo 里的，但它们不是你添加的 MCP 服务器，不会出现在 **MCP 连接** 里，也不需要你配置。见 [不用开关就有的工具](https://hello-halo.cc/docs/features/capabilities.html#built-in-tools)。

完整的配置字段和格式见 [MCP 配置参考](https://hello-halo.cc/docs/developers/mcp.html)。

## 开始之前 {#before-you-start}

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

## 手动添加一个 MCP 服务器 {#add}

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

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

## 粘贴 JSON 一次导入多个 {#import-json}

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

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

可以粘贴三种形状：只有一个服务器的配置、`{"名称": {...}}`，或者完整的 `{"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** 之间切换时，已经填好的内容会互相同步。

## 测试连接和连接状态 {#test}

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

卡片和详情页上的状态：

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

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

## 单独开关每个工具 {#tool-switches}

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

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

::: warning 注意
使用 DSH 引擎时，单个工具的开关不生效，界面会提示：「DSH 引擎无法单独排除 MCP 工具：在此处关闭的工具在其对话中仍可用。」想彻底不给某个工具，就禁用整个服务器，或换用其他引擎。引擎的区别见 [Agent 引擎](https://hello-halo.cc/docs/features/agent-engines.html)。
:::

## 全局还是工作区：谁能用到 {#scope}

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

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

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

### 管理已接入的服务器 {#manage}

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

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

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

### 在会话里查看能用哪些 MCP {#resources-rail}

在会话里点「展开工作区资源」，切到 **MCP** 标签，能看到当前工作区实际生效的 MCP 服务器（全局加本工作区）。这里只能查看，点一行会跳到能力库里它的详情。一个都没有时显示「暂无可用的 MCP 服务器。」资源栏的其他标签见 [文件与画布](https://hello-halo.cc/docs/features/files-and-canvas.html)。

## 从商店安装 {#from-the-store}

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

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

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

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

商店怎么浏览和更新，见 [商店](https://hello-halo.cc/docs/digital-humans/store.html)。

## 给数字人用 MCP {#digital-humans}

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

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

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

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

缺少依赖时会有提示：

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

从商店装的数字人可能自带 MCP 依赖。每一项设置的说明见 [能力与设置](https://hello-halo.cc/docs/digital-humans/capabilities.html)。

## 从 Claude CLI 导入 {#claude-cli}

（仅桌面版）

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

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

配置目录等其他选项见 [设置参考](https://hello-halo.cc/docs/features/settings.html#claude-cli-integration)。

## 遇到问题 {#troubleshooting}

### 卡片显示「连接失败」

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

### 卡片显示「需要登录」

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

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

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

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

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

### 关掉的工具 AI 还在用

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

## 下一步 {#next-steps}

- [技能](https://hello-halo.cc/docs/features/skills.html)：给 AI 装一套固定做法，有的技能需要先接好对应的 MCP 服务器
- [能力开关](https://hello-halo.cc/docs/features/capabilities.html)：分清 Halo 自带的能力和你接入的 MCP 服务器
- [MCP 配置参考](https://hello-halo.cc/docs/developers/mcp.html)：查完整的配置字段、传输方式和数字人的依赖声明