MessagesMCP 터널

MCP 터널 레퍼런스

Copy page



프록시 구성 필드, Tunnels REST API, 인증서 요구 사항 및 setup 컴포넌트에 대한 설명입니다.

프록시 구성

프록시는 /etc/mcp-gateway/config.yaml(Compose) 또는 렌더링된 ConfigMap(Helm, gateway.config.*에서 채워짐)에서 구성을 읽습니다.

https:// 업스트림 라우트의 경우, upstream.tls.ca_file 또는 upstream.tls.include_system_cas 중 하나 이상을 설정하세요. 그렇지 않으면 프록시에 업스트림 인증서에 대한 신뢰 앵커가 없게 됩니다.

라우트 매칭

routes는 리스트가 아닌 평면 문자열 맵(map[string]string)입니다. 프록시는 먼저 수신 호스트 이름을 정확히 일치하는 항목으로 조회한 다음, tunnel_domain 접미사를 제거하고 남은 서브도메인으로 매칭합니다. 매칭은 호스트 이름만 고려하며, 요청 경로와 쿼리 문자열은 변경 없이 업스트림 MCP 서버로 전달됩니다.

각 업스트림 값은 정확히 scheme://host:port 형식이어야 합니다. 포트는 필수입니다. 경로를 포함하면 구성 로드 시 invalid upstream (must be scheme://host:port) 오류와 함께 거부됩니다.

Tunnels API

Tunnels REST API는 /v1/tunnels에 위치하며 터널 생성, 목록 조회 및 보관, CA 인증서 등록, 터널 토큰 조회 또는 교체를 지원합니다. 모든 엔드포인트, 요청 및 응답 스키마, 예제는 Tunnels API 레퍼런스를 참조하세요.

모든 요청에 필요한 헤더:

인증서 요구 사항

setup 컴포넌트는 요구 사항을 준수하는 인증서를 자동으로 생성합니다. 이 요구 사항은 자체 PKI를 통해 인증서를 발급하는 경우에만 적용됩니다.

CA 인증서

POST /v1/tunnels/{tunnel_id}/certificates로 업로드합니다. 터널은 동시에 최대 두 개의 활성 CA 인증서를 보유할 수 있으며, 이를 통해 무중단 교체가 가능합니다.

• PEM 인코딩, 단일 인증서, 최대 8 kB.
• BasicConstraints 확장이 CA:TRUE로 존재하며 critical로 표시되어야 합니다.
• SubjectKeyIdentifier 확장이 존재해야 합니다.
• KeyUsage에 keyCertSign이 포함되어야 합니다.
• 유효 기간 내에 있어야 합니다.
• RSA 2048비트 이상 또는 ECDSA P-256 이상이며, SHA-256 이상의 서명을 사용해야 합니다.

서버 인증서

내부 TLS 중에 프록시가 제시합니다.

• 등록된 CA가 직접 서명해야 합니다(중간 인증서 없음).
• AuthorityKeyIdentifier 확장이 존재하며 CA의 SubjectKeyIdentifier와 일치해야 합니다.
• Subject Alternative Name에 <route>.<tunnel-domain>과 일치하는 DNS 이름이 포함되어야 합니다. 와일드카드 *.<tunnel-domain>은 모든 라우트를 포함합니다.
• ExtendedKeyUsage 확장이 존재하는 경우 serverAuth를 포함해야 합니다.
• 유효 기간 내에 있어야 합니다.
• RSA 2048비트 이상 또는 ECDSA P-256 이상이며, SHA-256 이상의 서명을 사용해야 합니다.

setup 컴포넌트는 5년 유효 기간의 ECDSA P-256 CA와 와일드카드 SAN 및 90일 유효 기간의 RSA 4096비트 서버 인증서를 생성합니다.

setup 컴포넌트

setup 컴포넌트는 mcp-proxy 이미지 내에 setup 바이너리로 포함되어 제공됩니다. docker compose run --rm setup <subcommand>(Compose)로 실행하거나 차트의 훅 및 CronJob(Helm)을 사용하세요.

setup init

기존 터널에 연결하거나(터널 ID가 제공되지 않은 경우 새로 생성), CA 및 서버 인증서를 생성하고, CA를 등록하고, 터널 토큰을 가져온 다음, 모든 출력을 대상 위치에 기록합니다.

이 명령은 Workload Identity Federation을 통해 인증합니다. ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_WORKSPACE_ID(선택 사항), 그리고 ANTHROPIC_IDENTITY_TOKEN_FILE 또는 ANTHROPIC_IDENTITY_TOKEN 중 정확히 하나를 읽습니다. 이러한 변수의 현재 의미는 WIF 레퍼런스를 참조하세요. setup 컴포넌트는 페더레이션 규칙에서 서비스 계정을 도출하므로 ANTHROPIC_SERVICE_ACCOUNT_ID를 별도로 요구하지 않습니다.

setup renew-cert

저장된 CA로 서명된 새 서버 인증서를 발급합니다. API 호출을 하지 않습니다.

--renew-before=720h로 설정하면 유효 기간이 30일 넘게 남아 있을 때 명령이 아무 작업도 수행하지 않으므로, 고정된 일정으로 실행해도 안전합니다.