MCP 터널 | Anthropic 지원 센터

이것이 무엇인가요?

인바운드 포트를 열거나 서비스를 인터넷에 노출하지 않고 Claude를 개인 네트워크에서 실행 중인 MCP 서버에 안전하게 연결합니다. MCP 터널은 현재 비공개 베타 상태이며 Cloudflare의 터널 서비스를 사용합니다.

작동 방식

MCP 터널은 Claude와 내부 MCP 서버 간의 연결을 생성하며, 전송 중에 여러 보안 계층으로 암호화됩니다.

Claude가 개인 네트워크의 MCP 서버에 접근해야 할 때, 요청은 보안 터널을 통해 이동합니다. 귀사 측에서 두 가지 구성 요소를 배포합니다:

cloudflared (Cloudflare의 터널 에이전트)
MCP 게이트웨이 (Anthropic 제공)

Cloudflared는 Cloudflare의 엣지에 대한 아웃바운드 전용 연결을 시작합니다. 방화벽에서 인바운드 포트를 열 필요가 없습니다. MCP 게이트웨이는 내부 TLS 계층을 종료하고, SSRF를 방지하기 위해 업스트림 IP를 검증하며, 서브도메인을 기반으로 각 요청을 올바른 MCP 서버로 라우팅합니다.

연결은 세 가지 독립적인 계층으로 보호됩니다: Anthropic과 Cloudflare 간의 외부 mTLS (IP 검증 포함), Anthropic의 백엔드에서 게이트웨이까지 페이로드를 엔드투엔드로 암호화하는 내부 TLS (Cloudflare가 MCP 페이로드에 접근할 수 없도록 설계됨), 그리고 각 MCP 서버의 애플리케이션 계층에서의 OAuth 인증입니다.

배포 항목

cloudflared

Cloudflare의 터널 에이전트입니다. 아웃바운드 전용 연결을 시작합니다 — 인바운드 포트가 필요하지 않습니다.

MCP 게이트웨이

내부 TLS를 종료하고, IP를 검증하며, 요청을 MCP 서버로 라우팅하는 Anthropic 제공 구성 요소입니다.

주요 보안 속성

인바운드 포트가 필요하지 않습니다. cloudflared는 아웃바운드 연결만 시작합니다 — 방화벽이 닫혀 있습니다.
엔드투엔드 암호화. 트래픽은 Anthropic의 백엔드에서 게이트웨이까지 전송 중에 암호화됩니다. MCP 페이로드는 Cloudflare에서 읽을 수 없습니다.
심층 방어. 여러 인증 계층: mTLS, 내부 TLS, 애플리케이션 계층의 OAuth입니다.
SSRF 보호. 게이트웨이는 요청 위조 공격을 방지하기 위해 업스트림 IP를 검증합니다.

이 가이드는 Helm (Kubernetes용) 및 Docker Compose를 통한 참조 배포를 제공합니다. 조직의 보안 요구 사항을 충족하도록 조정할 책임은 귀사에 있습니다.

공동 책임

이 시스템을 안전하게 유지하는 것은 Anthropic과 귀사 조직 간의 공동 책임입니다.

Anthropic의 책임:

Anthropic만 터널에 접근할 수 있도록 보장
게이트웨이에 연결하기 전에 CA 인증서 검증
Claude가 조직이 소유한 터널로만 요청을 보내도록 보장

귀사의 책임:

이 문서 및 후속 지침을 따르기
터널 토큰 및 TLS 개인 키 보호
MCP 사양에 설명된 대로 OAuth 인증을 사용하도록 MCP 서버 구성
게이트웨이 호스트 및 MCP 서버에 대한 접근을 적절한 담당자로 제한
시스템이 손상되었다고 의심되는 경우 Anthropic에 알림 (의심되는 위반에 대응 참조)

⚠️ 자격 증명 위험. 공격자가 터널 토큰과 TLS 개인 키 중 하나를 획득하면, 게이트웨이를 가장하고 OAuth 토큰을 포함한 MCP 요청 페이로드를 읽을 수 있습니다. 파일 권한, 저장 데이터 암호화, 비밀 관리를 포함하여 조직의 보안 요구 사항에 따라 이러한 자격 증명을 보호하세요.

필수 조건

배포 대상 — Kubernetes 클러스터 (Helm용) 또는 Docker 및 Docker Compose가 있는 VM입니다.
터널 API용 Anthropic API 토큰 — claude.ai → 조직 설정 → 커넥터 → 터널 API에서 생성합니다. 설정은 이 토큰을 사용하여 터널을 프로비저닝하고 CA 인증서를 등록합니다. 게이트웨이는 런타임에 필요하지 않습니다. 설정을 완료한 후 취소합니다.
네트워크 접근 — 아래 표에 따른 아웃바운드 연결입니다.
MCP 서버 — 게이트웨이가 접근할 수 있는 개인 네트워크에서 실행 중인 하나 이상의 MCP 서버입니다.

네트워크 요구 사항

구성 요소	대상	목적
설정 (일회성)	`api.anthropic.com:443` (포트 443)	터널 프로비저닝
cloudflared	Cloudflare 엣지, 포트 7844 TCP/UDP (`198.41.192.0/19`, `2606:4700:a0::/44`)	터널 연결
MCP 게이트웨이	MCP 서버	업스트림 트래픽

Cloudflare의 터널 방화벽 설명서에서 권한 있는 IP 목록을 확인하세요. Helm 사용자는 차트의 networkPolicy 값을 활성화하여 이 송신 제한을 적용할 수 있습니다.

배포 방법 선택

MCP 터널은 Helm(Kubernetes) 또는 Docker Compose를 통해 배포할 수 있습니다. 인프라에 맞는 방법을 선택하세요.

⎈ Helm / Kubernetes

대부분의 고객에게 권장됩니다. 터널 프로비저닝 및 인증서 갱신을 자동화합니다. 자격 증명을 Secrets로 저장합니다.

🐳 Docker Compose

단일 호스트 또는 VM 배포용입니다.

Helm / Kubernetes 배포

1. 차트 값 가져오기

기본값 파일을 다운로드합니다. 각 필드를 설명하는 주석이 포함되어 있습니다.

Shell

helm show values \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 > values.yaml

2. 경로 구성

values.yaml을 편집하고 gateway.config.routes 아래에 최소 하나의 경로를 추가합니다. 각 경로는 서브도메인 접두사를 업스트림 MCP 서버 URL에 매핑합니다.

3. 렌더링된 매니페스트 검토

플레이스홀더 토큰으로 차트를 렌더링하여 설치 전에 Kubernetes 리소스를 검사합니다. 차트는 렌더링하려면 api.token이 필요하지만 helm template은 API를 호출하지 않습니다.

Shell

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token=placeholder > rendered.yaml

조직의 타사 매니페스트 검증 관행에 따라 rendered.yaml을 검토하세요.

4. 차트 설치

API 토큰을 환경 변수에 저장한 후 설치합니다. 격리를 위해 전용 네임스페이스를 권장합니다.

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml \
  --set api.token="$API_TOKEN"

⚠️ 중요: 설치가 완료되면 API 토큰을 취소하세요. --set을 통해 토큰을 전달하면 값 파일에서 제외되지만 Helm은 여전히 릴리스 기록(sh.helm.release.v1.* Secrets)에 기록합니다. Kubernetes Secrets는 기본적으로 저장 시 암호화되지 않으므로 토큰을 취소할 때까지 클러스터에서 복구할 수 있습니다.

5. 터널 도메인 검색

설정 Job은 터널 도메인을 Secret에 씁니다. Claude에서 MCP 서버를 구성하려면 이것이 필요합니다.

Shell

kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-domain}' | base64 -d

터널이 실행 중이면 Claude에 연결하세요.

선택 사항: NetworkPolicy 활성화

값 파일에서 networkPolicy.enabled: true를 설정하여 터널 포드의 송신을 네트워크 수준에서 제한합니다. 업스트림 MCP 서버에 대한 포드 레이블 선택기 또는 CIDR 범위로 networkPolicy.mcpServers를 구성합니다. 정책에는 이미 cloudflared가 Cloudflare의 엣지에 도달하기 위한 송신 규칙이 포함되어 있습니다. 클러스터의 CNI는 NetworkPolicy를 지원해야 합니다. 값 파일에서 예제를 참조하세요.

선택 사항: 게이트웨이 구성

gateway.config.* 아래의 필드는 게이트웨이의 구성 파일로 전달됩니다. 전체 목록은 부록: 게이트웨이 구성을 참조하세요. 일반적인 조정에는 upstream.allowed_ips, log_level 및 https:// 경로용 upstream.tls가 포함됩니다. 구성이 참조하는 추가 파일(예: upstream.tls.ca_file용 CA 번들)을 마운트하려면 gateway.extraVolumes 및 gateway.extraVolumeMounts를 사용하세요.

업그레이드

helm upgrade에서 항상 --version을 지정하세요. 지정하지 않으면 Helm은 레지스트리에서 최신 차트 버전을 가져오며, 이는 검토한 버전이 아닐 수 있습니다.

구성 변경(경로, 복제본, NetworkPolicy 등)의 경우 API 토큰이 필요하지 않습니다. api.token을 전달하지 않으면 설정 Job이 업그레이드에서 건너뜁니다:

Shell

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml

터널 토큰 회전의 경우 값 파일에서 tunnel.tokenVersion을 증가시키고, 새 API 토큰을 생성한 후 업그레이드하세요:

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token="$API_TOKEN"

업그레이드가 완료되면 API 토큰을 취소하세요.

--reuse-values에 의존하지 말고 완전한 값 파일을 유지하세요. Helm은 맵 필드를 깊게 병합하므로 --reuse-values로 경로를 삭제하면 자동으로 실패합니다.

kubectl 또는 kustomize와 함께 helm template 사용

매니페스트를 렌더링하고 직접 적용하려면(kubectl apply 또는 kustomize 오버레이를 통해) 외부 모드(setup.enabled: false)를 사용하세요. 터널을 별도로 프로비저닝하고(부록: 터널 API 참조) external.tunnelTokenSecretName 및 external.serverCertSecretName으로 참조되는 사전 생성된 Secrets로 자격 증명을 제공합니다. 설정 바이너리를 사용하지 않고 자신의 인증서를 발급하는 경우 부록: 인증서 요구 사항을 참조하세요.

Docker Compose 배포

1. 배포 디렉토리 준비

Shell

mkdir -p mcp-gateway/{config,tunnel-data}
cd mcp-gateway
sudo chown 65532:65532 tunnel-data

chown을 사용하면 컨테이너(UID 65532로 실행)가 바인드 마운트된 디렉토리에 쓸 수 있습니다.

2. docker-compose.yaml 생성

YAML

services:
  # One-time provisioning. Run with: docker compose run --rm setup
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - API_TOKEN
    volumes:
      - ./tunnel-data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    # Verify digest at https://hub.docker.com/r/cloudflare/cloudflared/tags
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate --config /etc/cloudflared/config.yaml run
    environment:
      - TUNNEL_TOKEN
    volumes:
      - ./config/cloudflared-config.yaml:/etc/cloudflared/config.yaml:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-gateway:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    volumes:
      - ./config/mcp-gateway.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./tunnel-data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # Should match shutdown_timeout in mcp-gateway config
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

보안 조치: 루트가 아닌 실행(UID 65532), 읽기 전용 파일 시스템, 권한 상승 없음, 모든 Linux 기능 삭제, SHA256 다이제스트로 이미지 고정.

3. 터널 프로비저닝

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

설정 명령은 Tunnels API를 통해 터널을 생성하고, CA 및 서버 인증서를 생성하며, CA를 Anthropic에 등록하고, 모든 출력을 ./tunnel-data/에 작성합니다.

다음 단계를 위해 터널 도메인을 검색합니다:

Shell

sudo cat tunnel-data/tunnel-domain

⚠️ 중요: 진행하기 전에 API 토큰을 취소하세요.

4. 게이트웨이 구성

config/mcp-gateway.yaml 생성:

YAML

listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s

# Your tunnel domain from Step 3
tunnel_domain: abcd1234.tunnel.anthropic.com

tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key

routes:
  # Replace with your actual MCP servers.
  # With tunnel_domain set, keys are subdomain prefixes.
  docs: http://docs-mcp.internal:8080
  search: http://search-mcp.internal:8080

upstream:
  allowed_ips:
    - 10.0.0.0/8

사용 가능한 모든 필드는 부록: 게이트웨이 구성을 참조하세요.

config/cloudflared-config.yaml 생성:

YAML

ingress:
  - service: http://mcp-gateway:8080

5. 배포

Shell

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

디렉토리 구조:

mcp-gateway/
├── docker-compose.yaml
├── config/
│   ├── cloudflared-config.yaml
│   └── mcp-gateway.yaml
└── tunnel-data/
    ├── tunnel-id
    ├── tunnel-domain
    ├── tunnel-token
    ├── token-version
    ├── ca.crt
    ├── ca.key
    ├── tls.crt
    └── tls.key

CA 개인 키와 터널 토큰을 안전한 저장소로 이동하는 것을 고려하세요.

다중 VM 배포의 경우: mcp-gateway/ 디렉토리를 각 호스트에 복사합니다. 동일한 터널 토큰과 인증서가 모든 복제본에서 작동합니다.

터널이 실행 중이면 Claude에 연결합니다.

인증서 갱신(Compose)

서버 인증서의 유효 기간은 90일입니다. 만료 전에 갱신하세요:

Shell

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

게이트웨이는 30초마다 인증서 파일을 폴링하고 변경 시 자동으로 다시 로드합니다. 이 명령을 일정에 따라 안전하게 실행할 수 있는 플래그는 부록: 설정 CLI 참조를 참조하세요.

터널 토큰 로테이션(Compose)

docker-compose.yaml을 편집하여 --token-version을 증가시킨 후 새 API 토큰으로 설정을 다시 실행합니다:

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

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

로테이션이 완료되면 API 토큰을 취소합니다.

Claude에 연결

터널이 실행 중이면 MCP 서버를 Claude에 등록하여 사용자가 사용할 수 있도록 합니다.

1. MCP 서버 추가

조직 관리자는 claude.ai에서 Organization Settings → Connectors → Add → Custom → Web로 이동합니다.

각 MCP 서버를 터널 호스트명으로 입력합니다. 예를 들어 docs.abcd1234.tunnel.anthropic.com입니다. 서브도메인 접두사는 게이트웨이 구성의 경로 키와 일치합니다.

2. 사용자 연결

개별 사용자는 Settings → Connectors로 이동하여 사용하려는 각 MCP 서버에 대해 Connect를 클릭합니다.

나중에 더 많은 서버를 추가하시겠어요? 구성에 새 경로를 추가하고 변경 사항을 적용한 후(helm upgrade 또는 docker compose restart mcp-gateway), Claude에서 새 호스트명을 등록합니다. 인증서 또는 cloudflared 변경이 필요하지 않습니다. 와일드카드 인증서가 모든 서브도메인을 포함합니다.

보안 모범 사례

MCP 서버에서 OAuth를 요구하세요. 터널 및 TLS 계층은 전송을 보호하지만, 이들이 손상되면 애플리케이션 계층의 OAuth는 여전히 무단 도구 호출을 방지합니다. MCP 사양에 설명된 대로 각 MCP 서버가 OAuth 인증을 요구하도록 구성하세요.
claude.ai 조직에 SSO를 활성화하세요. 터널 토큰은 claude.ai 콘솔에서 생성됩니다. SSO가 적용되면 ID 공급자의 세션 제어가 관리자 세션을 관리합니다.
allowed_ips를 제한하세요. MCP 서버를 포함하는 가장 작은 CIDR 범위를 사용하세요.
로그를 모니터링하세요. 경고, 오류 및 비정상적인 패턴에 대한 알림을 설정하세요.
자격 증명을 로테이션하세요. 정기적으로 인증서를 로테이션하거나 손상이 의심되면 즉시 로테이션하세요.
이미지를 최신 상태로 유지하세요. 게이트웨이 업데이트를 신속하게 적용합니다. SHA256 다이제스트로 이미지를 고정합니다.
네트워크 액세스를 제한하세요. 게이트웨이와 cloudflared는 필요한 네트워크 액세스만 가져야 합니다.
MCP 서버 범위를 제한하세요. MCP 서버는 필요한 기능만 노출해야 합니다.
저장된 자격 증명을 보호하세요. tunnel-data/ 디렉토리(Compose) 또는 자격 증명 Secret(Helm)에 적절한 파일 권한, 저장 데이터 암호화 및 비밀 관리를 적용하세요.

의심되는 위반에 대응

터널 자격 증명, TLS 키 또는 시스템의 다른 측면이 손상되었다고 의심되는 경우:

배포를 즉시 중지합니다(helm uninstall 또는 docker compose down --timeout 0)
Claude에서 MCP 서버 제거(Organization Settings → Connectors)
API를 통해 터널을 보관합니다(Teardown, 3단계 참조)
Anthropic에 문의하여 조사할 수 있도록 합니다
자격 증명을 로테이션합니다 — 새 터널을 다시 프로비저닝하고 MCP 서버의 OAuth 토큰을 로테이션합니다
서비스 복원 전에 검토 로그

문제 해결

IP 유효성 검사 실패

게이트웨이 로그의 "IP 유효성 검사 실패"는 업스트림이 allowed_ips 외부의 IP로 확인되었음을 의미합니다. 확인된 IP를 확인하세요:

셸

dig +short docs-mcp.internal

IP가 정당한 경우 게이트웨이 구성에서 allowed_ips를 업데이트하여 올바른 CIDR 범위를 포함하세요.

터널이 연결되지 않음

cloudflared 로그에서 오류를 확인하세요. 일반적인 원인:

잘못된 터널 토큰
방화벽이 Cloudflare 엣지로의 아웃바운드 포트 7844 TCP/UDP를 차단함

Cloudflare의 IP 범위로의 아웃바운드 연결 확인: 198.41.192.0/19 및 2606:4700:a0::/44.

UDP 버퍼 크기 경고

cloudflared는 failed to sufficiently increase receive buffer size를 기록할 수 있습니다. 이는 QUIC 전송 튜닝 문제입니다. 조정하려면 quic-go UDP 버퍼 설명서를 참조하세요.

인증서 오류

TLS 핸드셰이크가 실패하면 다음을 확인하세요:

서버 인증서가 만료되지 않았음 (90일 유효성)
인증서의 SAN이 *.<tunnel-domain>과 일치함
CA 인증서가 API를 통해 Anthropic에 등록됨
Compose의 경우 인증서 파일이 UID 65532로 읽을 수 있음

터널을 통한 OAuth 라우팅 (IP 허용 목록 뒤의 인증 서버)

문제: 인증 서버가 소스 IP 허용 목록 뒤에 있습니다. Claude의 백엔드는 OAuth 검색, 클라이언트 등록 및 토큰 교환을 위해 이에 도달해야 하지만 Anthropic의 이그레스 IP 범위를 허용 목록에 추가하고 싶지 않습니다.

솔루션: 분할 엔드포인트 구성. 백엔드 간 OAuth 호출을 터널을 통해 라우팅합니다. 브라우저 대면 /authorize 엔드포인트를 기존 허용 목록 호스트명에 유지합니다. Claude가 검색 메타데이터에서 authorization_endpoint를 읽고 사용자의 브라우저를 그곳으로 리디렉션하기 때문에 작동합니다. 해당 URL에 직접 도달할 필요가 없습니다.

1단계: 인증 서버에 대한 게이트웨이 경로 추가

YAML — mcp-gateway.yaml

routes:
  mcp: http://your-mcp-server:8080
  auth: http://your-auth-server:8080

2단계: 분할 엔드포인트 검색 메타데이터 제공

인증 서버의 /.well-known/oauth-authorization-server는 다음을 반환해야 합니다:

JSON

{
  "issuer": "https://auth.<tunnel-id>.tunnel.anthropic.com",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/token",
  "registration_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/register",
  "code_challenge_methods_supported": ["S256"]
}

authorization_endpoint만 기존 호스트명을 가리킵니다. 다른 모든 것은 터널 URL을 사용합니다.

3단계: MCP 서버를 터널 발급자로 지정

MCP 서버의 /.well-known/oauth-protected-resource:

JSON

{
  "resource": "https://mcp.<tunnel-id>.tunnel.anthropic.com",
  "authorization_servers": [
    "https://auth.<tunnel-id>.tunnel.anthropic.com"
  ]
}

해제

더 이상 필요하지 않을 때 터널을 폐기하는 방법.

1. 터널 ID 가져오기

Helm

TUNNEL_ID=$(kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-id}' | base64 -d)

Compose

TUNNEL_ID=$(sudo cat tunnel-data/tunnel-id)

2. 배포 중지

Helm: helm uninstall mcp-tunnel -n mcp-tunnel (참고: 자격증명 Secret은 설정 Job에서 생성되었으며 Helm에서 생성되지 않았으므로 제거 후에도 유지됨)
Compose: docker compose down

3. 터널 보관

먼저 새 API 토큰을 생성하고 완료되면 취소하세요.

셸

read -rs API_TOKEN && export API_TOKEN

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

4. 저장된 자격증명 제거

Helm: kubectl delete secret mcp-tunnel -n mcp-tunnel
Compose: sudo rm -rf tunnel-data

도움말 받기

지원을 위해 Anthropic 계정 팀에 문의하세요.

부록: 게이트웨이 구성

게이트웨이는 YAML 파일에서 구성을 읽습니다. Docker Compose에서는 이 파일을 config/mcp-gateway.yaml로 직접 작성합니다. Helm에서는 값 파일의 gateway.config.* 아래에 이러한 필드를 설정하면 차트가 listen_addr, tls 및 tunnel_domain을 관리합니다.

필드	설명	기본값
`listen_addr`	수신 대기할 주소 및 포트	필수
`log_level`	로깅 상세도: `debug`, `info`, `warn`, `error`	`info`
`shutdown_timeout`	정상 종료 중 진행 중인 요청의 대기 시간	`30s`
`tunnel_domain`	접두사 경로 확인을 위한 기본 도메인	없음
`tls.cert_file`	TLS 인증서 경로	필수
`tls.key_file`	TLS 개인 키 경로	필수
`routes`	호스트명(또는 접두사)에서 업스트림 URL로의 매핑	필수
`upstream.allowed_ips`	게이트웨이가 연결할 수 있는 CIDR 범위	RFC 1918 개인 범위
`upstream.disable_ip_validation`	IP 검증 완전히 비활성화	`false`
`upstream.tls.ca_file`	업스트림 TLS 검증을 위한 CA 번들	없음
`upstream.tls.include_system_cas`	업스트림 TLS에 대해 시스템 CA 번들 신뢰	`false`

https:// 경로의 경우 upstream.tls.ca_file 또는 upstream.tls.include_system_cas 중 하나 이상을 설정하세요.

부록: 터널 API

사용자 정의 프로비저닝 워크플로우의 경우 터널 API를 직접 호출할 수 있습니다. 모든 요청에는 다음 헤더가 필요합니다:

셸

-H "Authorization: Bearer $API_TOKEN"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: mcp-tunnels-2026-02-24"

터널 생성:

curl -X POST https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d '{}'

터널 나열:

curl https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

CA 인증서 등록:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d "{\"ca_certificate_pem\": $(jq -Rs . < ca.crt)}"

CA 및 서버 인증서가 포함해야 할 내용은 부록: 인증서 요구사항을 참조하세요.

CA 인증서 나열:

curl "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

CA 인증서 취소:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates/${CERT_ID}/revoke" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

터널 토큰 공개:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/reveal_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

터널 토큰 회전:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/rotate_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

터널 보관:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

부록: 인증서 요구사항

설정 바이너리(setup init / setup renew-cert)를 사용하면 자동으로 호환되는 인증서를 생성하므로 이 섹션을 건너뛸 수 있습니다. 이 요구사항은 자신의 PKI를 통해 인증서를 발급하는 경우에 적용됩니다.

CA 인증서 — POST /v1/tunnels/{id}/certificates를 통해 업로드합니다. 터널은 한 번에 최대 2개의 활성 CA 인증서를 보유할 수 있으므로 다운타임 없이 회전할 수 있습니다.

PEM 인코딩, 단일 인증서, 최대 8KB
BasicConstraints 확장(critical로 표시된 CA:TRUE 포함)
SubjectKeyIdentifier 확장 존재
KeyUsage에 keyCertSign 포함
유효 기간 내
RSA 2048비트 이상 또는 ECDSA P-256 이상, SHA-256 이상의 서명

서버 인증서 — 내부 TLS 핸드셰이크 중 게이트웨이에서 제시됨. Anthropic에 업로드되지 않음.

터널에 등록된 CA에서 직접 서명됨
AuthorityKeyIdentifier 확장 존재, CA의 SubjectKeyIdentifier와 일치
SAN에 <route>.<tunnel-domain>과 일치하는 DNS 이름 포함(와일드카드 *.<tunnel-domain>는 모든 경로 포함)
ExtendedKeyUsage 확장이 있으면 serverAuth 포함
유효 기간 내
RSA 2048비트 이상 또는 ECDSA P-256 이상, SHA-256 이상의 서명

참고: 설정 바이너리는 ECDSA P-256 CA(5년 유효성)와 와일드카드 SAN이 있는 RSA 4096비트 서버 인증서(90일 유효성)를 생성합니다.

부록: 설정 CLI 참고

setup 바이너리는 docker compose run --rm setup <subcommand>(Compose) 또는 Helm 훅 및 CronJob(Kubernetes)으로 게이트웨이 컨테이너 내에서 실행됩니다.

setup init — Tunnels API를 통해 터널을 생성하고, CA 및 서버 인증서를 생성하며, CA를 등록하고, 모든 출력을 작성합니다.

플래그	설명	기본값
`--api-url`	Anthropic API 기본 URL. `API_URL`에서도 읽음.	필수
`--api-token`	터널 범위의 API 토큰. `API_TOKEN`에서도 읽음.	필수
`--output`	출력 대상: `dir:/path` 또는 `k8s-secret:NAME`	`k8s-secret:mcp-gateway`
`--cert-duration`	서버 인증서 유효 기간	`2160h` (90일)
`--token-version`	변경 감지 문자열, 새 값은 터널 토큰 회전을 트리거함	없음

setup renew-cert — 저장된 CA에서 서명한 새 서버 인증서를 발급합니다. API 호출 필요 없음.

플래그	설명	기본값
`--output`	출력 대상: `dir:/path` 또는 `k8s-secret:NAME`	`k8s-secret:mcp-gateway`
`--cert-duration`	새 인증서 유효 기간	`2160h` (90일)
`--renew-before`	기존 인증서가 만료될 때까지 이보다 더 오래 남아 있으면 건너뛰기	`0` (항상 갱신)

--renew-before=720h를 설정하면 30일 이상 남아 있을 때 명령이 작동하지 않으므로 일정에 따라 실행하기에 적합합니다.