아키텍처와 구성 요소

아키텍처와 구성 요소 (Architecture and components)

이 페이지에서는 MCP 터널 문서 전반에서 사용되는 용어를 정의해요. 여러 구성 요소가 설정 파일, 컨테이너 이미지, 설명 글에서 서로 다른 이름으로 나타날 수 있어서, 아래 표가 각각의 표준 이름과 함께 만날 수 있는 별칭을 정리해줘요.

출처: 문서

본문

참고 (Note) MCP 터널은 연구 프리뷰(research preview) 상태예요. 사용해보려면 액세스를 요청하세요.

이 페이지에서는 MCP 터널 문서 전반에서 사용되는 용어를 정의해요. 여러 구성 요소가 설정 파일, 컨테이너 이미지, 설명 글에서 서로 다른 이름으로 나타나므로, 아래 표에서 각각의 표준 이름과 함께 만날 수 있는 별칭을 확인할 수 있어요.

구성 요소 (Components)

용어 정의 다른 이름
터널 스택 (Tunnel stack) 터널에 연결하기 위해 네트워크 내부에서 실행하는 두 컨테이너, 즉 프록시와 cloudflared예요. 스택 하나가 터널 하나를 담당하며 가용성을 위해 호스트에 복제할 수 있어요. 프로그래매틱 액세스에서는 설정 구성 요소가 스택과 함께 실행되면서 자격 증명을 프로비저닝해요. 스택, MCP 터널 스택, 터널 배포, 여러분의 배포
프록시 (Proxy) Anthropic의 라우팅 구성 요소예요. 내부 TLS를 종료하고 업스트림 IP가 허용 범위에 드는지 검증하며, 각 요청을 호스트 이름에 따라 업스트림 MCP 서버로 라우팅해요. mcp-proxy (이미지 이름, Compose 서비스 이름, Helm 컨테이너 이름), mcp-gateway (컨테이너 내부 설정 경로 /etc/mcp-gateway/config.yaml과 Helm gateway.config.* 값 접두사)
cloudflared Cloudflare의 오픈 소스 터널 커넥터예요. 네트워크에서 터널 엣지로의 아웃바운드 전용 연결을 시작하고 엣지와 프록시 사이에서 암호화된 트래픽을 운반해요. Managed Agent와는 관련이 없어요. 아웃바운드 커넥터, 터널 커넥터
설정 구성 요소 (Setup component) mcp-proxy 이미지 안에 들어 있는 setup 바이너리예요. 프로그래매틱 액세스에서는 Workload Identity Federation을 통해 인증하고 터널 토큰을 가져오며 CA와 서버 인증서를 생성하고 CA를 Anthropic에 등록해요. renew-cert도 제공해요. setup Job (Helm 사전 설치 훅), setup 서비스 (Compose 프로필), 설정 훅, 설정 바이너리, 설정 CLI
터널 엣지 (Tunnel edge) cloudflared가 연결하는 Cloudflare 엣지 서버예요 (IP 범위 198.41.192.0/19와 2606:4700:a0::/44, 포트 7844 TCP 및 UDP). 그 위에서 도는 터널은 Anthropic이 프로비저닝하고 제어해요. Cloudflare는 기반 네트워크를 운영해요. 엣지, Anthropic이 운영하는 터널 엣지
내부 TLS (Inner TLS) 터널의 평문 WebSocket 스트림 안에서 수행되는, Anthropic 백엔드와 여러분의 프록시 사이의 두 번째 TLS 핸드셰이크예요. 프록시는 여러분이 터널에 등록한 CA가 서명한 서버 인증서를 제시해요. 개인 키를 여러분만 보유하므로 전송 공급자가 요청·응답 페이로드를 읽을 수 없어요. 내부 TLS 핸드셰이크
업스트림 MCP 서버 (Upstream MCP server) 프록시가 라우팅하는, 사설 네트워크에서 실행되는 MCP 서버예요. 각 업스트림은 터널 도메인 아래의 하나의 하위 도메인으로 노출돼요. 업스트림, 라우팅된 MCP 서버, 터널링된 MCP 서버

자격 증명 프로비저닝 (Credential provisioning)

터널 스택은 런타임에 두 가지 자격 증명이 필요해요. cloudflared의 아웃바운드 연결을 인증하는 터널 토큰, 그리고 내부 TLS 핸드셰이크에서 프록시가 제시하는, 터널에 등록된 CA가 서명한 서버 인증서예요. 이 가이드 전반에 걸쳐 한 쌍의 탭으로 제시되는 두 가지 공급 방식이 있어요.

모드 자격 증명이 스택에 도달하는 방식 Helm 차트 이름 탭 라벨
프로그래매틱 액세스 (Programmatic access) 설정 구성 요소가 Workload Identity Federation을 통해 Tunnels API에 인증하고, 터널 토큰을 가져오고, CA와 서버 인증서를 로컬에서 생성하고, CA를 등록해요. 장기 보관 비밀을 손으로 복사하지 않아요. workspace:manage_tunnels 스코프가 있는 페더레이션 규칙이 필요해요. 관리형 모드 (setup.enabled: true, 기본값) 프로그래매틱 액세스 사용
수동 (Manual) Claude Console에서 터널 토큰을 복사하고, CA와 서버 인증서를 직접 생성하고(예: openssl 사용), Console에서 CA를 등록하고, 토큰과 인증서를 비밀로서 스택에 제공해요. 설정 구성 요소는 실행되지 않아요. 외부 모드 (setup.enabled: false) 프로그래매틱 액세스 미사용

이 모드들은 배포 가이드에서 프로그래매틱 흐름(programmatic flow) 과 수동 흐름(manual flow) 으로도 불려요.

연결 모델 (Connection model)

터널에는 두 방향이 작동하며, 이들은 서로 반대 방향을 가리켜요:

  • 연결 방향 (Connection direction): cloudflared가 네트워크에서 터널 엣지로 아웃바운드로 연결을 시도해요. 방화벽에는 포트 7844의 이그레스(egress)만 보이고 인바운드 포트는 열리지 않아요.
  • 요청 방향 (Request direction): 연결이 수립되면 MCP 요청이 그 위에서 Anthropic에서 여러분의 네트워크 쪽으로 이동해요. cloudflared를 거쳐 프록시로, 그리고 업스트림 MCP 서버로 이어져요.

"아웃바운드 전용(outbound-only)"이라는 말은 연결을 뜻하며, 그 위로 운반되는 요청을 뜻하는 게 아니에요.

내부 TLS는 Anthropic의 백엔드와 여러분의 프록시 사이에 걸쳐 있어요. cloudflared와 터널 엣지는 그 사이의 전선상에 있지만 암호문만 볼 수 있어요. 프록시는 여러분의 네트워크 안에서 MCP 요청 페이로드를 읽을 수 있는 첫 번째 위치예요.

sequenceDiagram
  participant A as Anthropic<br/>backend
  participant E as Tunnel edge<br/>(Cloudflare network)
  participant C as cloudflared
  participant P as Proxy
  participant M as Upstream<br/>MCP server

  note over C,M: Inside your network

  C->>E: 1. Outbound connection (port 7844)
  note over C,E: Connection stays open.<br/>No inbound port is opened.

  A->>E: 2. MCP request (outer mTLS)
  E->>C: carried over the open connection
  C->>P: localhost:8080
  note over A,P: Inner TLS spans Anthropic backend to proxy.<br/>Terminates at the proxy.
  P->>M: 3. Route by hostname
  M-->>P: response
  P-->>A: response (same path, reversed)

더 알아보기 (Learn more)