DocumentoEcosistema de extensiónIntegración MCP

Integración MCP

Adjunte cualquier MCP Server como herramienta al Agent del workflow para ampliar lo que puede hacer.

MCP (Model Context Protocol) es un protocolo abierto que ofrece herramientas externas al LLM de forma unificada. En Braidrun, MCP se acopla al Agent: al configurar uno o varios MCP server para un Agent, las herramientas que esos server exponen aparecen, igual que las integradas, en la lista de herramientas que ese Agent puede invocar.

Cómo funciona

La configuración de MCP es a nivel de Agent: en el YAML del workflow, mcp_servers de cada Agent es un mapeo «nombre → configuración» y se pueden acoplar varios server a la vez. Antes de ejecutar el paso, en tiempo de ejecución se conecta a estos server uno a uno y se incorporan sus herramientas al registro de herramientas de ese Agent.

Cuando falla la conexión con algún MCP server, en tiempo de ejecución se registra una advertencia y se omiten sus herramientas, sin interrumpir todo el workflow — el resto de server y las herramientas integradas siguen disponibles. Si algún paso depende de una herramienta de un server que no se conectó, el fallo aparece en el registro de ejecución de ese paso.

Acoplar un server stdio local

La forma más habitual: el MCP server es un proceso local que, en tiempo de ejecución, se arranca con command + args y se comunica por entrada/salida estándar. Al declarar el Agent con un preset, mcp_servers se escribe dentro de 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"

En modo preset debe ir en overrides

Cuando un Agent declara un preset, en tiempo de ejecución solo se fusionan los valores por defecto del preset y los campos de overrides; los mcp_servers escritos en el nivel superior del Agent se ignoran.

Conectar un server remoto

El MCP server también puede ser un servicio de red: si se rellena url, deja de usar stdio, y type determina el modo de transporte (sse, websocket, http); si no se rellena type, se trata como 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

El servicio al que apunta url debe ser accesible desde el entorno de ejecución del workflow — escriba una dirección accesible desde Internet, no una dirección accesible solo desde su propia máquina.

Referencia de campos

campo	Descripción
`command`	Comando de arranque del modo stdio (nombre o ruta del ejecutable); obligatorio en modo stdio
`args`	Lista de argumentos de línea de comandos
`env`	Variables de entorno que se pasan al subproceso stdio; las credenciales se pasan por aquí
`cwd`	Directorio de trabajo del subproceso stdio; si no se rellena, se usa el valor por defecto del runtime
`url`	Dirección del server remoto; si se rellena url, deja de usar stdio
`type`	Tipo de transporte: stdio (por defecto), sse, websocket, http; solo surte efecto si se ha rellenado url; si no se rellena, se trata como sse
`timeout`	Timeout, en milisegundos; por defecto 30000
`enabled`	Por defecto true; ponerlo a false permite desactivar temporalmente un server sin borrar su configuración
`description`	Nota, ayuda a los colaboradores a entender para qué sirve este server

Consideraciones sobre credenciales y red

El subproceso stdio no hereda todas las variables del entorno de ejecución: solo unas pocas variables básicas como PATH, HOME, LANG, más lo que usted escriba explícitamente en env. La API Key que necesite el MCP server debe escribirse explícitamente en env.
El valor de env se guarda en texto plano en el YAML del workflow. Antes de compartir un workflow o publicar una plantilla, sustituya las claves reales por marcadores de posición y deje que quien lo use ponga las suyas.
Para los server remotos se recomienda una dirección HTTPS; en caso de fallo de conexión se omite como se ha descrito arriba, y puede confirmar primero en el registro de ejecución si las herramientas se registraron con éxito.
Cuantas más herramientas, mayor es el espacio de decisión del Agent. Acople solo los server que este Agent vaya a usar realmente; así mejoran tanto la tasa de éxito como la velocidad.

Exposición de las herramientas de Braidrun por MCP

Este camino también es bidireccional: las propias herramientas integradas de Braidrun se empaquetan como un MCP server stdio (llamado braidrun-workflow), y ese mismo conjunto de herramientas se puede ofrecer, mediante el protocolo MCP, para su reutilización por otros clientes MCP.

Relación con Claude Code / Codex

Dentro del producto, el asistente de IA puede usar Koog, Claude Code o Codex como runtime, con soporte para inicio de sesión por suscripción en lugar de API Key. El cambio de runtime se explica en la documentación del asistente de IA.