---
title: MCP 터널
url: https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/overview
description: 인바운드 포트를 열거나 서비스를 공용 인터넷에 노출하지 않고도 프라이빗 네트워크에서 실행 중인 MCP 서버에 Claude를 안전하게 연결합니다.
---

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

<Note>
  MCP 터널은 리서치 프리뷰 단계입니다. 사용해 보려면 [액세스를 요청](https://claude.com/form/mcp-tunnels)하세요. MCP 터널은 가동 시간, 지원 또는 연속성에 대한 어떠한 약정 없이 "있는 그대로" 제공되며, 기반 전송 계층에 대해 가용성을 약정하지 않는 타사 네트워크 제공업체(Cloudflare)에 의존합니다. Anthropic은 언제든지 MCP 터널을 수정하거나 중단할 수 있습니다.
</Note>

Zero Data Retention 및 HIPAA BAA 적격성에 대해서는 [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#feature-eligibility)을 참조하세요.

## 작동 방식

[터널 스택](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)은 네트워크 내부에서 실행되는 두 가지 구성 요소로 이루어집니다:

* **[cloudflared](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components):** Cloudflare의 오픈 소스 터널 커넥터입니다. [터널 엣지](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)로 아웃바운드 전용 연결을 시작하고 Anthropic에서 프록시로 암호화된 트래픽을 전달합니다.
* **[프록시](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components):** Anthropic의 라우팅 구성 요소입니다. [내부 TLS](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)를 종료하고, 업스트림 IP가 허용된 범위 내에 있는지 검증하며, 호스트 이름을 기반으로 각 요청을 올바른 [업스트림 MCP 서버](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)로 라우팅합니다.

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

## 사전 요구 사항

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

* 배포 대상: Kubernetes 클러스터 또는 Docker와 Docker Compose가 설치된 VM.

* 터널. Claude Console에서 생성하거나([터널 생성](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/console#create-a-tunnel) 참조) API를 통해 생성합니다. Helm 차트의 설정 훅이 설치 중에 터널을 생성해 줄 수도 있습니다.

* 스택이 Tunnels API에 인증하는 방법. 다음 중 하나를 선택하세요:

  * **[프로그래매틱 액세스](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#credential-provisioning)(권장).** 터널을 생성할 때 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation)을 설정합니다. 스택이 ID 공급자로부터 단기 API 토큰을 발급하고, 터널 토큰을 가져오며, CA 인증서를 자동으로 생성하고 등록합니다. 페더레이션 규칙을 관리할 권한, 등록된 OIDC 발급자, 그리고 `workspace:manage_tunnels` 범위를 가진 페더레이션 규칙이 필요합니다.
  * **[수동](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** 정적 자격 증명을 직접 제공합니다: Console의 터널 토큰과 Console에 등록한 CA가 서명한 서버 인증서입니다. [연결 세부 정보 가져오기](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/console#get-the-connection-details) 및 [CA 인증서 추가](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate)를 참조하세요.

* 프라이빗 네트워크에서 실행 중인 하나 이상의 MCP 서버. 예시는 [원격 MCP 서버](https://platform.claude.com/docs/ko/agents-and-tools/remote-mcp-servers)를 참조하세요.

* [네트워크 요구 사항](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/overview#network-requirements)에 나열된 아웃바운드 연결.

### 네트워크 요구 사항

| 구성 요소       | 대상                                            | 포트 / 프로토콜      | 사용 시점         |
| ----------- | --------------------------------------------- | -------------- | ------------- |
| 설정 구성 요소    | `api.anthropic.com`                           | 443 TCP        | 프로비저닝 및 토큰 교체 |
| cloudflared | 터널 엣지(`198.41.192.0/19`, `2606:4700:a0::/44`) | 7844 TCP 및 UDP | 런타임           |
| 프록시         | 업스트림 MCP 서버                                   | 구성에 따름         | 런타임           |

## 보안 모델

### 보안 계층

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

| 계층                                    | 보호 대상                           |
| ------------------------------------- | ------------------------------- |
| Anthropic과 전송 제공업체 간의 외부 mTLS 및 IP 검증 | 권한 없는 클라이언트가 터널에 도달하는 것         |
| Anthropic 백엔드에서 프록시까지의 내부 TLS         | 전송 제공업체 또는 네트워크 중개자에 의한 페이로드 검사 |
| 각 MCP 서버의 OAuth                       | 인증된 터널 트래픽에 의한 MCP 도구의 무단 사용    |

터널 전송은 Cloudflare의 네트워크에서 실행됩니다. 프록시가 사용자만 보유한 인증서를 사용하여 내부 TLS를 종료하므로, Cloudflare는 요청 또는 응답 페이로드를 읽을 수 없습니다. Anthropic은 CA 인증서가 등록될 때까지 터널에 연결하지 않으므로, 페이로드는 Cloudflare의 네트워크를 통과할 때 항상 암호화됩니다. Cloudflare는 연결 메타데이터를 수신합니다. [전송 제공업체가 관찰할 수 있는 것](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/overview#what-the-transport-provider-can-observe)을 참조하세요.

### 공동 책임 모델

| Anthropic 담당                    | 조직 담당                                                            |
| ------------------------------- | ---------------------------------------------------------------- |
| 터널 액세스 제어                       | 터널을 통과하는 모든 콘텐츠 및 트래픽, 그리고 적용 가능한 제3자 허용 사용 정책(Cloudflare 포함) 준수 |
| 프록시에 연결하기 전 CA 인증서 검증           | 이 페이지들의 배포 지침 준수                                                 |
| Claude가 조직 소유의 터널에만 요청을 보내도록 보장 | 터널 토큰 및 TLS 개인 키 보안                                              |
|                                 | 서버 인증서 관리 및 만료 전 갱신                                              |
|                                 | 각 MCP 서버에 OAuth 구성                                               |
|                                 | 프록시 및 MCP 서버에 대한 네트워크 액세스 제한                                     |
|                                 | 침해가 의심되는 경우 Anthropic에 알림                                        |

<Warning>
  공격자가 터널 토큰**과** TLS 개인 키 중 하나를 획득하면, 프록시를 가장하여 MCP 요청 페이로드를 읽을 수 있습니다. 둘 다 고가치 비밀로 취급하세요. 강화 지침은 [MCP 터널 보안](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/security)을 참조하세요.
</Warning>

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

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

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

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

## 터널 배포

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

<CardGroup cols={2}>
  <Card title="빠른 시작" icon="rocket" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/quickstart">
    작동하는 터널로 가는 가장 짧은 경로: 샘플 MCP 서버와 함께 Docker Compose 사용.
  </Card>

  <Card title="Helm으로 배포" icon="stack" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/deploy-helm">
    Anthropic Helm 차트를 사용하여 Kubernetes 클러스터에 설치합니다.
  </Card>

  <Card title="Docker Compose로 배포" icon="cube" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/deploy-compose">
    Docker Compose를 사용하여 VM에 설치합니다.
  </Card>
</CardGroup>

선택 기준:

* **배포 대상**

  * Kubernetes에 배포하는 경우 **Helm**.
  * 단일 호스트 또는 로컬 테스트의 경우 **Docker Compose**.

* **설정을 위한 인증**

  * Kubernetes 클러스터, 클라우드 IAM 또는 SPIFFE와 같은 OIDC ID 공급자가 있는 경우 **프로그래매틱 액세스**(Workload Identity Federation을 통해).
  * 그렇지 않거나 테스트 중인 경우 **수동 자격 증명**.

## 터널링된 MCP 서버 사용

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

<Note>
  Console을 통해 생성된 MCP 터널은 claude.ai에서 커넥터로 사용할 수 없습니다.
</Note>

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

### Managed Agents (Console)

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

### Messages API

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

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

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: mcp-client-2025-11-20" \
    -d '{
      "model": "claude-opus-5-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"}]
    }'
  ```

  ```bash CLI
  ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
  model: claude-opus-5-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
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.beta.messages.create(
      model="claude-opus-5-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)
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic();

  const response = await anthropic.beta.messages.create({
    model: "claude-opus-5-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"]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 1000,
      Messages = new List<BetaMessageParam>
      {
          new() { Role = Role.User, Content = "Use the hello tool to greet tunnel." }
      },
      McpServers = new List<BetaRequestMcpServerUrlDefinition>
      {
          new()
          {
              Url = "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",
              Name = "echo"
          }
      },
      Tools = new List<BetaToolUnion>
      {
          new BetaMcpToolset("echo")
      },
      Betas = ["mcp-client-2025-11-20"]
  };

  var message = await client.Beta.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1000,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Use the hello tool to greet tunnel.")),
  	},
  	MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
  		{
  			URL:  "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",
  			Name: "echo",
  		},
  	},
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
  			MCPServerName: "echo",
  		}},
  	},
  	Betas: []anthropic.AnthropicBeta{
  		anthropic.AnthropicBetaMCPClient2025_11_20,
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaMcpToolset;
  // ...
  import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
  // ...

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1000L)
          .addUserMessage("Use the hello tool to greet tunnel.")
          .addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
              .url("https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp")
              .name("echo")
              .build())
          .addTool(BetaMcpToolset.builder()
              .mcpServerName("echo")
              .build())
          .addBeta("mcp-client-2025-11-20")
          .build();

      BetaMessage response = client.beta().messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1000,
      messages: [
          ['role' => 'user', 'content' => 'Use the hello tool to greet tunnel.']
      ],
      model: 'claude-opus-5-5',
      mcpServers: [
          [
              'type' => 'url',
              'url' => 'https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp',
              'name' => 'echo',
          ],
      ],
      tools: [
          [
              'type' => 'mcp_toolset',
              'mcpServerName' => 'echo',
          ],
      ],
      betas: ['mcp-client-2025-11-20'],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.create(
    model: "claude-opus-5-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"]
  )

  puts response
  ```
</CodeGroup>

업스트림 MCP 서버에 대한 인증(`authorization_token`) 및 기타 `mcp_servers` 옵션에 대해서는 [MCP 커넥터](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector)를 참조하세요.

## 다음 단계

<CardGroup cols={2}>
  <Card title="보안" icon="lock" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/security">
    강화 지침, 자격 증명 교체 및 침해 대응.
  </Card>

  <Card title="문제 해결" icon="wrench" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/troubleshooting">
    연결, TLS 및 라우팅 문제를 진단합니다.
  </Card>

  <Card title="레퍼런스" icon="book" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/reference">
    프록시 구성 필드, Tunnels API, 인증서 요구 사항 및 설정 구성 요소.
  </Card>

  <Card title="MCP 커넥터" icon="link" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector">
    Messages API에서 터널링된 서버를 사용합니다.
  </Card>
</CardGroup>