MCP 터널

MCP 터널을 사용하면 프라이빗 네트워크 내부에서 실행되는 "Model Context Protocol", 즉 MCP 서버에 Claude를 연결할 수 있습니다. 트래픽은 아웃바운드 전용 연결을 통해 흐르므로, 인바운드 방화벽 포트를 열거나 서비스를 공용 인터넷에 노출하거나 오리진에서 Anthropic의 IP 범위를 허용 목록에 추가할 필요가 없습니다.

Zero Data Retention 및 HIPAA BAA 적격성에 대해서는 API 및 데이터 보존을 참조하세요.

작동 방식

터널 스택은 네트워크 내부에서 실행되는 두 가지 구성 요소로 이루어집니다:

• cloudflared: Cloudflare의 오픈 소스 터널 커넥터입니다. 터널 엣지로 아웃바운드 전용 연결을 시작하고 Anthropic에서 프록시로 암호화된 트래픽을 전달합니다.
• 프록시: Anthropic의 라우팅 구성 요소입니다. 내부 TLS를 종료하고, 업스트림 IP가 허용된 범위 내에 있는지 검증하며, 호스트 이름을 기반으로 각 요청을 올바른 업스트림 MCP 서버로 라우팅합니다.

노출하는 각 MCP 서버는 터널 도메인 아래의 호스트 이름을 갖게 됩니다(예: docs.<your-tunnel-domain>). 이러한 호스트 이름을 Claude Console에서 Managed Agent 세션에 연결하거나, MCP 커넥터를 통해 Messages API에 전달합니다.

사전 요구 사항

배포하기 전에 다음을 준비했는지 확인하세요:

• 배포 대상: Kubernetes 클러스터 또는 Docker와 Docker Compose가 설치된 VM.
• 터널. Claude Console에서 생성하거나(터널 생성 참조) API를 통해 생성합니다. Helm 차트의 설정 훅이 설치 중에 터널을 생성해 줄 수도 있습니다.
• 스택이 Tunnels API에 인증하는 방법. 다음 중 하나를 선택하세요:
  • 프로그래매틱 액세스(권장). 터널을 생성할 때 Workload Identity Federation을 설정합니다. 스택이 ID 공급자로부터 단기 API 토큰을 발급하고, 터널 토큰을 가져오며, CA 인증서를 자동으로 생성하고 등록합니다. 페더레이션 규칙을 관리할 권한, 등록된 OIDC 발급자, 그리고 workspace:manage_tunnels 범위를 가진 페더레이션 규칙이 필요합니다.
  • 수동. 정적 자격 증명을 직접 제공합니다: Console의 터널 토큰과 Console에 등록한 CA가 서명한 서버 인증서입니다. 연결 세부 정보 가져오기 및 CA 인증서 추가를 참조하세요.
• 프라이빗 네트워크에서 실행 중인 하나 이상의 MCP 서버. 예시는 원격 MCP 서버를 참조하세요.
• 네트워크 요구 사항에 나열된 아웃바운드 연결.

네트워크 요구 사항

보안 모델

보안 계층

세 개의 독립적인 계층이 모든 요청을 보호합니다:

터널 전송은 Cloudflare의 네트워크에서 실행됩니다. 프록시가 사용자만 보유한 인증서를 사용하여 내부 TLS를 종료하므로, Cloudflare는 요청 또는 응답 페이로드를 읽을 수 없습니다. Anthropic은 CA 인증서가 등록될 때까지 터널에 연결하지 않으므로, 페이로드는 Cloudflare의 네트워크를 통과할 때 항상 암호화됩니다. Cloudflare는 연결 메타데이터를 수신합니다. 전송 제공업체가 관찰할 수 있는 것을 참조하세요.

공동 책임 모델

전송 제공업체가 관찰할 수 있는 것

Cloudflare는 아웃바운드 전송을 제공합니다. MCP 요청 또는 응답 페이로드는 읽을 수 없지만, 다음과 같은 연결 메타데이터를 수신합니다:

• cloudflared를 실행하는 호스트의 이그레스 IP 주소
• cloudflared 호스트 핑거프린트
• 연결 타이밍 및 바이트 볼륨
• 터널에 할당된 *.tunnel.anthropic.com 하위 도메인

Anthropic과 Cloudflare 간의 계약은 Cloudflare의 이 텔레메트리 사용을 제한합니다. Cloudflare는 이 리서치 프리뷰에서 하위 처리자 역할을 합니다.

터널 배포

MCP 터널을 처음 사용하는 경우, 프로덕션 배포를 구성하기 전에 빠른 시작으로 로컬에서 작동하는 터널을 먼저 만들어 보세요.

선택 기준:

• 배포 대상
  • Kubernetes에 배포하는 경우 Helm.
  • 단일 호스트 또는 로컬 테스트의 경우 Docker Compose.
• 설정을 위한 인증
  • Kubernetes 클러스터, 클라우드 IAM 또는 SPIFFE와 같은 OIDC ID 공급자가 있는 경우 프로그래매틱 액세스(Workload Identity Federation을 통해).
  • 그렇지 않거나 테스트 중인 경우 수동 자격 증명.

터널링된 MCP 서버 사용

터널이 활성화되면(활성 CA 인증서가 있고 터널 스택이 연결된 상태), Claude Managed Agents 및 Messages API에서 업스트림 MCP 서버에 접근할 수 있습니다.

두 경우 모두, 터널은 암호화된 트래픽을 MCP 서버로 전달하지만 MCP 서버에 인증하지는 않습니다. 업스트림 MCP 서버가 자체 인증(OAuth, 베어러 토큰)을 요구하는 경우, 다른 MCP 서버와 동일한 방식으로 제공하세요. 이는 터널과 독립적입니다.

Managed Agents (Console)

1. Managed Agents > Sessions에서 세션을 생성하고 MCP 서버 목록을 편집할 수 있도록 Create new agent를 선택합니다.
2. + MCP Server를 클릭하고 드롭다운을 엽니다. 세션의 워크스페이스에 있으며 활성 인증서가 하나 이상 있는 터널이 공용 커넥터 카탈로그 위, 목록 상단에 표시됩니다.
3. 터널을 선택하고 프록시가 특정 MCP 서버로 라우팅하는 Subdomain과 업스트림 MCP 서버가 기대하는 Path를 입력합니다. Resolves to 줄에 정확한 URL이 표시됩니다.

Messages API

다른 원격 MCP 서버와 동일한 방식으로 mcp_servers 배열에 업스트림 MCP 서버의 URL을 전달합니다. 요청 본문과 anthropic-beta 헤더는 표준 MCP 커넥터 형식을 따르며, url만 터널에 고유합니다. 다음 예시는 MCP 커넥터의 mcp-client 베타 헤더를 사용하며, 이는 Tunnels API에서 사용하는 mcp-tunnels 베타와는 별개입니다. 해당 워크스페이스의 API 키를 사용하거나, 키가 여러 워크스페이스에 액세스할 수 있는 경우 anthropic-workspace-id 헤더를 해당 워크스페이스로 설정하여, 터널이 생성된 워크스페이스에서 요청을 수행하세요.

URL의 호스트는 <subdomain>.<your-tunnel-domain>입니다. 경로는 터널이 아니라 업스트림 MCP 서버에 따라 달라집니다. FastMCP의 streamable-http 전송은 /mcp에서 서비스하며, 다른 서버는 / 또는 사용자 지정 경로를 사용할 수 있습니다(서버 문서를 확인하세요). 프록시는 경로를 변경하지 않고 그대로 전달합니다.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Use the hello tool to greet tunnel."}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",
            "name": "echo",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "echo"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

업스트림 MCP 서버에 대한 인증(authorization_token) 및 기타 mcp_servers 옵션에 대해서는 MCP 커넥터를 참조하세요.

다음 단계