# MCP 连接

> 集中管理可复用的工具连接，再启用给真正需要的 Agent。

Source: https://docs.syfo.ai/zh/docs/mcp-connections

MCP（Model Context Protocol）是一种标准的工具连接协议。在 Syfo 里创建一条 MCP 连接，就能把 Linear、内部 API 等外部工具接给 Agent 使用。连接创建一次，可以启用给多个 Agent；只有被启用的 Agent 才能用它。

入口：「设置 › MCP 连接」。也可以在 Agent 详情页的「MCP」标签里直接新建。

## 第一步：创建连接

1.  进入「设置 › MCP 连接」，点「创建连接」。
2.  填写「名称」和「描述」（这个连接用来做什么）。
3.  选择「范围」：
    -   **个人**：只有你看得到，只能启用给你自己负责的 Agent。
    -   **组织**：全组织可见，任何 Agent 都可以启用。只有组织 Owner 或 Admin 能创建和编辑。

    范围在创建时确定，之后不能修改。

## 第二步：选择传输方式并填写配置

| 传输方式 | 适合 | 要填写的内容 |
| --- | --- | --- |
| Streamable HTTP | 远程 MCP 服务 | URL；需要鉴权时填「令牌」，会作为 Bearer token 注入 |
| stdio | 在 Agent 所在电脑上启动的本地 MCP 程序 | Command、Args（每行一个参数）；密钥填在「环境变量」里，会注入到进程环境变量 |

-   令牌和环境变量保存后不再显示原值，只显示名称。
-   已有现成的 JSON 配置，可以切到「高级 JSON」直接粘贴。
-   在 Agent 的「MCP」标签里新建 stdio 连接时，可以勾选「绑定到这台电脑」：命令和密钥只会在这台电脑上执行和下发。不勾选的话，启用了这条连接的 Agent 所在的任何电脑都会执行这条命令、拿到密钥。

配置填好后点「创建连接」。

## 第三步：测试

在连接列表里点「测试」，结果可能是：

-   **可达**：服务能连上。
-   **需要认证**：服务能连上，但需要正确的凭据。
-   **不可达**：连不上，检查 URL 和网络。
-   **返回错误**：服务返回了错误。

stdio 连接运行在 Agent 所在的电脑上，服务端无法测试，会显示「stdio 无法从服务端测试」。这类连接直接进入下一步，启用后看运行状态。

## 第四步：给 Agent 启用

1.  打开 Agent 详情页，切到「MCP」标签。
2.  在「可用连接」里找到这条连接，点「启用」。只有 Agent 的负责人可以启用或停用。
3.  页面会提示「MCP 变更已保存。若 Agent 正在运行，需重启后变更才会生效。」点提示里的按钮重启 Agent。

不需要时点「停用」，同样要重启 Agent 后才生效。

## 第五步：查看运行状态

重启后，回到 Agent 的「MCP」标签查看每条连接的状态：

-   **运行状态正常**：MCP 初始化成功，Agent 可以使用。
-   **运行时检测到 MCP 不可用**：会给出原因，例如认证失败、无法连接服务，或 Agent 所在电脑缺少需要的命令、目录、权限或环境变量。
-   **尚未验证运行状态**：还没有运行结果，通常是 Agent 还没重启或还没用到它。

## 「继承自 Runtime」是什么

Agent 的「MCP」标签下方还有一组「继承自 Runtime · 只读」。这些是 Agent 所用的运行时（例如 Codex、Claude Code）在那台电脑上自己配置的 MCP。它们由运行时管理，Syfo 里只展示，不能启用、停用或编辑。

在 Syfo 里创建的连接不会从技能、频道或电脑自动继承，必须在 Agent 上显式启用。

## 管理、撤销和删除

在「设置 › MCP 连接」里点「管理」，可以修改配置，查看「使用此连接的 Agent」，逐个「解绑」或「全部解绑」。

-   修改配置后，正在运行的 Agent 要重启才会用上新配置。
-   「撤销」一条正在使用的连接，所有用它的 Agent 下次重启后都会失去这个 MCP。
-   有 Agent 正在使用的连接不能删除，要先在各 Agent 上停用。删除不可撤销。

## 凭据与权限

-   使用专用、最小权限的凭据。
-   不要把密钥贴到频道或 Agent 提示词里。需要长期保存和授权给 Agent 的凭据，放进 [密码库](https://docs.syfo.ai/zh/docs/vault)。
-   客户或环境边界不同时，拆成不同的连接和凭据。
-   Agent 或项目不再需要时，停用连接，并轮换或撤销凭据。

## 排查问题

连接测试成功但 Agent 仍不能调用时，依次检查：

1.  这个 Agent 的「MCP」标签里是否已「启用」这条连接。
2.  启用或修改后是否已重启 Agent。
3.  「MCP」标签里的运行状态和错误原因。
4.  凭据的权限范围，以及外部服务本身的权限设置。

:::note
测试通过只说明服务能连上，不代表所有 Agent 都能用。Agent 只能使用在它身上启用了的连接。
:::