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:
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"The above writing method most intuitively expresses "overriding the preset default configuration". The current saving process will also normalize the mcp_servers at the top of the Agent into preset overrides. However, do not declare the same configuration in two places to avoid difficulty in determining which one takes effect during subsequent editing.
Connect to a Remote Server
MCP server can also be a network service: fill in the url and you will not go to stdio. The type determines the transmission method (sse, websocket, http). Remote Config recommends always filling in type explicitly; missing or unrecognized values currently fall back to SSE and log a warning.
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: trueThe 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 | Transmission type: stdio (local process), sse, websocket, http; please fill in the remote mode explicitly |
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
- A stdio child process does not inherit the whole environment: the platform clears it, lets through a small base allowlist (PATH, HOME, USER, SHELL, PWD, TMPDIR, LANG / LC_*, TZ — about a dozen names), and then layers on whatever you put in env. So an API key the MCP server needs must be written into env explicitly; if it also depends on some other system variable — a custom CA certificate path, say — either add that to env too or ask an administrator to extend the allowlist on the deployment side.
- 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.
Both routes can connect to external services, but the guarantees are different: for third-party authorization, the platform provides field specifications, application guidelines, verification upon saving, and account echo. The key is encrypted and stored and does not enter YAML; the authentication of MCP is arranged by you in the env, and the clear text is left in the workflow definition. For services already in the list, third-party authorization will be given priority.
Exposing Braidrun Tools Over MCP
This street runs both ways: the workflow engine ships its own stdio MCP server that exposes the built-in tools by group, so other MCP clients can reuse exactly the same toolset.
braidrun-workflow mcp-server --tool-group file_system,shell,git
braidrun-workflow list-tools- the server is named braidrun-workflow and talks over standard input/output;
- --tool-group picks which groups to expose (repeatable, aliased --tools); omit it or pass all to expose everything, and run list-tools to see the group names;
- the groups cover file system, shell, web and browser, PDF and Office documents, databases, email, IM, Git, image processing, data transformation, RAG retrieval and local knowledge memory, among others;
- environment variables tighten the boundary further: an allowlist of tool names, a per-minute call ceiling and a maximum input size per call.
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.