주요 콘텐츠로 건너뛰기
문서확장 생태계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커맨드라인 인자 목록
envstdio 하위 프로세스에 전달하는 환경 변수. 자격 증명은 여기에서 전달
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 어시스턴트 문서를 참고하십시오.

관련 페이지