Claude Platform Docs
MessagesMCP 터널

MCP 터널 빠른 시작

로컬 Docker Compose 배포를 사용하여 Claude를 프라이빗 MCP 서버에 연결합니다.

이 빠른 시작은 아무것도 없는 상태에서 시작하여 Claude가 터널을 통해 프라이빗 MCP 서버를 호출하는 단계까지 안내합니다. 로컬 테스트를 위한 가장 짧은 경로인 수동 자격 증명 프로비저닝과 함께 Docker Compose를 사용합니다. 프로덕션 배포의 경우 Helm으로 배포 또는 Docker Compose로 배포를 참조하세요.

구축할 내용

두 개의 컨테이너로 구성된 터널 스택(프록시와 cloudflared)과 그 옆에서 실행되는 샘플 MCP 서버입니다. 모든 것이 실행되면, 공개 포트에서 수신 대기하는 것이 아무것도 없음에도 불구하고 Claude에서 https://echo.<your-tunnel-domain>/mcp로 샘플 서버에 접근할 수 있습니다.

필요한 것

  1. 터널 생성

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

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

    • Domain (abcd1234.tunnel.anthropic.com과 같은 형태)
    • Token (눈 아이콘을 클릭한 다음 복사)

  2. 배포 디렉터리 설정

    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

  3. CA 및 서버 인증서 생성

    프록시는 사용자가 제어하는 CA가 서명한 인증서를 사용하여 내부 TLS를 종료합니다. 둘 다 생성하세요:

    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

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

  4. 샘플 MCP 서버 작성

    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

  5. 프록시 구성 및 compose 파일 작성

    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

  6. 시작하기

    docker compose up -d
docker compose logs mcp-proxy | grep "route configured"
docker compose logs cloudflared | grep "Registered tunnel connection"

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

  7. Claude에서 호출하기

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

    Use the hello tool to greet tunnel.

    도구 호출과 그 결과가 표시되어야 합니다.

다음 단계

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

프로덕션 배포의 경우:

Docker Compose로 배포

프로그래매틱 액세스 유무에 관계없이 강화된 단일 호스트 배포.

Helm으로 배포

자동 자격 증명 관리를 갖춘 Kubernetes 배포.

Was this page helpful?