Docker로 MCP 서버를 설정하고 AI 에이전트와 연동하는 방법

Docker MCP Catalog로 서버 연결이 왜 이렇게 간단해졌나요?

Docker MCP Catalog 덕분에 MCP 서버를 클릭 한 번으로 바로 연결할 수 있게 되었습니다. 과거에는 MCP 레지스트리에서 서버를 찾은 뒤 JSON 설정을 일일이 작성해야 했습니다. 여러 서버를 쓰려면 반복 작업이 많았고 API 키 관리도 따로 해야 했습니다.

Catalog가 바꾼 설치 과정

• 인기순으로 정리된 리스트에서 원하는 서버 선택
• 클릭 한 번으로 추가와 API 키 설정까지 동시에 완료
• Docker Desktop과 자동으로 연동되어 별도 JSON 편집 불필요

Docker Desktop 즉시 활용 사례

Docker Desktop만 설치하면 MCP 서버를 클라우드 데스크톱이나 Gemini CLI 같은 클라이언트에 바로 연결할 수 있습니다. 이제 JSON을 직접 만지지 않아도 Catalog가 환경 설정을 자동으로 적용해줍니다.

MCP Gateway를 Docker로 실행해 Python·N8N 에이전트와 연동하는 방법은?

Docker로 MCP Gateway를 실행하면 Python이나 N8N 같은 커스텀 에이전트가 MCP 서버 기능을 HTTP로 바로 호출할 수 있습니다.

Gateway 컨테이너 실행하기

docker/mcp-gateway 이미지를 사용해 8089 포트에서 게이트웨이를 실행합니다. 이 설정 하나로 Docker Catalog에 등록된 모든 MCP 서버가 외부 에이전트에 노출됩니다. 별도의 SDK 설치 없이 HTTP 요청만으로 도구를 호출할 수 있어 코드가 간결해집니다.

N8N과의 연동 방법

N8N에서 MCP 클라이언트를 추가하고 게이트웨이 주소를 입력하면 Slack 채널 목록 조회 같은 MCP 도구를 워크플로우 노드로 바로 사용할 수 있습니다. 게이트웨이 로그를 통해 실시간 연결 상태도 확인 가능합니다.

LiveKit 같은 음성 에이전트에도 동일한 게이트웨이 연결을 적용해 음성 질의로 GitHub 저장소 정보를 바로 받아올 수 있습니다.

Python 에이전트 연동 팁

Python 코드에서는 MCP 툴킷을 통해 게이트웨이에 연결한 뒤, 필요한 MCP 서버를 호출하는 방식으로 에이전트를 구성합니다. 이 구조 덕분에 에이전트 로직은 프롬프트와 추론에 집중하고, 도구 연동은 게이트웨이가 담당합니다.

Docker Compose로 GitHub MCP 서버를 설정하고 AI 에이전트를 만드는 단계는?

Docker Compose 파일 하나로 GitHub MCP Gateway를 실행하고 MCPToolkit을 연결해 GPT-4o 기반 AI 에이전트를 바로 만들 수 있습니다.

docker-compose.yml 작성하기

서비스 정의는 간단합니다. docker/mcp-gateway:latest 이미지를 사용하고 GitHub 서버를 지정한 뒤 8080 포트를 노출합니다.

• —server=github 옵션 추가
• .env 파일로 GitHub 토큰 주입
• 에이전트와 동일 네트워크 연결

이 설정만으로 별도 SDK 설치 없이 GitHub API 호출이 가능해집니다.

GitHub 토큰과 MCPToolkit 연결

토큰을 설정한 후 MCPToolkit을 에이전트 코드에 추가합니다. HTTP로 게이트웨이에 요청을 보내면 파일 목록 조회, 코드 검색 같은 기능이 자동으로 수행됩니다.

게이트웨이가 GitHub 관련 작업을 모두 처리하므로 에이전트는 프롬프트와 추론에만 집중하면 됩니다.

GPT-4o 연동 전체 흐름

에이전트가 질문을 받으면 MCPToolkit을 통해 게이트웨이로 도구 호출을 전달합니다. 검색 결과는 GPT-4o 프롬프트에 포함되어 자연어 답변을 생성합니다.

실제 실행은 docker compose up 한 줄로 끝나며, 로컬·스테이징·프로덕션 환경에서 동일하게 동작합니다.

한 Docker 환경에서 여러 MCP 서버를 동시에 쓰려면 어떻게 해야 하나요?

MCP Catalog에서 여러 서버를 한 번에 선택하고 Gateway를 단일 엔드포인트로 연결하면 Docker 한 환경에서 여러 MCP 서버를 동시에 활용할 수 있습니다. Docker MCP 서버 통합 설치법에 따르면 Catalog 화면에서 유튜브·슬랙·깃허브 등 원하는 서버를 다중 선택하면 자동으로 통합 설정이 적용됩니다. 별도의 JSON 편집 없이도 모든 서버가 하나의 Gateway 주소로 노출되므로 클라이언트 쪽 연동이 단순해집니다.

Catalog 다중 선택으로 시작하기

• Catalog 리스트에서 서버를 체크만 하면 자동 등록
• API 키 설정도 Catalog 내에서 일괄 처리
• 선택한 서버들은 Docker Desktop에서 즉시 활성화

Gateway 단일 엔드포인트의 장점

Gateway가 모든 MCP 서버를 하나의 HTTP 엔드포인트로 묶어주기 때문에 Python이나 N8N 같은 외부 에이전트는 이 주소 하나만 바라보면 됩니다. 서버가 늘어나도 클라이언트 코드를 수정할 필요가 없어집니다.

각 MCP 서버는 독립된 컨테이너로 실행되므로 작업이 끝나면 바로 종료되어 메모리와 보안 부담이 줄어듭니다.

이 방식은 같은 Docker 네트워크 안에서 컨테이너 격리를 유지하면서도 여러 도구를 동시에 호출할 수 있게 해줍니다.

Docker로 AI 에이전트를 구성하는 과정이 생각보다 훨씬 가볍게 느껴지실 거예요. 실제 프로젝트에 바로 적용해 보면서 편한 점을 직접 확인해 보시길 추천합니다. 다음 글에서는 더 다양한 에이전트 연동 사례를 정리해 올게요.

자주 묻는 질문

Docker MCP Catalog에서 지원하는 주요 서버는 어떤 것들이 있나요?

Docker MCP Catalog에서는 유튜브 트랜스크립트, 슬랙, 깃허브, 오브시디언 같은 서버를 클릭 한 번으로 추가할 수 있습니다. Fetch는 50만 다운로드 이상을 기록했고 Notion과 ChromaDB도 지원 목록에 들어 있습니다. Docker Desktop만 설치하면 별도 JSON 편집 없이 바로 연결됩니다.

MCP Gateway를 사용하면 기존 Python 에이전트 코드를 크게 수정해야 하나요?

MCP Gateway를 쓰면 에이전트 코드에 GitHub API 같은 무거운 로직을 직접 넣지 않아도 됩니다. HTTP로 게이트웨이에 연결하기만 하면 기존 Python 에이전트가 MCP 서버를 호출할 수 있습니다. 따라서 코드 수정량이 크게 줄어듭니다.

Docker로 실행한 MCP 서버는 작업이 끝나면 자동으로 종료되나요?

MCP 서버의 각 도구는 Docker 컨테이너로 실행됩니다. 작업이 필요할 때만 컨테이너가 잠시 가동되고, 작업이 끝나면 바로 종료됩니다. 이 방식 덕분에 메모리 사용과 보안 부담을 줄일 수 있습니다.

Docker MCP Toolkit을 쓰면 환경 설정이 팀원마다 달라지는 문제를 해결할 수 있나요?

Docker MCP Toolkit은 컨테이너 이미지에 고정된 종속성을 담고 있습니다. 따라서 팀원마다 설치된 패키지나 경로가 달라지는 일이 사라집니다. docker-compose.yml 하나로 모두 동일한 환경을 유지할 수 있습니다.

참고 자료

• Docker MCP 서버 통합 설치법과 활용법, 2025년 최신 가이드tilnote.io
• Docker MCP 툴킷을 사용하여 AI 에이전트 구축: 개발자의 …kr.linkedin.com
• 같은 Docker 컨테이너 안에서 여러 개의 MCP 서버를 어떻게 …reddit.com