---
title: MCP 터널 빠른 시작
url: https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/quickstart
description: 로컬 Docker Compose 배포를 사용하여 Claude를 프라이빗 MCP 서버에 연결합니다.
---

<Note>
  MCP tunnels(MCP 터널)는 연구 프리뷰 단계입니다. 사용해 보려면 [액세스를 요청](https://claude.com/form/mcp-tunnels)하세요.
</Note>

이 빠른 시작은 아무것도 없는 상태에서 시작하여 Claude가 터널을 통해 프라이빗 MCP 서버를 호출하는 단계까지 안내합니다. 로컬 테스트를 위한 가장 짧은 경로인 [수동](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) 자격 증명 프로비저닝과 함께 Docker Compose를 사용합니다. 프로덕션 배포의 경우 [Helm으로 배포](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/deploy-helm) 또는 [Docker Compose로 배포](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/deploy-compose)를 참조하세요.

## 구축할 내용

두 개의 컨테이너로 구성된 [터널 스택](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)([프록시](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))과 그 옆에서 실행되는 샘플 MCP 서버입니다. 모든 것이 실행되면, 공개 포트에서 수신 대기하는 것이 아무것도 없음에도 불구하고 Claude에서 `https://echo.<your-tunnel-domain>/mcp`로 샘플 서버에 접근할 수 있습니다.

## 필요한 것

* 아웃바운드 인터넷 액세스가 가능한 머신에 설치된 [Docker 및 Docker Compose](https://docs.docker.com/get-docker/).
* MCP 터널을 관리할 수 있는 [Claude Console](https://platform.claude.com)의 역할. [Console 가이드 사전 요구 사항](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/console#prerequisites)을 참조하세요.
* [OpenSSL](https://openssl-library.org/source/) 1.1.1 이상. macOS 및 대부분의 Linux 배포판에는 사전 설치되어 있으며, Windows에서는 별도로 설치해야 합니다(`openssl` 바이너리가 `PATH`에 있어야 합니다).

<Steps>
  <Step title="터널 생성">
    Claude Console에서 [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) 페이지(`platform.claude.com/settings/workspaces/default/mcp-tunnels`)로 이동하세요. 각 터널은 하나의 워크스페이스에 속합니다. 사이드바의 워크스페이스 선택기에서 원하는 워크스페이스를 선택하세요. **New tunnel**을 클릭하고 이름을 지정하세요. **Set up programmatic access**는 끈 상태로 두세요. 이 빠른 시작 가이드는 수동 자격 증명 프로비저닝을 사용합니다.

    생성된 후 터널을 엽니다. **Connection** 섹션에서 두 가지 값을 복사합니다:

    * **Domain** (`abcd1234.tunnel.anthropic.com`과 같은 형태)
    * **Token** (눈 아이콘을 클릭한 다음 복사)
  </Step>

  <Step title="배포 디렉터리 설정">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash
        mkdir -p mcp-tunnel/{config,data}
        cd mcp-tunnel
        export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE   # from step 1
        export TUNNEL_TOKEN='eyJ...'            # from step 1
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell
        New-Item -ItemType Directory -Force -Path mcp-tunnel/config, mcp-tunnel/data | Out-Null
        Set-Location mcp-tunnel
        $env:TUNNEL_DOMAIN = "YOUR_TUNNEL_DOMAIN_HERE"   # from step 1
        $env:TUNNEL_TOKEN  = "eyJ..."             # from step 1
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="CA 및 서버 인증서 생성">
    프록시는 사용자가 제어하는 CA가 서명한 인증서를 사용하여 [내부 TLS](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)를 종료합니다. 둘 다 생성하세요:

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash
        openssl req -x509 -newkey rsa:2048 -nodes \
          -keyout data/ca.key -out data/ca.crt \
          -days 3650 -subj "/CN=mcp-tunnel-ca" \
          -addext "basicConstraints=critical,CA:TRUE" \
          -addext "keyUsage=critical,keyCertSign,cRLSign" \
          -addext "subjectKeyIdentifier=hash"

        cat > data/tls.ext <<EOF
        subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
        authorityKeyIdentifier = keyid,issuer
        extendedKeyUsage = serverAuth
        EOF

        openssl req -newkey rsa:2048 -nodes \
          -keyout data/tls.key -out /tmp/server.csr \
          -subj "/CN=${TUNNEL_DOMAIN}"
        openssl x509 -req -in /tmp/server.csr \
          -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
          -out data/tls.crt -days 90 -extfile data/tls.ext

        chmod 644 data/tls.key
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell
        openssl req -x509 -newkey rsa:2048 -nodes `
          -keyout data/ca.key -out data/ca.crt `
          -days 3650 -subj "/CN=mcp-tunnel-ca" `
          -addext "basicConstraints=critical,CA:TRUE" `
          -addext "keyUsage=critical,keyCertSign,cRLSign" `
          -addext "subjectKeyIdentifier=hash"

        @"
        subjectAltName = DNS:$env:TUNNEL_DOMAIN,DNS:*.$env:TUNNEL_DOMAIN
        authorityKeyIdentifier = keyid,issuer
        extendedKeyUsage = serverAuth
        "@ | Set-Content -NoNewline -Encoding ascii -Path data/tls.ext

        openssl req -newkey rsa:2048 -nodes `
          -keyout data/tls.key -out data/server.csr `
          -subj "/CN=$env:TUNNEL_DOMAIN"
        openssl x509 -req -in data/server.csr `
          -CA data/ca.crt -CAkey data/ca.key -CAcreateserial `
          -out data/tls.crt -days 90 -extfile data/tls.ext
        ```
      </Tab>
    </Tabs>

    Console로 돌아가서 터널 세부 정보 페이지에서 **Add certificate**를 클릭하고 `data/ca.crt`를 업로드합니다(또는 그 내용을 붙여넣습니다). 터널 이름 옆의 **Needs certificate** 배지가 사라집니다.
  </Step>

  <Step title="샘플 MCP 서버 작성">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash
        cat > hello_server.py <<'EOF'
        from mcp.server.fastmcp import FastMCP

        mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


        @mcp.tool()
        def hello(name: str = "world") -> str:
            """Say hello to someone."""
            return f"Hello, {name}!"


        if __name__ == "__main__":
            mcp.run(transport="streamable-http")
        EOF
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell
        @'
        from mcp.server.fastmcp import FastMCP

        mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


        @mcp.tool()
        def hello(name: str = "world") -> str:
            """Say hello to someone."""
            return f"Hello, {name}!"


        if __name__ == "__main__":
            mcp.run(transport="streamable-http")
        '@ | Set-Content -NoNewline -Encoding ascii -Path hello_server.py
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="프록시 구성 및 compose 파일 작성">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash
        cat > config/mcp-proxy.yaml <<EOF
        listen_addr: ":8080"
        tunnel_domain: ${TUNNEL_DOMAIN}
        tls:
          cert_file: /data/tls.crt
          key_file: /data/tls.key
        routes:
          echo: http://hello-mcp:9000
        EOF

        cat > docker-compose.yaml <<'EOF'
        services:
          mcp-proxy:
            image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
            volumes:
              - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
              - ./data:/data:ro
            restart: unless-stopped

          cloudflared:
            image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
            command: tunnel --no-autoupdate run --url http://localhost:8080
            environment:
              - TUNNEL_TOKEN
            network_mode: "service:mcp-proxy"
            restart: unless-stopped

          hello-mcp:
            image: python:3.13-slim
            working_dir: /app
            volumes:
              - ./hello_server.py:/app/hello_server.py:ro
            command: sh -c "pip install --quiet mcp && python hello_server.py"
            restart: unless-stopped
        EOF
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell
        @"
        listen_addr: ":8080"
        tunnel_domain: $env:TUNNEL_DOMAIN
        tls:
          cert_file: /data/tls.crt
          key_file: /data/tls.key
        routes:
          echo: http://hello-mcp:9000
        "@ | Set-Content -NoNewline -Encoding ascii -Path config/mcp-proxy.yaml

        @'
        services:
          mcp-proxy:
            image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
            volumes:
              - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
              - ./data:/data:ro
            restart: unless-stopped

          cloudflared:
            image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
            command: tunnel --no-autoupdate run --url http://localhost:8080
            environment:
              - TUNNEL_TOKEN
            network_mode: "service:mcp-proxy"
            restart: unless-stopped

          hello-mcp:
            image: python:3.13-slim
            working_dir: /app
            volumes:
              - ./hello_server.py:/app/hello_server.py:ro
            command: sh -c "pip install --quiet mcp && python hello_server.py"
            restart: unless-stopped
        '@ | Set-Content -NoNewline -Encoding ascii -Path docker-compose.yaml
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="시작하기">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash
        docker compose up -d
        docker compose logs mcp-proxy | grep "route configured"
        docker compose logs cloudflared | grep "Registered tunnel connection"
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell
        docker compose up -d
        docker compose logs mcp-proxy | Select-String "route configured"
        docker compose logs cloudflared | Select-String "Registered tunnel connection"
        ```
      </Tab>
    </Tabs>

    `echo`에 대한 `route configured` 줄 하나와 `Registered tunnel connection` 줄 네 개가 표시되어야 합니다. 컨테이너가 시작되는 데 몇 초가 걸리므로, 로그 명령이 빈 결과를 반환하면 다시 실행하세요.
  </Step>

  <Step title="Claude에서 호출하기">
    Console에서 [Sessions](https://platform.claude.com/sessions) 페이지(`platform.claude.com/sessions`)로 이동하여 세션을 생성하세요. 에이전트 선택기에서 **Create new agent**를 선택하고, 에이전트 이름을 지정한 다음, 미리 채워진 모델을 그대로 유지하세요. **+ MCP Server**를 클릭하고 터널을 선택한 다음, **Subdomain**을 `echo`로, **Path**를 `mcp`로 설정하세요. 그런 다음 다음과 같이 요청하세요:

    > Use the hello tool to greet tunnel.

    도구 호출과 그 결과가 표시되어야 합니다.
  </Step>
</Steps>

## 다음 단계

터널이 종단 간 검증되었습니다. 자체 MCP 서버로 교체하려면 `docker-compose.yaml`에 추가하고(또는 동일한 Docker 네트워크에서 실행하고), `config/mcp-proxy.yaml`에 해당 서버에 대한 라우트를 추가한 다음 프록시를 재시작하세요(`docker compose restart mcp-proxy`).

프로덕션 배포의 경우:

<CardGroup cols={2}>
  <Card title="Docker Compose로 배포" icon="cube" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/deploy-compose">
    프로그래매틱 액세스 유무에 관계없이 강화된 단일 호스트 배포.
  </Card>

  <Card title="Helm으로 배포" icon="stack" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/deploy-helm">
    자동 자격 증명 관리를 갖춘 Kubernetes 배포.
  </Card>
</CardGroup>