合从文档中心

Appearance

接入 MCP 服务 ​

已经有一个 MCP 服务的话，粘贴一段配置就能把里面的工具全部接进来，不用一个个配。

开始之前 ​

  • 只支持远程 MCP 服务，通过 HTTP 访问。stdio 方式（本地进程）不支持——配置里带 command 字段会被直接拒绝。
  • 服务地址必须公网可访问，内网地址和私有网段一律被拒。
  • 认证只能通过请求头携带，不支持 OAuth 授权流程。
  • 需要工作台的 AI 管理权限。

要接的只有一两个接口时，HTTP API 工具更直接，不必为此搭一个 MCP 服务。

支持的传输方式 ​

传输支持
Streamable HTTP（协议版本 2025-11-25）✅
HTTP + SSE（2024-11-05）✅
stdio❌

不指定传输方式时会自动判断：地址以 /sse 结尾按 SSE 处理，否则先尝试 Streamable HTTP，不通再回退 SSE。

接入 ​

  1. 在左侧栏选择 AI Agent > 工具，选择 添加自定义工具 > MCP 服务。

  2. 把 MCP 配置 JSON 粘进输入框。

    接入 MCP 服务页面，粘贴配置 JSON 后识别

  3. 选择 识别。系统会连接服务、拉取工具清单并展示出来。

  4. 确认无误后保存。

配置格式 ​

顶层键支持 mcpServers（主流写法）和 servers（VS Code 写法）两种，配置内容 5000 字符以内。

json
{
  "mcpServers": {
    "order-service": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <你的令牌>"
      }
    }
  }
}
字段必填说明
url✅服务地址，团队内不可重复
headers❌每次请求都会带上，认证信息放这里
type❌sse 或 streamable-http，不填则自动判断
command—存在即拒绝（stdio 不支持）

配置里有多个服务时只取第一个

mcpServers 下写了多个服务，系统只会接入第一个，其余被忽略且不会提示。一次配一个服务，多个服务分多次添加。

接入之后 ​

服务里的每个工具会成为工具列表中的独立一项，可以单独绑定到不同机器人。工具的名称和参数定义直接沿用服务返回的内容。

到机器人详情页的 工具 卡片上选择 管理，绑定需要的工具即可。单个机器人最多绑 10 个自定义工具，整个团队最多 20 个。

返回内容的处理 ​

机器人只读取返回内容里的文本部分（type: "text"）。图片、音频等其他类型会被丢弃。

限制值
单次调用超时10 秒
响应体上限1 MB
传给机器人的结果上限1000 字符

超过 1000 字符的部分机器人看不到

和 HTTP 工具一样，结果序列化后超过 1000 字符会被静默截断。机器人会基于不完整的数据回答客户，而对话上看不出异常。

让工具只返回必要字段，列表类结果限制条数。

返回 isError: true 时视为调用失败，失败信息会交给机器人，由它决定怎么应对。不会自动重试。

已知限制 ​

工具清单不能增量刷新

工具清单只在添加服务时拉取一次。之后服务端新增、删除或修改了工具，合从这边不会同步。

要更新，只能删除整个服务再重新添加——而删除前必须先把该服务下所有工具从各个机器人上解绑。把这一点纳入你的发布流程考虑。

其他：

  • 服务下任一工具正在被机器人使用时，无法删除该服务。
  • 工具名与团队内已有工具重名时，添加会失败。
  • 服务连不上、或拉取到 0 个工具时，添加会失败并给出原因。

常见错误 ​

提示原因怎么办
配置 JSON 格式错误JSON 语法不合法用格式化工具校验一遍
无法识别的配置格式顶层没有 mcpServers 或 servers按上面的示例调整结构
不支持 stdio 方式配置里有 command 字段改用远程 HTTP 服务
缺少服务地址没填 url补上
地址已存在这个地址已经接入过先删除原有服务
地址不允许访问内网地址或私有网段换成公网可访问的地址
连接服务失败服务不可达、握手失败或认证被拒检查地址可达性与 headers 里的凭据
未发现可用工具服务返回了空的工具清单确认服务端已正确注册工具

下一步 ​