跳转到主要内容
文档扩展生态MCP 集成

MCP 集成

给工作流里的 Agent 挂载任意 MCP Server 作为工具，扩展它能做的事。

MCP（Model Context Protocol）是一个开放协议，用统一的方式把外部工具提供给 LLM。在 Braidrun 里，MCP 挂在 Agent 上：给某个 Agent 配置一个或多个 MCP server，这些 server 暴露的工具就和内置工具一样，出现在该 Agent 可调用的工具列表里。

工作原理

MCP 配置是 Agent 级的：在工作流 YAML 里，每个 Agent 的 mcp_servers 是一个「名字 → 配置」的映射，可以同时挂多个 server。步骤执行前，运行时逐个连接这些 server，把它们的工具并入该 Agent 的工具注册表。

某个 MCP server 连接失败时，运行时记一条警告并跳过它的工具，不会中断整条工作流 —— 其余 server 和内置工具照常可用。如果某个步骤依赖的工具来自没连上的 server，失败会体现在那个步骤的执行日志里。

挂一个本地 stdio server

最常见的形式：MCP server 是一个本地进程，运行时用 command + args 把它启动起来，通过标准输入输出通信。用 preset 声明 Agent 时，mcp_servers 写在 overrides 里：

yaml
agents:
  researcher:
    preset: universal
    overrides:
      mcp_servers:
        github:
          command: npx
          args: ["-y", "@modelcontextprotocol/server-github"]
          env:
            GITHUB_PERSONAL_ACCESS_TOKEN: "<your-token>"
          description: "读写 GitHub 仓库与 issue"
preset 模式下必须放 overrides

Agent 声明了 preset 时，运行时只合并 preset 默认值和 overrides 里的字段；写在 Agent 顶层的 mcp_servers 会被忽略。

连接远程 server

MCP server 也可以是一个网络服务：填 url 就不再走 stdio，type 决定传输方式（sse、websocket、http），不填 type 按 sse 处理。

yaml
agents:
  analyst:
    preset: universal
    overrides:
      mcp_servers:
        crm:
          url: "https://mcp.example.com/sse"
          type: sse
          timeout: 60000
        docs-search:
          url: "https://mcp.example.com/mcp"
          type: http
          enabled: true

url 指向的服务必须能从工作流的运行环境访问到 —— 写公网可达的地址，不要写只在你本机可访问的地址。

字段参考

字段说明
commandstdio 模式的启动命令（可执行文件名或路径）；stdio 模式下必填
args命令行参数列表
env传给 stdio 子进程的环境变量；凭据从这里传
cwdstdio 子进程的工作目录，不填用运行时默认
url远程 server 地址；填了 url 就不再走 stdio
type传输类型：stdio（默认）、sse、websocket、http；只在填了 url 时生效，不填按 sse 处理
timeout超时，单位毫秒，默认 30000
enabled默认 true；设为 false 可以临时停用一个 server 而不删配置
description备注，帮助协作者理解这个 server 是干什么的

凭据与网络注意事项

  • stdio 子进程不会继承运行环境的全部变量：只有 PATH、HOME、LANG 等少量基础变量，加上你在 env 里显式写的内容会传进去。MCP server 需要的 API Key 必须显式写在 env 里。
  • env 的值以明文保存在工作流 YAML 里。分享工作流或发布模板之前，把真实密钥换成占位符，让使用者填自己的。
  • 远程 server 建议用 HTTPS 地址；连接失败按上面说的跳过处理，可以先在执行日志里确认工具是否注册成功。
  • 工具越多，Agent 的决策空间越大。只挂这个 Agent 真正会用到的 server，成功率和速度都会更好。

Braidrun 工具的 MCP 暴露

这条路也是双向的：Braidrun 自身的内置工具打包成了一个 stdio MCP server（名为 braidrun-workflow），同一套工具可以经 MCP 协议提供给其他 MCP 客户端复用。

与 Claude Code / Codex 的关系

在产品内，AI 助手可以选用 Koog、Claude Code 或 Codex 作为运行时，支持订阅登录代替 API Key。运行时切换见 AI 助手文档。

相关页面