MCP 카탈로그 도구

MCP 카탈로그 도구 (MCP Catalog Tool)

에이전트가 런타임에 Docker MCP 카탈로그의 서버를 검색·활성화·비활성화하는 방법을 설명해요. 턴이 진행되면서 필요한 서비스를 그때그때 고를 수 있어요.

출처: 문서

본문

mcp_catalog 도구셋은 에이전트에게 Docker MCP 카탈로그의 큐레이션된 하위 집합에 대한 접근을 제공해요 — 이 하위 집합의 모든 서버는 streamable-http 전송으로 도달할 수 있어서, Docker Agent가 MCP 게이트웨이나 로컬 서브프로세스 없이 직접 통신할 수 있어요.

서버는 기본적으로 활성 상태가 아니에요. 대신 도구셋은 에이전트가 턴이 진행되면서 서버를 검색·활성화·비활성화하는 데 쓰는 작은 메타-도구 집합을 노출해요. 활성화되지 않은 서버의 도구는 숨겨져 있어서, 에이전트가 절대 쓰지 않을 수백 개의 도구 정의로 프롬프트가 범람하지 않아요.

참고 언제 쓸까 에이전트가 어떤 타사 서비스(Notion, Stripe, Brave Search 등)가 필요한지 YAML에 미리 박아 두지 않고 런타임에 결정하길 원할 때 mcp_catalog를 사용하세요. 고정된 서버 집합이라면 각각을 type: mcp로 직접 선언하면 됩니다. 카탈로그는 순수 type: mcp 항목에는 필요 없는 메타-도구 계층을 추가해요.

구성

toolsets:
  - type: mcp_catalog

카탈로그는 docker-agent 바이너리에 내장되어 있고 각 릴리스마다 갱신돼요. 기본적으로 내장 subset의 모든 서버가 제공돼요.

제공되는 서버 제한

두 개의 선택적 목록이 도구셋이 제공하는 것을 좁혀서, 에이전트가 전체 카탈로그 대신 집중되고 예측 가능한 메뉴를 보게 해요:

allowed_servers — 비어 있지 않으면 이 카탈로그 서버 id만 검색·활성화 가능하고 다른 모든 항목은 숨겨짐
blocked_servers — 제공 집합에서 개별 id를 제거. allowed_servers 뒤에 적용되므로 둘 다에 있는 서버는 차단(블록이 허용을 이김)

둘 다 search_remote_mcp_servers가 반환하는 id 필드인 서버 id를 받아요. 빈 목록이나 생략된 목록은 그 필터를 비활성화해요.

toolsets:
  - type: mcp_catalog
    allowed_servers:
      - docker-docs
      - microsoft-learn
      - hugging-face
    blocked_servers:
      - gitmcp

메타-도구

최대 다섯 개의 도구가 모델에 노출돼요. disable/reset-auth 쌍은 서버가 하나 이상 활성화된 뒤에만 나타나서, 에이전트가 무언가 활성화하기 전까지 메타-도구 표면을 최소로 유지해요.

도구	표시 시점	설명
`search_remote_mcp_servers`	항상	id, 제목, 설명, 범주, 태그에 대한 대소문자 구분 없는 퍼지 검색. id, 인증 요구사항(`oauth`/`none`), URL 반환
`enable_remote_mcp_server`	항상	id로 서버 활성화. 연결(및 필요한 OAuth 핸드셰이크)이 끝날 때까지 블록; 성공 시 서버 도구가 즉시 라이브가 되고 모델은 같은 턴에서 사용자의 원래 요청으로 계속됨
`list_remote_mcp_servers`	항상	현재 활성화된 서버와 연결 상태 표시
`disable_remote_mcp_server`	첫 활성화 후	서버 중지하고 그 도구를 활성 집합에서 제거
`reset_remote_mcp_server_auth`	첫 활성화 후	저장된 OAuth 자격 증명 제거해서 다음 활성화가 새 인증 흐름을 트리거하게 함. `none` 서버에는 무의미(no-op)

워크플로

에이전트는 사용자 의도와 맞는 키워드로 search_remote_mcp_servers를 호출해요("notion", "stripe", "docs", "browser", "grafana", ...).
일치하는 서버 id를 고르고 enable_remote_mcp_server를 호출해요. enable은 MCP 핸드셰이크(및 필요한 OAuth 흐름)가 끝날 때까지 블록해요: 성공하면 서버 도구가 같은 턴에서 사용 가능 — 에이전트는 재질문 없이 사용자의 원래 요청으로 곧장 진행해요.
실패하면(사용자가 인증 대화상자를 닫거나 서버가 거부), 도구는 특정 이유를 이름 붙인 오류 결과를 반환해서 에이전트가 연결된 척하지 않고 복구할 수 있어요.
새로 활성화된 도구를 다른 것처럼 사용해요.
다 끝나면 disable_remote_mcp_server로 서버를 활성 집합에서 제거해요.

인증

카탈로그는 Docker Agent가 스스로 인증할 수 있는 서버만 포함해요. 그래서 두 가지 인증 형태가 있어요:

oauth — enable_remote_mcp_server가 elicitation 파이프라인(YAML 선언 원격 MCP 도구셋이 쓰는 것과 같은)을 통해 인증 URL을 표시하고, 사용자가 승인하거나 취소할 때까지 블록해요. 사용자가 승인하면 토큰이 OS 키링에 저장되고 이후 실행에서 재사용돼요. 지우려면 reset_remote_mcp_server_auth를 사용하세요. 사용자가 대화상자를 닫으면 enable은 거절을 이름 붙인 오류 결과를 반환해서 에이전트가 재시도할지 물어볼 수 있어요.
none — 인증 없음. 활성화되면 즉시 서버에 도달 가능.

호출자가 제공한 API 키를 요구하는 서버는 의도적으로 카탈로그에서 제외돼요. 그런 서버를 쓰려면 type: mcp로 명시적으로 선언하고 환경 변수로 키를 제공하세요.

예시

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Agent that can on-demand connect to remote MCP servers from the Docker MCP Catalog.
    instruction: |
      You can discover and activate remote MCP servers on demand.
      Use search_remote_mcp_servers to find a server matching the
      user's intent, then enable_remote_mcp_server to activate it.
      Be conservative: enable only the servers you actually need for
      the task at hand. Disable a server with disable_remote_mcp_server
      once you are done with it.
    toolsets:
      - type: mcp_catalog

완전하고 실행 가능한 구성은 examples/mcp_catalog.yaml에 있어요. allow/block-list 변형은 examples/mcp_catalog_filtered.yaml에 있어요.

참고 사항과 한계

Streamable-http 전용. 카탈로그는 로컬 서브프로세스나 MCP 게이트웨이가 필요한 서버를 의도적으로 제외해요 — 그런 것은 type: mcp로 선언하세요.
카탈로그 구성원은 릴리스마다 바뀌어요. 통합이 더해지거나 제거됨에 따라 사용 가능한 서버 집합이 각 Docker Agent 릴리스마다 갱신돼요. 어떤 릴리스에 있는 서버가 다음 릴리스에는 없을 수 있어요.
차단 활성화. DNS, TCP, MCP 핸드셰이크, 어떤 OAuth 흐름도 enable_remote_mcp_server 내부에서 동기적으로 일어나므로 에이전트는 같은 턴에서 결정적인 결과를 얻어요. 다만 시작 시 런타임은 비대화형으로 도구를 검사하고(mcp.WithoutInteractivePrompts), OAuth 대기 서버는 거기서 빨리 실패해서 다음 대화형 턴으로 조용히 연기돼요 — 대화상자가 불가능한 사이드바 전용 도구 수 패스도 포함해요.
프롬프트 발견 없음. MCP 프롬프트 조회(/prompts)는 YAML 선언 mcp 도구셋을 직접 걸어요. 카탈로그를 통해 활성화된 서버가 노출하는 프롬프트는 표시되지 않아요. 도구 — 주요 인터페이스 — 는 잘 동작해요.
빌드 시점에 동결. 서버 목록은 바이너리에 내장돼요. 새 항목은 각 Docker Agent 릴리스와 함께 들어와요.

팁 권한과 함께 쓰세요 에이전트가 어느 타사 서비스와 통신할지 스스로 결정하기 때문에, 이 도구셋은 주변 도구(filesystem 쓰기, shell 커맨드)에 명시적 권한이 있을 때 가장 잘 동작해요. 잘못 라우팅된 서버가 눈치채지 못하게 데이터를 유출하지 못하게요.

더 알아보기 (Learn more)

MCP 도구로 고정 MCP 서버 선언하기
Remote MCP Servers 문서에서 원격 엔드포인트 카탈로그 살펴보기