MCP 도구

MCP 도구 (MCP Tool)

에이전트를 어떤 MCP 서버에도 연결하는 방법을 설명해요. Docker MCP, 로컬 stdio, 원격 Streamable HTTP/SSE 세 가지 형태를 지원해요.

출처: 문서

본문

mcp 도구셋은 에이전트를 어떤 MCP 서버 — Model Context Protocol 위에서 도구, 리소스, 프롬프트를 노출하는 프로세스나 원격 서비스 — 에 연결해요. 세 가지 형태를 지원해요:

형태	전송	용도
Docker MCP	MCP Gateway를 통한 컨테이너	Docker MCP 카탈로그의 큐레이션·샌드박스 서버
로컬 stdio	stdin/stdout 위의 서브프로세스	바이너리나 npx/pip 패키지에서 실행하는 커스텀·커뮤니티 MCP 서버
원격	Streamable HTTP 또는 SSE	호스팅 MCP 엔드포인트를 가진 클라우드 서비스(Linear, Notion, Atlassian 등)

참고 MCP가 뭔가요? Model Context Protocol은 AI 도구 연결을 위한 오픈 표준이에요. Docker Agent는 MCP 서버를 사용할 수 있고(이 페이지) 에이전트를 MCP 서버로 노출할 수도 있어요 — MCP Mode 문서 참고.

Docker MCP (권장)

MCP 서버를 MCP Gateway를 통해 안전한 Docker 컨테이너로 실행해요. ref: docker: 문법이 Docker MCP 카탈로그에서 큐레이션 정의를 가져와요:

toolsets:
  - type: mcp
    ref: docker:duckduckgo        # 웹 검색
  - type: mcp
    ref: docker:github-official   # GitHub 통합
    tools: ["list_issues", "create_issue"]

사용 가능한 서버는 Docker MCP 카탈로그에서 찾아보세요.

속성	타입	설명
ref	string	Docker MCP 참조(docker:name) 또는 재사용 가능한 mcps: 블록의 이름
tools	array	선택적 허용 목록 — 이 도구만 모델에 노출
instruction	string	에이전트의 컨텍스트에 주입되는 커스텀 지침
config	any	초기화 중 전달되는 MCP 서버별 구성
working_dir	string	MCP 게이트웨이 서브프로세스의 작업 디렉터리. 카탈로그 항목이 로컬 프로세스로(원격이 아닌) 실행될 때만 적용. 상대 경로는 에이전트의 작업 디렉터리 기준으로 해석. ${env.VAR}(표준) 및 ~, 셸 스타일 $VAR/${VAR} 확장 지원

로컬 MCP (stdio)

MCP 서버를 stdin/stdout으로 통신하는 로컬 프로세스로 실행:

toolsets:
  - type: mcp
    command: python
    args: ["-m", "mcp_server"]
    tools: ["search", "fetch"]
    env:
      API_KEY: value

속성	타입	설명
command	string	MCP 서버를 실행하는 커맨드
args	array	커맨드 인수
tools	array	선택적 허용 목록 — 이 도구만 노출
env	object	환경 변수(키-값 쌍)
working_dir	string	MCP 서버 프로세스의 작업 디렉터리. 상대 경로는 에이전트 작업 디렉터리 기준. 생략하면 에이전트 작업 디렉터리 기본값. ${env.VAR}(표준) 및 ~, 셸 스타일 $VAR/${VAR} 확장 지원
instruction	string	에이전트 컨텍스트에 주입되는 커스텀 지침
version	string	커맨드 바이너리 자동 설치용 패키지 참조

팁 자동 설치 command가 PATH에 없으면 Docker Agent가 aqua 레지스트리에서 찾아 설치해 줘요. 빠지려면 version: "false"를 쓰거나 전역으로 DOCKER_AGENT_AUTO_INSTALL=false를 설정하세요. Auto-Installing Tools 참고.

원격 MCP (Streamable HTTP / SSE)

네트워크를 통해 MCP 서버에 연결해요. OAuth 흐름(동적 클라이언트 등록 포함)은 자동으로 처리돼요 — Docker Agent는 인증이 필요하면 브라우저를 열고 이후 세션을 위해 토큰을 캐시해요. 토큰이 만료되거나 서버 측에서 취소되면 조용히 갱신되고, 조용한 갱신이 불가능하면 다음 메시지에서 OAuth 프롬프트가 다시 나타나요.

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.linear.app/mcp"
      transport_type: "streamable"               # 레거시 서버는 "sse"
      headers:
        Authorization: "Bearer ${env.LINEAR_TOKEN}"
    # 선택: OAuth 헬퍼 요청이 사설/내부 IP에 닿게 허용
    allow_private_ips: false
    tools: ["search_issues", "create_issue"]

속성	타입	설명
remote.url	string	MCP 서버의 기본 URL
remote.transport_type	string	streamable 또는 sse
remote.headers	object	모든 요청에 보내는 HTTP 헤더. 값은 요청별로 해석되는 ${env.VAR}와 ${headers.NAME} 자리표시자를 지원. Remote MCP Servers 참고
remote.oauth	object	DCR을 지원하지 않는 서버용 명시적 OAuth 클라이언트 자격 증명. Remote MCP Servers 참고
allow_private_ips	boolean	원격 MCP OAuth 헬퍼 요청이 비공개 IP 주소로 다이얼링을 허용. 신뢰하는 내부 서버에만 사용

큐레이션된 공개 원격 MCP 엔드포인트 목록(Linear, GitHub, Vercel, Notion 등)과 전체 OAuth 구성 세부사항은 Remote MCP Servers 문서를 참고하세요.

MCP 프롬프트

MCP 서버는 프롬프트 — 서버가 /prompts 엔드포인트로 제공하는 명명된 파라미터화 템플릿 — 를 노출할 수 있어요. Docker Agent는 도구셋 시작 시에 이를 발견하고 TUI에서 슬래시 커맨드로 등록해서, 입력 박스에서 직접 호출할 수 있어요.

# /를 입력하면 내장 커맨드와 함께 사용 가능한 프롬프트 표시
/review         # "review"라는 MCP 프롬프트 호출
/summarize My text here   # 첫 번째 인수를 채워 호출

동작 방식:

• 각 MCP 프롬프트는 MCP Prompts 범주 아래 명령 팔레트(Ctrl+K로 접근)에 나타나요.
• 입력 박스에 /를 입력하면 프롬프트를 즉시 호출해요.
• 프롬프트가 인수를 선언하고 슬래시 커맨드 뒤에 텍스트를 제공하면, 그 텍스트는 첫 번째 선언 인수에 매핑돼요.
• 필수 인수가 없으면 Docker Agent가 프롬프트를 실행하기 전에 인수 입력 대화상자를 열어요.
• 인수가 필요 없거나 모든 필수 인수가 공급되면 프롬프트가 즉시 실행돼요.

참고 MCP 프롬프트 발견은 YAML에서 선언된 mcp 도구셋이 필요해요. Docker MCP 카탈로그(ref: docker:)로 활성화된 서버의 프롬프트는 현재 표시되지 않아요.

내장 리소스 (Embedded Resources)

MCP 도구 결과는 내장 리소스 — 도구 응답에 직접 반환되는 이미지, PDF, 텍스트 파일 — 를 포함할 수 있어요. Docker Agent는 이를 첨부로 보존하고 네이티브 콘텐츠 블록으로 모델에 전달해요:

• Anthropic — 이미지는 tool_result의 이미지 블록이 되고, PDF와 기타 문서는 문서 블록이 돼요.
• OpenAI — 이미지는 input_image 데이터 URI로, PDF는 input_file 데이터 URI로 도구 결과 콘텐츠에 전달돼요.
• Bedrock과 Gemini — 동등한 프로바이더 네이티브 표현을 받아요.

구성이 필요 없어요. MCP 서버가 텍스트 출력과 함께 내장 리소스를 반환하면, 리소스가 자동으로 첨부되어 다음 턴에 모델로 보내져요. 차트를 만들거나 PDF를 내보내거나 응답의 일부로 바이너리 데이터를 반환하는 MCP 서버에 유용해요.

재사용 가능한 정의 (mcps:)

반복적인 MCP 서버 구성은 최상위 mcps: 섹션으로 끌어올리고 {type: mcp, ref: }로 이름을 참조할 수 있어요:

mcps:
  github:
    remote:
      url: https://api.githubcopilot.com/mcp
      transport_type: sse
  playwright:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-playwright"]

agents:
  root:
    model: openai/gpt-5
    toolsets:
      - type: mcp
        ref: github
      - type: mcp
        ref: playwright

전체 참조는 Reusable MCP Servers 문서를 참고하세요.

공통 옵션

이 속성들은 형태와 무관하게 모든 MCP 도구셋에 적용돼요:

도구 필터링

toolsets:
  - type: mcp
    ref: docker:github-official
    tools: ["list_issues", "create_issue", "get_pull_request"]

도구를 허용 목록으로 만들면 모델 정확도가 올라가요 — 선택지가 적을수록 혼란이 적으니까요.

지연 로딩

도구가 실제로 호출될 때까지 도구셋의 시작 비용을 건너뛰어요:

toolsets:
  - type: mcp
    ref: docker:github-official
    defer: true
  # 또는 도구셋 내 특정 도구를 지연:
  - type: mcp
    ref: docker:slack
    defer: ["list_channels", "search_messages"]

커스텀 지침

toolsets:
  - type: mcp
    ref: docker:github-official
    instruction: |
      Use these tools to manage GitHub issues.
      Always check for existing issues before creating new ones.
      Label new issues with 'triage' by default.

TOON 인코딩 출력

장황한 JSON 출력을 컴팩트한 TOON 형식으로 다시 인코딩해 컨텍스트 예산을 아껴요. 목록/검색 도구에서 보통 30–60% 더 작은 페이로드를 만들어요.

toon은 도구 이름과 매칭되는 정규식 문자열이에요. 이름이 패턴과 일치하는 도구는 JSON 출력이 모델에 보이기 전에 TOON으로 투명하게 다시 인코딩돼요. 재인코딩은 스키마 장황함을 줄여서, 모델이 크거나 반복적인 도구 출력으로 어려움을 겪을 때 특히 유용해요.

toolsets:
  - type: mcp
    ref: docker:github-official
    toon: ".*"            # 이 서버의 모든 도구를 toonify
  - type: mcp
    command: my-server
    toon: "list_.*,get_.*" # list_/get_ 도구만 toonify

값은 쉼표로 구분된 정규식 목록(또는 단일 정규식)이에요. 도구 이름은 재인코딩되려면 적어도 하나의 패턴과 일치해야 해요. toon: ".*"를 설정하면 그 도구셋의 모든 도구를 재인코딩해요.

GitHub MCP 서버를 쓰는 실용 예시는 examples/github-toon.yaml을 참고하세요.

도구셋별 모델 라우팅

이 도구셋의 도구 결과를 다른(보통 더 저렴하고/빠른) 모델로 처리해요. 오버라이드는 일회성이에요 — 이후 턴은 에이전트의 기본 모델로 돌아가요:

toolsets:
  - type: mcp
    ref: docker:github-official
    model: openai/gpt-4o-mini

Per-Toolset Model Routing 문서 참고.

생명주기 (자동 재시작, 프로파일)

로컬 stdio와 원격 MCP 서버는 감독돼요: 충돌한 서버는 지수 백오프로 자동 재연결돼요. 원격 MCP 서버(Streamable HTTP / SSE)는 유휴/정리 연결 종료 후에도 재연결돼요 — Notion과 Linear 같은 서비스는 주기적으로 유휴 연결을 닫는데, Docker Agent가 투명하게 재연결해요. lifecycle 블록으로 정책을 조정하세요:

toolsets:
  - type: mcp
    ref: docker:duckduckgo
    lifecycle:
      profile: resilient   # 기본; 백오프로 자동 재시작
  - type: mcp
    command: docker
    args: ["mcp", "gateway"]
    lifecycle:
      profile: strict      # fail-fast: 필수, 재시도 없음

모든 프로파일과 조정 손잡이는 Toolset Lifecycle 문서를, TUI에서 재연결을 강제하는 /toolset-restart를 참고하세요.

결합 예시

mcps:
  github:
    remote:
      url: https://api.githubcopilot.com/mcp
      transport_type: sse

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Full-featured developer assistant
    instruction: You are an expert developer.
    toolsets:
      # Docker MCP 카탈로그 항목
      - type: mcp
        ref: docker:duckduckgo

      # 최상위 mcps: 블록의 재사용 가능한 정의
      - type: mcp
        ref: github
        tools: ["list_issues", "create_issue"]
        toon: "list_.*"

      # 자동 설치가 있는 로컬 stdio 서버
      - type: mcp
        command: gopls
        version: "golang/[email protected]"
        args: ["mcp"]

      # OAuth가 있는 원격 MCP (자동 처리)
      - type: mcp
        remote:
          url: "https://mcp.linear.app/mcp"
          transport_type: "streamable"
        instruction: Use Linear for issue tracking.

경고 도구셋 순서가 중요해요 여러 도구셋이 같은 이름의 도구를 제공하면 첫 번째가 우선해요. 나중 도구셋의 중복은 무시되고 경고가 두 도구셋을 식별해요. 도구셋을 의도적으로 정렬하세요. 두 도구를 모두 호출 가능하게 하려면 MCP 도구셋에 고유한 name:을 주거나(그러면 그 도구가 <name>_<tool>로 노출돼요) tools: 필터로 겹치는 도구셋을 제한하세요.

더 보기

• Tool Configuration — 모든 도구셋 유형의 전체 참조와 공유 옵션(lifecycle, TOON, 모델 라우팅 등)
• Reusable MCP Servers — 최상위 mcps: 블록
• Remote MCP Servers — 공개 원격 MCP 엔드포인트 카탈로그 + OAuth 레시피
• MCP Mode — 에이전트를 Claude Desktop, Claude Code 등에 MCP 도구로 노출
• Auto-Installing Tools — MCP 서버 바이너리 자동 설치

더 알아보기 (Learn more)

• MCP 카탈로그 도구로 런타임에 서버 검색·활성화하기
• LSP 도구로 코드 인텔리전스 얻기