MCP 모드

MCP 모드 (MCP Mode)

Docker Agent 에이전트를 MCP 도구로 노출해서 Claude Desktop, Claude Code 및 기타 MCP 호환 애플리케이션에서 사용해요.

출처: 문서

본문

왜 MCP 모드인가? (Why MCP Mode?)

docker agent serve mcp 명령은 Model Context Protocol을 지원하는 어떤 애플리케이션에서든 에이전트를 사용 가능하게 해요. 즉 다음을 할 수 있어요:

• Claude Desktop이나 Claude Code에서 직접 커스텀 에이전트 사용
• 서로 다른 애플리케이션 간에 특화 에이전트 공유
• 어떤 MCP 클라이언트에서든 소비 가능한 재사용 에이전트 팀 구축
• 기존 워크플로에 도메인 특화 에이전트 통합

Note MCP란 무엇인가? (What is MCP?) Model Context Protocol은 AI 도구를 연결하기 위한 개방형 표준이에요. 클라우드 서비스 연결은 Remote MCP Servers도 참고하세요.

기본 사용법 (Basic Usage)

# Expose a local config (stdio transport, the default)
$ docker agent serve mcp ./agent.yaml

# Expose from a registry
$ docker agent serve mcp myorg/agent:tag

# Set the working directory
$ docker agent serve mcp ./agent.yaml --working-dir /path/to/project

전송 (Transports)

기본적으로 serve mcp 는 stdio 전송을 사용해요 — 서버를 하위 프로세스로 생성하는 클라이언트(Claude Desktop, Claude Code, Cursor, …)에 이상적이에요.

MCP 서버를 스트리밍 HTTP로 노출하려면 --http 를 전달해요:

# Streaming HTTP transport on the default 127.0.0.1:8081
$ docker agent serve mcp ./agent.yaml --http

# Override the listen address / port; non-loopback HTTP requires authentication
$ docker agent serve mcp ./agent.yaml --http --listen 0.0.0.0:9090 --auth-token "$MCP_BEARER_TOKEN"

--working-dir, --env-from-file, --models-gateway, 훅 플래그 같은 런타임 구성 플래그도 사용 가능해요 — CLI reference 참고.

HTTP 보안 (HTTP security)

HTTP MCP는 기본적으로 루프백 바인딩을 사용해요. 비루프백 --listen 주소는 --auth-token 이 필요해요; 신뢰된 역방향 프록시나 네트워크 경계가 클라이언트를 인증할 때만 --insecure-no-auth 를 사용하세요. 안전 정책은 --safety, 에이전트 구성, 런타임 구성, restricted 순으로 결정돼요. 이 HTTP 전용 플래그는 stdio 또는 --attach 동작에는 영향이 없어요.

Claude Desktop과 함께 사용 (Using with Claude Desktop)

Claude Desktop MCP 설정 파일에 구성을 추가해요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "myagent": {
      "command": "/usr/local/bin/docker",
      "args": [
        "agent",
        "serve",
        "mcp",
        "myorg/coder",
        "--working-dir",
        "/home/user/projects"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "your_key_here",
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}

구성 업데이트 후 Claude Desktop을 재시작하세요.

Claude Code와 함께 사용 (Using with Claude Code)

$ claude mcp add --transport stdio myagent \
  --env OPENAI_API_KEY=$OPENAI_API_KEY \
  --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -- docker agent serve mcp myorg/agent:tag --working-dir $(pwd)

MCP 모드의 다중 에이전트 (Multi-Agent in MCP Mode)

MCP로 다중 에이전트 구성을 노출하면, 각 에이전트가 MCP 클라이언트에서 별개의 도구가 돼요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Main coordinator
    sub_agents: [designer, engineer]
  designer:
    model: openai/gpt-5-mini
    description: UI/UX design specialist
  engineer:
    model: anthropic/claude-sonnet-4-5
    description: Software engineer

세 에이전트(root, designer, engineer) 모두 Claude Desktop이나 Claude Code에서 별개의 도구로 나타나요.

문제 해결 (Troubleshooting)

• 에이전트가 나타나지 않음: docker-agent 바이너리 경로를 확인하고 MCP 클라이언트 재시작
• 권한 에러: docker-agent 실행 권한 확인(chmod +x)
• API 키 누락: env 섹션에 모든 필수 키를 전달
• 작업 디렉터리 문제: --working-dir 경로가 존재하고 접근 가능한지 확인

더 알아보기 (Learn more)