DocsExtensions EcosystemMCP Integration

MCP Integration

Attach any MCP Server as a tool to an Agent in your workflow, extending what it can do.

MCP (Model Context Protocol) is an open protocol for providing external tools to an LLM in a uniform way. In Braidrun, MCP hangs off an Agent: configure one or more MCP servers on an Agent, and the tools those servers expose appear in that Agent's callable tool list, just like built-in tools.

How It Works

MCP config is per-Agent: in the workflow YAML, each Agent's mcp_servers is a "name → config" map, and you can attach multiple servers at once. Before a step runs, the runtime connects to each server in turn and merges their tools into that Agent's tool registry.

When an MCP server fails to connect, the runtime logs a warning and skips its tools without interrupting the whole workflow — the other servers and the built-in tools stay available. If a step depends on a tool from a server that didn't connect, the failure shows up in that step's execution log.

Attach a Local Stdio Server

The most common form: the MCP server is a local process that the runtime launches with command + args and communicates with over standard input/output. When declaring an Agent with a preset, put mcp_servers inside 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"

In preset mode it must go in overrides

When an Agent declares a preset, the runtime only merges the preset defaults and the fields inside overrides; mcp_servers written at the Agent's top level is ignored.

Connect to a Remote Server

An MCP server can also be a network service: set url and it no longer uses stdio, and type decides the transport (sse, websocket, http); if type is omitted it defaults to 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

The service that url points to must be reachable from the workflow's runtime environment — use a publicly reachable address, not one that's only reachable on your own machine.

Field Reference

Field	Description
`command`	The launch command for stdio mode (an executable name or path); required in stdio mode
`args`	The list of command-line arguments
`env`	Environment variables passed to the stdio child process; credentials are passed here
`cwd`	The working directory of the stdio child process; if omitted, the runtime default is used
`url`	The remote server address; once url is set, it no longer uses stdio
`type`	Transport type: stdio (default), sse, websocket, http; only takes effect when url is set, and defaults to sse if omitted
`timeout`	Timeout in milliseconds, default 30000
`enabled`	Defaults to true; set it to false to temporarily disable a server without deleting the config
`description`	A note to help collaborators understand what this server is for

Credential And Network Notes

The stdio child process doesn't inherit all of the runtime environment's variables: only a few basics like PATH, HOME, and LANG, plus whatever you write explicitly in env, get passed through. Any API Key the MCP server needs must be written explicitly in env.
The values in env are stored in plain text in the workflow YAML. Before sharing a workflow or publishing a template, replace real secrets with placeholders and let users fill in their own.
Use HTTPS addresses for remote servers; connection failures are skipped as described above, so you can check the execution log first to confirm whether the tools registered successfully.
The more tools there are, the larger the Agent's decision space. Attach only the servers this Agent actually uses, and both success rate and speed improve.

Exposing Braidrun Tools Over MCP

This path is bidirectional too: Braidrun's own built-in tools are packaged as a stdio MCP server (named braidrun-workflow), so the same tool set can be reused by other MCP clients over the MCP protocol.

Relationship to Claude Code / Codex

In the product, the AI assistant can use Koog, Claude Code, or Codex as its runtime, with subscription login supported in place of an API Key. For switching runtimes, see the AI assistant docs.