# 外部工具（MCP）

> 连接 MCP 服务器，让角色接上外部服务和数据：本机和远程服务器、登录授权、面板、长任务，以及哪个角色能用哪个。

\*\*外部工具（MCP）\*\*是空间连接 [Model Context Protocol](https://modelcontextprotocol.io) 服务器的地方：这些程序和服务给 Agent 带来内置工具之外的工具、数据和面板。这一页负责定义每个连接；哪些 Agent 用它，由角色的 **MCP 服务器**设置决定。

从\*\*团队与工具 › 外部工具（MCP）\*\*打开。页面标题是 **MCP 服务器**，编辑页里它的标签是 **MCP**。

## 添加服务器 [#添加服务器]

选**添加服务器**。表单**连接至自定义 MCP** 第一项是**名称**：这是服务器的 ID，角色靠它引用，所以保存后不能再改。显示名称可以不填。接着选 The One 怎么连到它。

**STDIO** 在这台电脑上运行一个程序：

* **启动命令**和**参数**，比如一条以 `npx` 开头的命令。
* **环境变量**：交给这个程序的值；**环境变量传递**：它要从应用自己的环境里拿到的变量。
* **工作目录**。不填的话，服务器会在应用的数据目录里拿到一个自己的文件夹，临时文件不会散落到你的项目里。

STDIO 服务器以你这个系统用户的权限运行：它能读写文件、访问网络、启动别的程序。页面上会标出**完全本地访问**；环境变量的设置只决定它拿到哪些值，并不是沙箱。

用 `npx` 或 `node` 启动的服务器，不需要你装 Node：电脑上有 Node 就用电脑上的，没有就用 The One 自带的。在 Mac 上，即使从程序坞打开应用，用 Homebrew、nvm 或 Volta 装的命令也找得到。

**流式 HTTP** 连到网络上的服务器：

* 服务器的 **URL**。
* **标头**，比如服务要求的 API Key；以及**来自环境变量的标头**。**Bearer 令牌环境变量**写的是存着 Bearer 令牌的那个环境变量的名字。
* **OAuth 2.1 / PKCE**：用于要你登录的服务器（见下文）。

保存时，The One 会自动发现这个服务器的工具；发现失败的话，服务器照样保存下来，可以稍后再试。列表里每一行写着它的连接方式、工具数量（展开就能看到每个工具），以及**发现工具**：比如服务器有了变化，用它重新列一遍。**原文**显示服务器的配置文件，像是密钥的值会被遮住。

![MCP 服务器页面](https://the-zeroth.com/docs-assets/images/0.5/zh/mcp-servers.png)

## 登录服务器（OAuth） [#登录服务器oauth]

远程服务器要求登录时，勾选 **OAuth 2.1 / PKCE**（“启用浏览器授权、发现、刷新和动态客户端注册”）。通常只要勾这一项：The One 会自己找到服务器的登录设置，并向它登记自己。

* **OAuth 客户端 ID**：只有服务给了你一个，或者登录停下来要你填时，才需要填。
* **OAuth 权限范围（scope）**：只有服务要求特定的权限范围时才填。
* **凭据库 ID**：几个空间填同一个 ID，就共用一次登录。
* **OAuth 本机回调地址（loopback redirect URI）**：登录完成后回到哪里，默认是 `http://127.0.0.1:33418/callback`，服务另有要求时才改。

保存服务器时，或者之后点**发现工具**时，它的登录页会在你的浏览器里打开。拿到的令牌存在系统的钥匙串里，从不写进空间。

Agent 的调用从来不会自己弹出登录。已保存的登录失效时，Agent 会收到说明，自己换条路，或者来问你；你在这里对这个服务器点**发现工具**，重新登录即可。

![启用 OAuth 登录的流式 HTTP 服务器](https://the-zeroth.com/docs-assets/images/0.5/zh/mcp-oauth.png)

## 把服务器交给角色 [#把服务器交给角色]

角色编辑页的**能力 › MCP 服务器**决定它的 Agent 用哪些服务器：选**全部**就是空间里的每个服务器，包括以后新加的，新加的从 Agent 的下一轮起就能用；选**自选**就逐个挑（[角色](./roles)）。Agent 在干活时，也可以把空间里的某个服务器加给自己。

在官方空间和你从它复制出来的空间里，主助手和通用工作组的助手拿到全部服务器，所以你新加的服务器，它们从下一轮起就能用。团队里的角色只拿各自活儿需要的服务器。

## Agent 怎么用 MCP 工具 [#agent-怎么用-mcp-工具]

* 为了让每次请求保持精简，Agent 一开始只看到 MCP 工具的名字。它用 `search_tools` 查找工具，用 `load_tool` 载入某个工具的完整描述和参数，从下一轮起就能调用。
* 除了工具，Agent 还能列出和读取服务器的资源（Resources），使用它的提示词（Prompts）。
* 服务器可以在一次调用做完之前提问，比如请 Agent 确认一个选项。Agent 会把这个问题当作调用结果收到，然后回答。
* 工具卡片会按服务器给的提示，把每次调用标成**只读**、**会改东西**或**会碰外部**。这些提示只是说明，不会因此拦下或询问任何调用。Agent 一起发出的只读调用会同时进行。
* 每一次调用都记在**设置 › 数据和撤销 › 行动记录**里，被调用改动的文件可以在那里放回（[行动记录、撤回和急停](../action-log)）。

## 长调用和重启 [#长调用和重启]

支持 MCP 2026-07-28 版本的服务器，可以把一次很长的调用（比如渲染、回测）变成任务。Agent 照常等它完成，或者让它在后台跑；服务器报来的进度会显示在这次调用的工具卡片上，也会显示在事项的剧场里。

如果这期间应用重启了，The One 会向服务器要同一个任务的结果，而不是把工具再调一次。不是任务的调用，或者服务器已经不认识这个任务时，只有服务器标明工具是只读的、或者重复调用无害，才会再调一次；否则 Agent 会被告知结果不明，因为这件事可能做了，也可能没做。

## 面板（MCP Apps） [#面板mcp-apps]

工具可以带一个面板：由它的服务器提供的一个小应用页面。面板显示在对话里这次工具调用的下方。最新的三个会自动载入，更早的点一下才载入；每个都可以收起、重新载入、全屏，或者钉到右侧栏。

你和 Agent 在面板里看的是同一个东西。面板可以调用它自己服务器的工具，告诉 Agent 面板上现在是什么，或者把你写的话转给 Agent。你在面板里做的事，会以你的名义记进行动记录，和 Agent 的调用一样可以撤回。

面板是隔离的：碰不到应用本身、你的文件和应用的令牌，联网也只能连它的服务器声明过的地址。主助手或工作组还可以把面板钉到事项的看板上，成为一张**面板**卡片（[事项与看板](../matters)）。

## 协议版本 [#协议版本]

两代 MCP 服务器 The One 都能连，而且会自己分辨：2026-07-28 版本的服务器不需要握手，也没有会话；更早的版本（2024-11-05 到 2025-11-25）要先握手。更老的 HTTP+SSE 传输方式不支持。STDIO 服务器在两次调用之间一直运行着，所以会保存状态的服务器，状态也会留着。

## 官方空间里的服务器 [#官方空间里的服务器]

官方空间自带一个服务器，**Chrome DevTools**：在你电脑上装的 Google Chrome 里做浏览器自动化。Agent 可以打开和跳转网页，以文字快照或截图的方式读页面，点击和填写表单，查看控制台和网络请求。它的程序包随 The One 一起提供，不需要 Node，也不用另外下载。每次运行都有自己的浏览器配置，一个工作组不会动到另一个工作组的网页。

官方空间里会用浏览器的十个角色都用它：软件团队的方案负责人和开发者、前端工作室的三个角色、Blender 的导演和评审、深度网页研究员，以及产品评测的总监和模拟用户。

控制桌面和其他应用不是空间里的服务器，而是**Computer Use** 插件。

## 插件里的 MCP 服务器 [#插件里的-mcp-服务器]

很多工具以插件的形式提供，插件里带着一个 MCP 服务器，比如 Blender Control、OneCanvas、Gmail Control 和 Computer Use。装好插件，把它加给角色就行：服务器怎么启动由签了名的插件决定，密钥来自插件自己的设置，这一页上什么都不用填。**浏览插件**会打开插件库（[插件与应用](./plugins)）。

一个工具需要代码、设置或密钥，换个空间又得重新配一遍时，优先用插件。只属于这一个空间的服务器，留在这一页上就好。

## 密钥和分享 [#密钥和分享]

服务器的设置是空间里 `mcp_servers` 文件夹下的一个文件。导出或分享空间时，这些文件里可能是密钥的值会被去掉，拿到空间的人要填上自己的。登录拿到的令牌从不离开你的钥匙串。见[定义空间](./definition-spaces)。

官方空间是只读的：要添加服务器，先复制一份。

Source: https://the-zeroth.com/zh/docs/the-one-app/capabilities/mcp