连接器与 MCP

选择要连接的服务#

连接器把外部服务接进工作台，让 Agent 在对话里直接调用对方提供的工具。接上 GitHub 就能查看议题与拉取请求，接上团队工具就能查内部数据，接上数据库就能按条件检索。

每个连接器都会带来一组新工具，不需要你写代码。选择时先看服务本身提供哪些能力，再确认这些能力落在你这次授权的范围里。

1. 在当前工作区新建来源目录 ~/.zero-works/workspaces/{工作区目录名}/sources/linear/；也可请 Agent 按下面的完整配置创建来源。
2. 保存 config.json 和说明用途、团队范围及读写约定的 guide.md。slug 必须与来源目录名一致，id 在工作区内唯一。
3. 在桌面完成授权，再请 Agent 调用 source_test({"sourceSlug":"linear"})。这些是会话工具名，不是终端命令或聊天斜杠命令。

为什么用 MCP#

MCP（Model Context Protocol）是一种开放的工具协议。服务按同一套约定发布工具，Agent 就能用统一的方式调用，不必为每个服务单独适配。

它带来的好处是工具语义明确。服务自己定义有哪些操作、每个操作要什么参数，Agent 照着调用即可，出问题时也能定位到具体是哪个工具、哪次调用。

• 接入栈更完整：只要服务提供 MCP 服务，Agent 就能用上它公布的全部能力。
• 可以串起真实流程：从一个服务取数据、加工后写进另一个服务。
• 凭据按来源隔离，每个来源只拿到自己需要的权限。
• 生态在持续扩展，越来越多服务直接提供官方 MCP 服务。

来源配置字段#

MCP 服务以来源的形式配置，字段集中在来源目录的 config.json 里。type 固定为 mcp，其余字段说明服务地址、传输方式与认证方式。

字段含义与来源总览一致，区别在于 MCP 来源额外提供传输方式与服务地址，本地服务则用启动命令与环境变量描述。

{
  "id": "linear-docs-example",
  "name": "Linear",
  "slug": "linear",
  "enabled": true,
  "provider": "linear",
  "type": "mcp",
  "mcp": {
    "transport": "http",
    "url": "https://mcp.linear.app/mcp",
    "authType": "oauth",
    "oauthRelay": false
  }
}

传输方式#

MCP 服务可以跑在网络另一端，也可以跑在你自己的机器上。两种情况对应两种传输方式，配置时选错会直接连不上。

同一台机器上的本地服务与网络另一端的远程服务可以同时接入，互不冲突。配置前先确认运行 Agent 的环境能访问远程地址。

• http 对应 Streamable HTTP；服务明确给出旧 SSE 端点时选择 sse。保留供应商给出的完整路径，不把 /mcp 或 /sse 自行删掉。
• 本地服务常见的启动形态是 npx 加包名、node 跑脚本、python 跑脚本，或直接执行一个可执行文件。
• 从其他工具复制过来的配置通常是 mcpServers 结构，需要转换成来源自己的字段写法。

如何找到 MCP 服务#

MCP 服务主要有三个来源。优先找服务官方提供的实现，它对工具定义和权限边界最清楚，也最跟得上服务本身的变化。

找到地址只是第一步，接入前还要确认它的认证方式与权限范围，以及它实际发布哪些工具，这些都以服务官方说明为准。

• 服务官方文档：不少服务现在直接在自己的开发者文档里给出 MCP 地址。
• 公开的 MCP 服务注册表：可以按用途检索已经发布的实现。
• 团队自建：内部系统或私有数据由团队自己实现并部署一个 MCP 服务。

配置访问权限#

凭据决定 Agent 能碰到哪些数据。申请范围时按最小必要来：这一阶段只需要读，就不要申请写；只需要一个项目，就不要申请整个组织。

凭据保存与连接验证是两步。完成认证后，请求来源校验并核对工具列表；只有一次真实的、范围合适的读取才能确认业务权限。

1. 先保存完整来源配置；在来源详情查看当前工作区、URL、transport 和认证方式。不要把其他客户端的 mcpServers 包装直接作为 config.json。
2. oauth：请 Agent 调用 source_oauth_trigger({"sourceSlug":"linear"})，在桌面打开的浏览器中确认账号和权限，等待应用收到回调。
3. bearer：请 Agent 调用 source_credential_prompt({"sourceSlug":"service","mode":"bearer"})，只在专用输入框填写令牌。
4. 自定义认证头：在 mcp.headerNames 声明名称，用 source_credential_prompt({"sourceSlug":"service","mode":"multi-header","headerNames":["x-api-key"]}) 收集值；不要把 Key 写成静态 mcp.headers。
5. 认证后运行 source_test({"sourceSlug":"linear"})，查看返回的工具名称和数量，然后先做一条只读请求。

认证方式#

MCP 来源用 authType 声明认证方式。选对之后，凭据的存放位置、填写方式和有效期判断都会随之确定。

认证方式决定凭据的存放位置，也决定它失效时会发生什么。静态令牌失效后需要重新填写，授权类凭据则通常可以在服务方后台单独撤销。

• HTTP/SSE 的 bearer、OAuth 和自定义认证头由凭据库注入；不要把真实令牌放入 guide.md、聊天或截图。
• stdio 的 authType: none 只表示没有 MCP 网络认证；进程访问 Brave 或 GitHub 等服务时仍要自己的环境变量。凭据提示不会自动把库里的值映射到 mcp.env。
• mcp.env 是直接传给进程的字符串配置，不解析 ${VAR}、${env:VAR} 或 {{secret}} 插值。可让进程继承已正确设置的宿主环境，或明确填写进程所需环境；后者在 config.json 中是明文。

确认工具就绪后再使用#

source_test 会校验配置、检查认证并尝试 MCP 握手和工具发现；查看工具名称与数量是否符合预期，不能只看地址能打开。

测试通过默认启用来源并尝试把它激活到当前会话；支持即时激活的后端会重启当前轮以加载工具。需要只检查时传 autoEnable: false。

1. 查看来源状态，确认它已启用并且发现了工具。
2. 在对话里先发一个范围清楚的只读请求。
3. 核对返回内容和工具过程，再决定是否允许创建或修改外部内容。

添加自己的 MCP 服务#

官方条目之外的服务要自己按来源接入。填写之前先确认服务地址、认证要求和本地命令的来源，再动手配置。

自己建的来源和官方服务走的是同一套配置与校验流程。填好之后先看工具是否被发现，再决定要不要在对话里交给 Agent 使用。

1. 下面是完整 GitHub 本地 stdio 示例。先安装并启动 Docker，创建可访问目标仓库的 PAT，并把令牌放入 GITHUB_PERSONAL_ACCESS_TOKEN 对应进程环境。
2. 在当前工作区 sources/github/ 下保存示例为 config.json，补 guide.md，说明仓库范围及只读优先约定。示例 env 留空以继承宿主环境；它不是自动读取凭据库。
3. 让 Agent 调用 source_test({"sourceSlug":"github"})。确认返回预期 GitHub 工具，再查询一个允许访问的仓库。

{
  "id": "github-docs-example",
  "name": "GitHub",
  "slug": "github",
  "enabled": true,
  "provider": "github",
  "type": "mcp",
  "mcp": {
    "transport": "stdio",
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "GITHUB_PERSONAL_ACCESS_TOKEN",
      "ghcr.io/github/github-mcp-server"
    ],
    "env": {},
    "authType": "none"
  }
}

连接多个服务#

一个工作区里可以同时接入多个 MCP 来源。每个来源的工具会带上自己的来源名前缀，Agent 调用时能分辨清楚是哪一路数据。

同时接入多个服务时，先确认它们之间不会互相覆盖工具名。建议按用途区分命名，例如「检索」「工单」「文档」，而不是按加入顺序编号。

• 工具名前缀能帮助 Agent 判断该用哪一路来源。
• 来源越多，每轮可选工具越多，响应也会变慢。
• 不同来源的凭据各自独立，删除其中一个不会影响其他来源。

刷新连接#

服务升级、工具增删或权限改变后，请重新运行来源测试并检查工具列表。配置文件的监听和运行后端决定当前会话能否即时重建连接。

先使用 source_test 的默认激活路径；若返回「重启会话以加载工具」提示，按提示开始新一轮或重新打开会话，不假定界面一定有同名刷新按钮。

1. 请 Agent 调用 source_test({"sourceSlug":"github"})；纯检查使用 {"sourceSlug":"github","autoEnable":false}。
2. 阅读连接、认证、工具名称与激活结果；配置校验通过但运行后端没有连接测试能力时，按返回提示实际调用只读工具验证。
3. 认证失效时重新授权；命令或 env 改动后确保本地进程已重建，再核对一次工具。

凭据管理与作用域#

来源目录与凭据记录按工作区及来源标识区分；来源不会因同名就自动在其他工作区启用。

HTTP 认证令牌保存在独立凭据库。检查来源状态可以确认是否已认证、是否需要重新登录；不能把 isAuthenticated: true 手工写入配置来代替认证。

如果把两个来源指向同一个外部账号或同一个本地记忆文件，外部数据仍然共享。工作区隔离的是来源记录，不会自动隔离外部服务的数据。

• 停用来源会移除可用工具，但不等于撤销服务方授权。
• 需要撤销访问时在来源中清理凭据，并在服务方撤销令牌或应用授权。
• 修改标识、迁移工作区或设备后重新确认凭据归属与测试状态。

安全注意事项#

接入一个外部服务，等于把一部分决策权交给它发布的工具。范围和权限就是安全边界，值得在接入前想清楚。

外部内容一旦进入上下文，就有可能被当作指令来读。涉及外部返回结果的任务，先用只读请求取回内容，再决定如何处理，比直接放权更稳妥。

• 只申请当前需要的权限范围，读写分离，能只读就只读。
• 不要把真实凭据贴进对话、技能文件或截图。
• 本地 stdio 服务会执行你配置的启动命令，只用来源可信、你能审阅的实现。
• 外部内容属于不可信输入，Agent 读取后再转述时要留意其中夹带的指令。
• 来源被停用后，对话中不再有它的工具，但凭据仍然存在，需要时记得清理。

排障#

连接器的问题基本集中在四类：连不上、认证不通过、工具不出现、本地服务起不来。按下面的顺序排查，能最快缩小范围。

排查时保留现场信息很有用：来源状态、报错原文、失败时间点，这三项能让重复出现的故障更快收敛到同一个原因上。

• 连接失败：核对完整端点、http/sse 选择、代理和运行 Agent 那台机器的网络；普通浏览器 GET 不能证明 MCP 握手通过。
• OAuth discovery 失败：检查服务是否发布受保护资源/授权服务元数据及客户端注册能力。只有授权服务网页、没有 MCP OAuth 元数据时，不能靠把 authType 改为 oauth 连接。
• redirect_uri_mismatch：检查浏览器授权 URL 中实际 redirect_uri 与应用注册一致。桌面源授权从 localhost:6477/callback 起选择空闲端口，最多尝试至 6576；以本次值为准，不照抄旧 8914 端口或 Craft 托管回调。
• 浏览器已同意但应用等候：保持发起授权的桌面窗口和本机回调监听，检查本机防火墙、代理是否改写 localhost、授权是否超时或 state 不匹配；取消后重启一轮，不重复复用旧回调。
• OAuth relay is not available：当前托管中继未提供。使用允许 loopback 的桌面流程；不能把远程 WebUI 或 Slack 的托管回调描述为已接通。
• 401/403：检查当前账号、令牌期限及服务授权范围；确认凭据库实际存有该来源的令牌或所需 headerNames，重新提示凭据后再测。
• stdio 启动失败：在实际运行机器检查 command 的绝对路径、PATH、Node/Python/Docker、参数和 env。stdout 混入日志、冷安装超时及远端 API Key 缺失是不同故障。
• 工具缺失：保存后重跑 source_test 并读激活结果，检查供应商工具筛选和工作区本地 MCP 开关，再按后端提示重开会话。