CLI로 MCP Toolkit 사용하기

docker mcp 명령을 사용하면 터미널에서 MCP 프로필, 서버, OAuth 자격 증명, 카탈로그를 관리할 수 있어요. 스크립트, 자동화, 헤드리스(headless) 환경에서 CLI를 사용하세요.

출처: 문서

본문

가용성: Beta

참고: 여기에 문서화된 docker mcp 명령은 Docker Desktop 4.62 이상에서 사용할 수 있어요. 이전 버전은 여기 보이는 모든 명령을 지원하지 않을 수 있어요.

프로필(Profiles)

프로필 만들기

$ docker mcp profile create --name <profile-id>

프로필 ID는 이후 명령에서 프로필을 참조하는 데 사용돼요:

$ docker mcp profile create --name web-dev

프로필 목록 보기

$ docker mcp profile list

프로필 확인

$ docker mcp profile show <profile-id>

프로필 제거

$ docker mcp profile remove <profile-id>

주의: 프로필을 제거하면 그 프로필의 모든 서버 설정과 세팅이 삭제돼요. 이 작업은 되돌릴 수 없어요.

서버(Servers)

카탈로그 둘러보기

사용 가능한 서버와 그 ID를 나열해요:

$ docker mcp catalog server ls mcp/docker-mcp-catalog

출력에는 각 서버가 이름으로 나열돼요. 이름(예: playwright 또는 github-official)이 catalog:// URI에서 사용할 서버 ID예요.

Docker Desktop에서 서버 ID를 확인하려면 MCP Toolkit > Catalog를 열고, 서버를 선택한 뒤 Server ID 필드를 확인하세요.

프로필에 서버 추가

서버는 URI로 참조돼요. URI 형식은 서버가 어디서 오는지에 따라 달라져요:

형식	출처
`catalog://<catalog-ref>/<server-id>`	OCI 카탈로그
`docker://<image>:<tag>`	Docker 이미지
`https://<url>/v0/servers/<uuid>`	MCP 커뮤니티 레지스트리
`file://<path>`	로컬 YAML 또는 JSON 파일

가장 흔한 형식은 catalog://인데, <catalog-ref>는 Catalog 필드와, <server-id>는 Docker Desktop이나 catalog server ls 출력에 표시된 Server ID 필드와 일치해요:

$ docker mcp profile server add <profile-id> \
--server catalog://<catalog-ref>/<server-id>

한 명령으로 여러 서버를 추가할 수도 있어요:

$ docker mcp profile server add web-dev \
--server catalog://mcp/docker-mcp-catalog/github-official \
--server catalog://mcp/docker-mcp-catalog/playwright

로컬 YAML 파일에 정의된 서버를 추가하려면:

$ docker mcp profile server add my-profile \
--server file://./my-server.yaml

YAML 파일은 서버 이미지와 설정을 정의해요:

name: my-server
title: My Server
type: server
image: myimage:latest
description: Description of the server

서버에 OAuth 인증이 필요하면 추가한 뒤 Docker Desktop에서 승인해 주세요. OAuth 인증 문서를 참고하세요.

서버 목록 보기

모든 프로필의 모든 서버를 나열해요:

$ docker mcp profile server ls

프로필로 필터링:

$ docker mcp profile server ls --filter profile=web-dev

서버 제거

$ docker mcp profile server remove <profile-id> --name <server-name>

한 번에 여러 서버 제거:

$ docker mcp profile server remove web-dev \
--name github-official \
--name playwright

서버 설정 구성

프로필에 있는 서버의 설정 값을 설정하고 조회해요:

$ docker mcp profile config <profile-id> --set <server-id>.<key>=<value>
$ docker mcp profile config <profile-id> --get-all
$ docker mcp profile config <profile-id> --del <server-id>.<key>

서버 설정 키와 그 예상 값은 각 서버가 정의해요. 서버의 문서나 Docker Desktop의 MCP Toolkit > Catalog > Configuration 항목을 확인하세요.

게이트웨이(Gateway)

특정 프로필로 MCP Gateway 실행:

$ docker mcp gateway run --profile <profile-id>

기본 프로필을 사용하려면 --profile을 생략하세요.

클라이언트를 수동으로 연결

Docker Desktop에 나열되지 않은 클라이언트를 연결하려면 stdio로 게이트웨이를 실행하도록 구성해 주세요. 예를 들어 JSON 기반 클라이언트 구성에서는:

{
  "servers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"],
      "type": "stdio"
    }
  }
}

Claude Desktop에서는 형식이 이렇게 돼요:

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"]
    }
  }
}

이름 있는 클라이언트 연결

지원되는 클라이언트를 프로필에 연결해요:

$ docker mcp client connect <client> --profile <profile-id>

예를 들어 VS Code를 프로젝트별 프로필에 연결하려면:

$ docker mcp client connect vscode --profile my-project

이 명령은 현재 디렉터리에 .vscode/mcp.json 파일을 만들어요. 사용자별 파일이므로 .gitignore에 추가해 주세요:

$ echo ".vscode/mcp.json" >> .gitignore

프로필 공유

OCI 레지스트리나 버전 관리를 사용해 팀과 프로필을 공유해요.

OCI 레지스트리로 공유

프로필은 OCI 호환 레지스트리를 통해 OCI 아티팩트로 공유돼요. 보안상의 이유로 자격 증명은 포함되지 않아요. 팀원은 풀(pull)한 뒤 인증 자격 증명을 별도로 구성해요.

web-dev라는 기존 프로필을 OCI 레지스트리에 푸시하려면:

$ docker mcp profile push web-dev registry.example.com/profiles/web-dev:v1

같은 프로필을 풀하려면:

$ docker mcp profile pull registry.example.com/profiles/team-standard:latest

버전 관리로 공유

프로젝트별 프로필은 export와 import 명령을 사용해 코드와 함께 버전 관리에 저장할 수 있어요. 팀원이 파일을 가져오면 같은 설정을 얻을 수 있어요.

프로필을 프로젝트 디렉터리로 내보내려면:

$ mkdir -p .docker
$ docker mcp profile export web-dev .docker/mcp-profile.json

저장소를 클론한 팀원은 프로필을 가져올 수 있어요:

$ docker mcp profile import .docker/mcp-profile.json

이 명령은 파일에 정의된 서버와 설정으로 프로필을 만들어요. 필요한 경우 인증 자격 증명은 별도로 구성해야 해요.

커스텀 카탈로그

커스텀 카탈로그를 사용하면 팀이나 조직을 위한 집중된 서버 모음을 만들 수 있어요. 커스텀 카탈로그가 무엇이고 언제 사용하는지에 대한 개요는 커스텀 카탈로그 문서를 참고해 주세요.

카탈로그는 예를 들어 registry.example.com/mcp/my-catalog:latest 같은 OCI 참조로 참조돼요. 카탈로그 안의 서버는 프로필에 서버를 추가할 때와 같은 URI 체계를 사용해요.

Docker 카탈로그 맞춤화

Docker 카탈로그를 기본으로 삼고, 조직의 요구에 맞게 서버를 추가하거나 제거해요. 먼저 복사해 주세요:

$ docker mcp catalog tag mcp/docker-mcp-catalog \
  registry.example.com/mcp/company-tools:latest

포함된 서버를 나열해요:

$ docker mcp catalog server ls registry.example.com/mcp/company-tools:latest

조직이 승인하지 않는 서버를 제거해요:

$ docker mcp catalog server remove \
  registry.example.com/mcp/company-tools:latest \
  --name <server-name>

Docker 이미지로 패키징된 자체 비공개 서버를 추가해요:

$ docker mcp catalog server add registry.example.com/mcp/company-tools:latest \
  --server docker://registry.example.com/mcp/internal-api:latest \
  --server docker://registry.example.com/mcp/data-pipeline:latest

준비되면 푸시해요:

$ docker mcp catalog push registry.example.com/mcp/company-tools:latest

처음부터 카탈로그 빌드

선택한 것만 정확히 포함하고 싶다면 처음부터 카탈로그를 만들어요. Docker 카탈로그의 서버, 자체 비공개 이미지, 또는 둘 다 포함할 수 있어요.

카탈로그를 만들고 포함할 서버를 지정해요:

$ docker mcp catalog create registry.example.com/mcp/data-tools:latest \
  --title "Data Analysis Tools" \
  --server catalog://mcp/docker-mcp-catalog/sequentialthinking \
  --server catalog://mcp/docker-mcp-catalog/brave \
  --server docker://registry.example.com/mcp/analytics:latest

결과를 확인해요:

$ docker mcp catalog show registry.example.com/mcp/data-tools:latest

배포하려면 푸시해요:

$ docker mcp catalog push registry.example.com/mcp/data-tools:latest

카탈로그 배포

팀원이 가져올 수 있도록 카탈로그를 푸시해요:

$ docker mcp catalog push <oci-reference>

팀원은 CLI로 풀할 수 있어요:

$ docker mcp catalog pull <oci-reference>

또는 Docker Desktop에서 가져올 수 있어요: MCP Toolkit > Catalog > Import catalog를 선택하고 OCI 참조를 입력하세요.

게이트웨이에서 커스텀 카탈로그 사용

기본 Docker 카탈로그 대신 여러분의 카탈로그로 게이트웨이를 실행해요:

$ docker mcp gateway run --catalog <oci-reference>

에이전트가 대화 중에 서버를 탐색하고 추가하는 Dynamic MCP의 경우, 이렇게 하면 에이전트가 찾을 수 있는 것을 여러분이 선별한 집합으로 제한해요.

프로필을 사용하지 않고 카탈로그에서 특정 서버만 활성화하려면:

$ docker mcp gateway run --catalog <oci-reference> \
  --servers <name1> --servers <name2>

CLI로 MCP Toolkit 사용하기