Docker Compose로 MCP 터널 배포하기

이 가이드는 터널 스택을 단일 호스트에 강화된 컨테이너로 배포합니다. 동일한 구성을 여러 호스트에 복제하여 가용성을 확보할 수 있습니다.

시작하기 전에

다음이 필요합니다:

• Console에서 생성된 터널. 터널 생성을 따라 진행하고 터널 ID(tnl_...)를 기록하세요.
• 호스트가 Tunnels API에 인증할 수 있는 방법.
  • 프로그래매틱 액세스(권장). 터널을 생성할 때 Set up programmatic access를 켜서 setup 컴포넌트가 Workload Identity Federation을 통해 인증할 수 있도록 하세요. 페더레이션 규칙 ID(fdrl_...)와 조직 ID를 기록하세요.
  • 수동. 프로그래매틱 액세스를 건너뜁니다. Console에서 터널 토큰을 가져오고, CA 및 서버 인증서를 직접 생성한 다음, Console에서 CA를 등록합니다.
• Docker 및 Docker Compose가 설치된 호스트. 수동 방식에는 openssl(1.1.1 이상)도 필요합니다.
• 호스트에서 api.anthropic.com(443 TCP) 및 터널 엣지(7844 TCP 및 UDP)로의 아웃바운드 네트워크 연결. 전체 네트워크 요구 사항을 참조하세요.
• routes에 구성할 주소로 호스트에서 실행 중이며 접근 가능한 하나 이상의 MCP 서버. 아직 없다면 샘플 서버를 사용하세요.

선택 사항: 샘플 MCP 서버 사용

테스트에 사용할 MCP 서버가 없다면 다음의 최소 서버를 사용하세요:

mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


@mcp.tool()
def hello(name: str = "world") -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"


if __name__ == "__main__":
    mcp.run(transport="streamable-http")
EOF

다음 설치 단계에서는 mcp-tunnel/로 cd하며, 해당 서비스와 라우트를 추가할 위치를 안내합니다.

설치

이 가이드는 Docker Compose를 사용하는 하나의 참조 접근 방식을 제공합니다. 조직의 보안 요구 사항에 맞게 조정하는 것은 사용자의 책임입니다.

compose 파일은 기본값 없이 호스트 환경에서 TUNNEL_TOKEN을 읽으므로, 새 셸마다 그리고 재부팅 후에 export를 반복해야 합니다.

다중 VM 배포의 경우 mcp-tunnel/ 디렉터리를 각 호스트에 복사하고, TUNNEL_TOKEN을 설정한 다음, docker compose up -d를 실행하세요. 프로그래매틱 방식에서는 TUNNEL_TOKEN이 $(sudo cat data/tunnel-token)이고, 수동 방식에서는 Console에서 복사한 값입니다. 동일한 터널 토큰과 인증서가 모든 복제본에서 작동합니다.

배포 확인

Anthropic 측에서 업스트림 MCP 서버를 호출하여 엔드 투 엔드로 확인하세요. 터널링된 MCP 서버 사용을 참조하세요. 샘플 MCP 서버를 사용하는 경우 라우팅된 URL은 https://echo.<your-tunnel-domain>/mcp입니다. 확인에 실패하면 문제 해결을 참조하세요.

업그레이드

이 섹션의 명령은 mcp-tunnel/ 배포 디렉터리 내부에서 실행하세요.

터널 토큰 교체

프로그래매틱 액세스를 사용하는 경우, setup 서비스 command에서 --token-version을 증가시키고, Workload Identity Federation 식별자를 설정하고, 새 OIDC JWT를 발급한 다음, setup 컴포넌트를 다시 실행하세요:

# docker-compose.yaml 편집: setup 서비스의 --token-version 인수에 있는 정수를
# 증가시키세요(예: --token-version=1 에서 --token-version=2 로).
# 값이 변경되지 않으면 setup 바이너리는 로테이션을 거부합니다.
# 

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # 규칙이 워크스페이스 범위인 경우
# 사용 환경에 맞는 WIF 공급자 가이드에 따라 ANTHROPIC_IDENTITY_TOKEN 을
# 다시 발급하세요(설치 이후 만료되었을 것입니다).
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d cloudflared

--token-version 인수는 명령줄에서 전달하지 않고 docker-compose.yaml에서 편집하므로, 새 값이 setup 컴포넌트의 향후 실행에서도 유지됩니다. setup 컴포넌트는 Workload Identity Federation으로 인증하므로 폐기할 API 토큰이 없습니다.

프로그래매틱 액세스가 없는 경우, Console의 터널 상세 페이지에서 Rotate token을 클릭한 다음, 각 호스트에서 TUNNEL_TOKEN 환경 변수를 업데이트하고 cloudflared를 재시작하세요(docker compose up -d cloudflared).

인증서 갱신

서버 인증서가 만료되기 전에 만료를 모니터링하고 갱신하는 것은 사용자의 책임입니다.

프로그래매틱 액세스를 사용하는 경우:

docker compose run --rm setup renew-cert --output=dir:/data

CLI 인수는 setup 서비스의 command(init 인수)를 대체하지만 entrypoint는 유지하므로, 이는 /setup renew-cert --output=dir:/data를 실행합니다.

프로그래매틱 액세스가 없는 경우, 기존 CA로 새 서버 인증서에 서명하고(Console에 등록된 CA는 변경되지 않음) data/tls.crt를 교체하세요. 새 셸에서 실행하는 경우 먼저 TUNNEL_DOMAIN을 설정하세요.

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 \
  -extfile data/tls.ext

두 방식 모두에서 프록시는 tls.cert_file을 폴링하고 자동으로 다시 로드하므로 재시작이 필요하지 않습니다.

다음 단계