Console에서 터널 관리하기

Console에서 터널 관리하기 (Manage tunnels in the Console)

이 페이지에서는 MCP 터널 배포의 Console 측면을 다뤄요. 터널 만들기, CA 인증서 등록, 터널 토큰 가져오기, 업스트림 MCP 서버를 에이전트에 연결하는 방법까지요. 네트워크 안에서 터널 스택을 실행하는 방법은 Helm으로 MCP 터널 배포하기와 Docker Compose로 MCP 터널 배포하기에서 다뤄요.

출처: 문서

본문

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

이 페이지에서는 MCP 터널 배포의 Console 측면을 다뤄요. 터널 만들기, CA 인증서 등록, 터널 토큰 가져오기, 업스트림 MCP 서버를 에이전트에 연결하는 방법까지 살펴볼게요. Helm으로 MCP 터널 배포하기와 Docker Compose로 MCP 터널 배포하기는 네트워크 안에서 터널 스택을 실행하는 방법을 다뤄요.

사전 준비 (Prerequisites)

  • 사설 네트워크에서 실행되는 하나 이상의 MCP 서버. 터널은 트래픽을 그들에게 라우팅하지, 호스팅하지 않아요. 배포할 수 있는 예시는 원격 MCP 서버를 참고하세요.
  • 터널 관리 권한(Manage tunnels permission)이 있는 Console 역할. 터널을 만들고 아카이브하고, 토큰을 순환하고, 인증서를 관리할 수 있어요. 조직 관리자와 소유자는 기본으로 가지며, 커스텀 역할과 계정별 권한에도 포함될 수 있어요. 이 권한이 없는 역할은 MCP tunnels 페이지와 터널 상세에 읽기 전용으로 접근해요.
  • 스택이 Tunnels API에 인증하는 방법. 하나를 선택하세요:

터널 만들기 (Create a tunnel)

  1. MCP tunnels 페이지 열기 — Console 사이드바에서 Manage > MCP tunnels로 가요. 터널은 워크스페이스 범위로 지정돼요. 새 터널은 Console에서 현재 선택된 워크스페이스에 속하므로, 다른 곳에 두고 싶다면 먼저 워크스페이스를 전환하세요.

  2. 터널 이름 정하기 — New tunnel을 클릭하고 Create tunnel 대화 상자에 이름을 입력해요. 이름은 필수이며 목록, 상세 페이지, 에이전트 MCP 서버 선택기에서 터널을 식별해요. abcd1234.tunnel.anthropic.com 형태의 도메인이 자동 할당돼요.

  3. (선택) 프로그래매틱 액세스 설정하기 — 역할이 페더레이션 규칙을 관리할 수 있으면 Set up programmatic access 토글이 나타나요(기본 꺼짐). 아니면 Console이 그 자리에 공지를 보여주고 터널 스택은 수동 흐름을 사용해요. 생성 흐름의 나머지는 어느 쪽이든 같아요.

    프로그래매틱 액세스는 Workload Identity Federation에 의존해요. 페더레이션 발급자, 규칙, 서비스 계정이 낯설다면 먼저 그 페이지를 읽어보세요. 토글을 켜려면 다음이 필요해요:

    1. 스택이 토큰을 제시하는 ID 공급자를 위한 등록된 OIDC 발급자(Kubernetes 클러스터, AWS IAM, Google Cloud, GitHub Actions 등). 조직에 없는 경우 Settings > Workload identity > Issuers에서 하나 등록하세요.
    2. workspace:manage_tunnels 스코프가 있는 페더레이션 규칙. 토글을 켜면 Federation rule 선택기가 나타나요. 그 스코프가 있는 기존 규칙을 선택하거나 Create federation rule을 클릭해 인라인으로 만들 수 있어요.
    3. 규칙의 서비스 계정을 이 워크스페이스에 추가. Tunnels API는 서비스 계정의 워크스페이스 멤버십을 기준으로 권한을 부여해요. 조직 기본값이 아닌 다른 워크스페이스에서 터널을 만드는 경우 Settings > Workspaces에서 서비스 계정을 추가하고 배포 시 워크스페이스 ID를 전달하세요 (Helm은 api.wif.workspaceId, Compose는 ANTHROPIC_WORKSPACE_ID).

    이 단계를 건너뛰는 것은 완전히 지원돼요. 두 배포 가이드 모두 Without programmatic access 탭이 있어요.

  4. 터널 만들기 — Create tunnel을 클릭해요. Console이 터널을 프로비저닝하고 상세 페이지를 열어요.

  5. 배포 식별자 기록하기 — 두 배포 경로 모두 다음이 필요해요:

    • 터널 ID (tnl_...), 터널 상세 페이지에 표시돼요.
    • 터널 도메인 (abcd1234.tunnel.anthropic.com), 터널 상세 페이지에 표시돼요. 프록시의 tunnel_domain과 서버 인증서의 SAN으로 사용돼요.

    그 외에 필요한 것은 자격 증명 프로비저닝 모드에 따라 달라요:

    프로그래매틱 액세스 있음 프로그래매틱 액세스 없음
    선택한 규칙의 페더레이션 규칙 ID (fdrl_...). 규칙은 조직 수준이며 터널에 저장되지 않아요. Settings > Workload identity > Rules에서 찾아요. 터널 토큰, 상세 페이지의 Token 옆 눈 아이콘으로 공개돼요. 비밀로 취급하세요. 연결 세부 정보 가져오기를 참고하세요.
    조직 ID (UUID), Settings > Organization 아래에 표시돼요. 직접 생성해서 터널에 등록한 CA 인증서.

    프로그래매틱 액세스에서는 스택이 Tunnels API를 통해 터널 토큰을 가져오고, CA와 서버 인증서를 로컬에서 생성하며(개인 키는 환경을 벗어나지 않아요), CA의 공개 인증서만 Anthropic에 등록해요. 그래도 개인 키를 보호하고 서버 인증서를 만료 전에 갱신해야 하는 책임은 여러분에게 있어요.

조직은 활성 터널을 최대 10개까지 보유할 수 있어요. 터널을 만드는 것 자체는 연결을 수립하지 않아요. 스택이 터널 토큰으로 연결되고 CA 인증서가 등록된 후에야 연결이 일어나요.

연결 세부 정보 가져오기 (Get the connection details)

터널을 열면 상세 페이지에 Connection 섹션(도메인과 토큰)과 Certificates 섹션이 보여요.

필드 설명
Domain 할당된 abcd1234.tunnel.anthropic.com 값을 복사하세요. 프록시의 라우트는 이 도메인의 하위 도메인이에요.
Token 눈 아이콘(Show token)을 클릭해 터널 토큰을 가져온 다음 복사 아이콘으로 터널 스택의 비밀 저장소에 복사하세요. Rotate token을 클릭하면 현재 토큰을 무효화하고 새 토큰을 발급해요.

참고 (Note) 모든 공개와 순환은 조직의 Compliance API 활동 로그에 기록돼요. 순환은 이미 수립된 cloudflared 연결을 끊지 않으므로, 순환하고 새 값으로 재배포한 다음 옛 연결이 비워지게 둘 수 있어요.

CA 인증서 추가하기 (Add a CA certificate)

Anthropic은 터널에 등록한 CA 인증서를 기준으로 프록시로의 내부 TLS를 검증해요. 활성 인증서가 없는 터널은 연결을 받아들일 수 없고, 인증서가 등록되기 전까지 에이전트 MCP 서버 선택기에 나타나지 않아요.

  1. Certificates 섹션 찾기 — 터널 상세 페이지에서 Certificates 섹션으로 스크롤하고 Add certificate를 클릭해요.
  2. 인증서 제공하기 — Choose file을 클릭해 .pem, .crt, .cer 파일을 선택하거나, 파일을 텍스트 영역에 끌어다 놓거나, PEM 블록을 직접 붙여넣어요. 모달은 개인 키 자료와 -----BEGIN CERTIFICATE----- 블록이 아닌 내용을 거부해요. 파일은 8 kB 이하여야 해요.
  3. 인증서 추가하기 — Add certificate를 클릭해요. 지문과 만료가 인증서 목록에 나타나고 섹션 헤더의 슬롯 수가 증가해요.

터널은 활성 인증서를 최대 두 개까지 보유해서 무중단 순환이 가능해요. 새 인증서를 옛 인증서와 함께 등록하고, 프록시를 새 키 쌍으로 재배포하고, 트래픽이 흐르는지 확인한 다음 옛 인증서 행의 Revoke를 클릭하세요. 폐지된 인증서는 Revoked 배지와 함께 목록에 남아 보입니다.

터널 스택 배포하기 (Deploy the tunnel stack)

터널은 Console에 있지만, 네트워크 안에서 터널 스택이 실행되고 터널 토큰으로 연결될 때까지는 트래픽이 흐르지 않아요. 배포 가이드 중 하나를 따라보세요:

  • Docker Compose로 배포 — 단일 호스트에서 터널 스택 실행. 프로그래매틱 액세스 및 수동 흐름 모두.
  • Helm으로 배포 — Kubernetes 클러스터에서 터널 스택 실행. 프로그래매틱 액세스 및 수동 흐름 모두.

에이전트에서 터널 사용하기 (Use the tunnel in an agent)

스택이 실행 중이고 하나 이상의 MCP 서버가 구성되면 업스트림 MCP 서버를 Managed Agent 세션에 연결하세요. 대신 Messages API에서 같은 서버를 호출하려면 터널링된 MCP 서버 사용하기를 참고하세요.

참고 (Note) 선택기는 활성 인증서가 하나 이상 있는 터널만 보여줘요. MCP tunnels 목록에서 여전히 Needs certificate를 표시하는 터널은 드롭다운에 나타나지 않으니, 먼저 CA 인증서를 등록하세요. 선택기도 워크스페이스 범위라서 세션과 같은 워크스페이스의 터널만 나열해요.

  1. 새 세션 모달 열기 — Managed Agents > Sessions로 가 New session을 클릭해요.
  2. 인라인 에이전트 정의하기 — 에이전트 선택기에서 Create new agent를 선택해 MCP 서버 목록을 직접 편집할 수 있게 해요.
  3. MCP 서버 추가하기 — + MCP Server를 클릭하고 드롭다운을 열어요. 현재 워크스페이스에서 만든 터널이 공용 커넥터 카탈로그보다 목록 상단에 나타나요. 도달하려는 서버 앞에 있는 터널을 선택하세요.
  4. 라우팅 제공하기 — 카드에는 선택 필드 두 개가 보여요. Subdomain(터널 도메인 앞에 붙음)과 Path(그 뒤에 붙음). 프록시 라우트가 구성된 방식에 따라 하나 또는 둘 다 채우세요. Resolves to 줄이 에이전트가 연결하는 전체 MCP 서버 URL을 보여줘요.

참고 (Note) 터널은 트래픽을 운반하지, 업스트림 MCP 서버에 인증하지 않아요. 다른 MCP 서버와 같은 방식으로 MCP 서버에 OAuth나 베어러 인증을 구성하세요.

터널 아카이브하기 (Archive a tunnel)

아카이빙은 터널이 즉시 연결을 받아들이지 못하게 하며 영구적이에요.

MCP tunnels 목록에서 터널의 행 메뉴를 열고 Archive를 선택하세요. 아카이브된 터널은 목록을 Archived 또는 All로 필터하면 계속 보입니다.

더 알아보기 (Learn more)