메시지MCP 터널

MCP 터널 빠른 시작

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

MCP 터널은 리서치 프리뷰 단계입니다. 사용해 보시려면 액세스를 요청하세요.

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

구축할 내용

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

필요한 것

아웃바운드 인터넷 접근이 가능한 머신의 Docker 및 Docker Compose.
MCP 터널을 관리할 수 있는 Claude Console의 역할. Console 가이드 사전 요구 사항을 참조하세요.
OpenSSL 1.1.1 이상. macOS와 대부분의 Linux 배포판에는 사전 설치되어 있으며, Windows에서는 별도로 설치해야 합니다(openssl 바이너리가 PATH에 있어야 합니다).

터널 생성
Claude Console 사이드바에서 Manage > MCP tunnels로 이동하여 New tunnel을 클릭합니다. 이름을 지정합니다. Set up programmatic access는 끈 상태로 둡니다. 이 빠른 시작은 수동 자격 증명 프로비저닝을 사용합니다.
생성된 후 터널을 엽니다. Connection 섹션에서 두 가지 값을 복사합니다:
- Domain (abcd1234.tunnel.anthropic.com과 같은 형태)
- Token (눈 아이콘을 클릭한 다음 복사)

배포 디렉터리 설정

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

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를 업로드합니다(또는 그 내용을 붙여넣습니다). 터널 상태가 Active로 전환됩니다.

샘플 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

프록시 구성 및 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:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    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

시작하기
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 라인 네 줄이 표시되어야 합니다. 컨테이너가 시작되는 데 몇 초가 걸립니다. 로그 명령이 비어 있는 결과를 반환하면 다시 실행하세요.
Claude에서 호출하기
Console에서 Managed Agents > 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?

구축할 내용

필요한 것

아웃바운드 인터넷 접근이 가능한 머신의 Docker 및 Docker Compose.

MCP 터널을 관리할 수 있는 Claude Console의 역할. Console 가이드 사전 요구 사항을 참조하세요.

OpenSSL 1.1.1 이상. macOS와 대부분의 Linux 배포판에는 사전 설치되어 있으며, Windows에서는 별도로 설치해야 합니다(openssl 바이너리가 PATH에 있어야 합니다).

터널 생성
Claude Console 사이드바에서 Manage > MCP tunnels로 이동하여 New tunnel을 클릭합니다. 이름을 지정합니다. Set up programmatic access는 끈 상태로 둡니다. 이 빠른 시작은 수동 자격 증명 프로비저닝을 사용합니다.
생성된 후 터널을 엽니다. Connection 섹션에서 두 가지 값을 복사합니다:
- Domain (abcd1234.tunnel.anthropic.com과 같은 형태)
- Token (눈 아이콘을 클릭한 다음 복사)

배포 디렉터리 설정

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

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

샘플 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

프록시 구성 및 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:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    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

시작하기
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 라인 네 줄이 표시되어야 합니다. 컨테이너가 시작되는 데 몇 초가 걸립니다. 로그 명령이 비어 있는 결과를 반환하면 다시 실행하세요.
Claude에서 호출하기
Console에서 Managed Agents > Sessions로 이동하여 세션을 생성합니다. 에이전트 선택기에서 Create new agent를 선택하고, 에이전트에 이름을 지정하고, 미리 채워진 모델을 유지합니다. + MCP Server를 클릭하고, 터널을 선택한 다음, Subdomain을 echo로, Path를 mcp로 설정합니다. 그런 다음 다음과 같이 요청합니다:

Use the hello tool to greet tunnel.

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

다음 단계

프로덕션 배포의 경우:

Was this page helpful?

구축할 내용

필요한 것

다음 단계

구축할 내용

필요한 것

다음 단계

구축할 내용

필요한 것

다음 단계

구축할 내용

필요한 것

다음 단계