MessagesMCP 터널

MCP 터널 문제 해결

터널 스택에서 연결, TLS, IP 검증 및 OAuth 라우팅 문제를 진단합니다.

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

터널을 통한 요청은 세 계층 중 하나에서 실패할 수 있습니다. 다음 순서로 진단하세요: 터널 엣지로의 아웃바운드 연결, Anthropic에서 프록시로의 내부 TLS, 그리고 업스트림 MCP 서버로의 라우팅 및 IP 검증.

빠른 참조

증상	원인	해결 방법
에이전트의 + MCP Server 선택기에 터널이 표시되지 않음	선택기는 세션의 워크스페이스에 있는 터널 중 활성 인증서가 하나 이상 있는 터널만 나열합니다.	CA 인증서를 등록하거나, 터널이 생성된 워크스페이스에서 세션을 여세요.
호출자에게 HTTP 500이 표시되고 cloudflared가 `No ingress rules were defined`를 로그에 기록함	cloudflared에 로컬 대상이 없습니다.	cloudflared 서비스에 `--url http://localhost:8080` 및 `network_mode: "service:mcp-proxy"`를 추가하세요.
프록시가 `no route for host`를 로그에 기록함	`tunnel_domain`이 할당된 도메인과 일치하지 않거나, 재시작 없이 `config.yaml`이 편집되었습니다.	`tunnel_domain`을 터널 상세 페이지에 표시된 정확한 도메인으로 설정한 다음 프록시를 재시작하세요(`docker compose restart mcp-proxy`).
프록시가 `IP validation failed: <ip> is not a private address`를 로그에 기록함	업스트림 MCP 서버가 RFC1918 범위 밖으로 해석됩니다.	업스트림 IP 검증을 참조하세요.
프록시가 `cannot unmarshal !!seq into map[string]string`으로 종료됨	`routes`가 YAML 리스트입니다.	`routes: { name: http://host:port }`를 사용하세요.
프록시가 `open /data/tls.key: permission denied`로 종료됨	키가 `0600`이며 프록시 컨테이너가 non-root로 실행됩니다.	`chmod 644 data/tls.key`를 실행하세요.
`curl https://<proxy>:8080`이 `wrong version number`로 실패함	예상된 동작입니다. 리스너는 평문 WebSocket이며 TLS는 WS 스트림 내부에서 발생합니다.	대신 Managed Agent 또는 Messages API를 통해 확인하세요.

다음 섹션에서는 한 줄 수정 이상이 필요한 실패 사례를 다룹니다.

소스 IP 허용 목록 뒤에서 OAuth 실패

인증 서버의 소스 IP 허용 목록이 Anthropic의 백엔드가 /token, /register 및 디스커버리 엔드포인트에 도달하는 것을 차단하면 OAuth 플로우가 실패합니다. Anthropic의 이그레스 범위를 허용 목록에 추가하고 싶지 않다면, 브라우저 대상 /authorize 엔드포인트는 기존 공개 호스트명에 유지하면서 백엔드 간 OAuth 호출을 터널을 통해 라우팅할 수 있습니다.

인증 서버에 대한 프록시 라우트 추가
routes: mcp: http://your-mcp-server:8080 auth: http://your-auth-server:8080
routes를 편집한 후 프록시를 재시작하세요(docker compose restart mcp-proxy 또는 helm upgrade).

분할 엔드포인트 디스커버리 메타데이터 제공

인증 서버의 /.well-known/oauth-authorization-server 응답은 authorization_endpoint를 기존 허용 목록에 있는 호스트명으로, 나머지는 모두 터널로 가리켜야 합니다:

{
  "issuer": "https://auth.<tunnel-domain>",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-domain>/token",
  "registration_endpoint": "https://auth.<tunnel-domain>/register",
  "code_challenge_methods_supported": ["S256"]
}

MCP 서버가 터널 발급자를 가리키도록 설정
MCP 서버의 /.well-known/oauth-protected-resource 응답은 터널 호스트명을 인증 서버로 참조해야 합니다:
{ "resource": "https://mcp.<tunnel-domain>", "authorization_servers": ["https://auth.<tunnel-domain>"] }

이 구성을 사용하면 사용자의 브라우저는 기존 호스트명(허용 목록에서 이미 허용됨)의 /authorize에 접근하고, Anthropic의 백엔드는 터널을 통해 /token, /register 및 디스커버리 문서에 도달합니다.

설정 컴포넌트 인증 실패

설정 컴포넌트(Helm Job 또는 Compose setup 서비스)는 페더레이션 규칙을 통해 OIDC JWT를 교환하여 Tunnels API에 인증합니다. 교환이 실패하면 Workload Identity Federation 참조의 실패한 교환 문제 해결을 참조하세요. 실패 모드(subject, audience, issuer, JWKS, lifetime)는 동일합니다.

터널 관련 원인:

차트의 기본 audience는 api.anthropic.com(스킴 없음)입니다. 규칙의 audience가 https://api.anthropic.com인 경우 api.wif.audience를 일치하도록 설정하세요.
교환 성공 후 Tunnels API에서 403이 반환되면 규칙의 스코프에 org:manage_tunnels가 포함되지 않았거나, 규칙의 서비스 계정이 터널의 워크스페이스 멤버가 아님을 의미합니다. 스코프를 설정하고 서비스 계정을 워크스페이스에 추가하세요.

Helm에서 설정 컴포넌트는 pre-install 훅 Job으로 실행됩니다. 실패 시 Job은 검사를 위해 남겨집니다(kubectl logs job/mcp-tunnel-setup -n mcp-tunnel). Helm은 훅 리소스를 관리하지 않으므로 재시도하기 전에 삭제하세요:

helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup

터널이 연결되지 않음

먼저 cloudflared 로그를 확인하세요. 일반적인 원인:

TUNNEL_TOKEN이 누락되었거나, 만료되었거나, 잘못 복사되었습니다.
방화벽이 터널 엣지로의 포트 7844 아웃바운드 TCP/UDP를 차단하고 있습니다.

cloudflared는 UDP 수신 버퍼 크기에 대한 경고를 로그에 기록할 수도 있습니다. 이는 QUIC 튜닝 힌트이며 오류가 아닙니다.

인증서 오류

내부 TLS 중 Anthropic이 프록시의 인증서를 거부하면 프록시는 tls handshake failed를 로그에 기록합니다. 다음을 확인하세요:

서버 인증서가 만료되지 않았습니다.
인증서의 Subject Alternative Name이 *.<tunnel-domain>과 일치합니다.
서명 CA가 이 터널에 대해 Anthropic에 등록되어 있습니다.

전체 검증 규칙은 인증서 요구 사항을 참조하세요.

업스트림 IP 검증

SSRF 보호를 위해 프록시는 기본적으로 RFC1918 사설 범위(10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)의 주소로만 연결합니다. 프록시에서 업스트림으로의 연결은 IPv4만 지원됩니다. (네트워크 요구 사항의 cloudflared에서 엣지로의 이그레스 범위는 다른 홉입니다.)

프록시가 IP validation failed: <ip> is not a private address를 로그에 기록하면 업스트림 호스트명이 해당 범위 밖으로 해석된 것입니다. Kubernetes에서 일부 관리형 배포판은 Service CIDR을 RFC1918 밖에 할당합니다. kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}'가 사설 범위 밖의 주소를 반환하면 클러스터의 Service CIDR을 조회하여 추가하세요.

주소가 정당한 경우 이를 포함하는 가장 좁은 CIDR을 upstream.allowed_ips에 추가하세요. allowed_ips를 설정하면 RFC1918 기본값을 확장하는 것이 아니라 대체하므로, 다른 업스트림 MCP 서버가 사용하는 사설 범위도 포함하세요:

config/mcp-proxy.yaml

upstream:
  allowed_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 127.0.0.0/8       # loopback, for local testing only

로컬 테스트 외에는 0.0.0.0/0을 사용하지 마세요. SSRF 보호가 완전히 비활성화됩니다.

Was this page helpful?

MessagesMCP 터널

MCP 터널 문제 해결

터널 스택에서 연결, TLS, IP 검증 및 OAuth 라우팅 문제를 진단합니다.

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

빠른 참조

증상	원인	해결 방법
에이전트의 + MCP Server 선택기에 터널이 표시되지 않음	선택기는 세션의 워크스페이스에 있는 터널 중 활성 인증서가 하나 이상 있는 터널만 나열합니다.	CA 인증서를 등록하거나, 터널이 생성된 워크스페이스에서 세션을 여세요.
호출자에게 HTTP 500이 표시되고 cloudflared가 `No ingress rules were defined`를 로그에 기록함	cloudflared에 로컬 대상이 없습니다.	cloudflared 서비스에 `--url http://localhost:8080` 및 `network_mode: "service:mcp-proxy"`를 추가하세요.
프록시가 `no route for host`를 로그에 기록함	`tunnel_domain`이 할당된 도메인과 일치하지 않거나, 재시작 없이 `config.yaml`이 편집되었습니다.	`tunnel_domain`을 터널 상세 페이지에 표시된 정확한 도메인으로 설정한 다음 프록시를 재시작하세요(`docker compose restart mcp-proxy`).
프록시가 `IP validation failed: <ip> is not a private address`를 로그에 기록함	업스트림 MCP 서버가 RFC1918 범위 밖으로 해석됩니다.	업스트림 IP 검증을 참조하세요.
프록시가 `cannot unmarshal !!seq into map[string]string`으로 종료됨	`routes`가 YAML 리스트입니다.	`routes: { name: http://host:port }`를 사용하세요.
프록시가 `open /data/tls.key: permission denied`로 종료됨	키가 `0600`이며 프록시 컨테이너가 non-root로 실행됩니다.	`chmod 644 data/tls.key`를 실행하세요.
`curl https://<proxy>:8080`이 `wrong version number`로 실패함	예상된 동작입니다. 리스너는 평문 WebSocket이며 TLS는 WS 스트림 내부에서 발생합니다.	대신 Managed Agent 또는 Messages API를 통해 확인하세요.

다음 섹션에서는 한 줄 수정 이상이 필요한 실패 사례를 다룹니다.

소스 IP 허용 목록 뒤에서 OAuth 실패

인증 서버에 대한 프록시 라우트 추가
routes: mcp: http://your-mcp-server:8080 auth: http://your-auth-server:8080
routes를 편집한 후 프록시를 재시작하세요(docker compose restart mcp-proxy 또는 helm upgrade).

분할 엔드포인트 디스커버리 메타데이터 제공

{
  "issuer": "https://auth.<tunnel-domain>",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-domain>/token",
  "registration_endpoint": "https://auth.<tunnel-domain>/register",
  "code_challenge_methods_supported": ["S256"]
}

MCP 서버가 터널 발급자를 가리키도록 설정
MCP 서버의 /.well-known/oauth-protected-resource 응답은 터널 호스트명을 인증 서버로 참조해야 합니다:
{ "resource": "https://mcp.<tunnel-domain>", "authorization_servers": ["https://auth.<tunnel-domain>"] }

설정 컴포넌트 인증 실패

터널 관련 원인:

차트의 기본 audience는 api.anthropic.com(스킴 없음)입니다. 규칙의 audience가 https://api.anthropic.com인 경우 api.wif.audience를 일치하도록 설정하세요.
교환 성공 후 Tunnels API에서 403이 반환되면 규칙의 스코프에 org:manage_tunnels가 포함되지 않았거나, 규칙의 서비스 계정이 터널의 워크스페이스 멤버가 아님을 의미합니다. 스코프를 설정하고 서비스 계정을 워크스페이스에 추가하세요.

helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup

터널이 연결되지 않음

먼저 cloudflared 로그를 확인하세요. 일반적인 원인:

TUNNEL_TOKEN이 누락되었거나, 만료되었거나, 잘못 복사되었습니다.
방화벽이 터널 엣지로의 포트 7844 아웃바운드 TCP/UDP를 차단하고 있습니다.

cloudflared는 UDP 수신 버퍼 크기에 대한 경고를 로그에 기록할 수도 있습니다. 이는 QUIC 튜닝 힌트이며 오류가 아닙니다.

인증서 오류

내부 TLS 중 Anthropic이 프록시의 인증서를 거부하면 프록시는 tls handshake failed를 로그에 기록합니다. 다음을 확인하세요:

서버 인증서가 만료되지 않았습니다.
인증서의 Subject Alternative Name이 *.<tunnel-domain>과 일치합니다.
서명 CA가 이 터널에 대해 Anthropic에 등록되어 있습니다.

전체 검증 규칙은 인증서 요구 사항을 참조하세요.

업스트림 IP 검증

config/mcp-proxy.yaml

upstream:
  allowed_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 127.0.0.0/8       # loopback, for local testing only

로컬 테스트 외에는 0.0.0.0/0을 사용하지 마세요. SSRF 보호가 완전히 비활성화됩니다.

Was this page helpful?