네트워크 연결

머신 외부의 HTTP MCP client가 연결하려면 접근 가능한 HTTPS origin이 필요합니다. 이 페이지는 네트워크 라우팅을 설명하며 어떤 runtime을 선택할지는 다루지 않습니다.

client endpoint는 보통 /mcp로 끝납니다.

https://your-public-host.example.com/mcp

서버의 public base URL 설정에는 origin만 넣습니다.

LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://your-public-host.example.com

이 base URL에 /mcp를 포함하지 마십시오.

연결 옵션

옵션	사용 시점
Compose tunnel sidecar	내장 tunnel profile을 사용하는 Docker Compose
외부 tunnel	로컬 네트워크 밖에서 접근해야 하는 모든 runtime
Caddy	간단한 자동 TLS가 필요할 때
Nginx 또는 Nginx Proxy Manager	기존 Nginx 인프라가 있을 때
Traefik	기존 container-native 라우팅을 사용할 때

경로

전체 origin을 실행 중인 서버로 전달하십시오. 중요한 경로는 다음과 같습니다.

경로	용도
/mcp	MCP Streamable HTTP endpoint
/healthz, /readyz	상태 확인
/.well-known/...	client discovery metadata
/oauth/...	client 인증 흐름
/downloads/...	선택적 생성 파일 링크
/join/..., /remote/...	선택적 remote-worker 흐름

프록시 동작

프록시는 경로를 보존하고 request body를 전달하며 긴 response를 지원하고 지나치게 짧은 timeout을 피해야 합니다.

확인

curl -i http://127.0.0.1:8765/healthz
curl -i https://your-public-host.example.com/healthz

흔한 실수

실수	해결
ChatGPT에서 https://host/mcp 대신 https://host 사용	client endpoint에만 /mcp 추가
LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://host/mcp 설정	origin만 설정
/mcp만 라우팅	discovery 및 인증 경로도 작동하도록 전체 origin 라우팅
host runtime에서 너무 넓은 workspace 사용	좁은 workspace 또는 Docker 사용

권장 조합

Runtime	네트워크 패턴
서버의 Docker Compose	기존 reverse proxy 또는 Compose tunnel profile
가정용 머신의 Docker Compose	outbound tunnel
노트북의 VS Code extension	세션용 임시 tunnel
VM의 binary	VM 또는 네트워크 경계의 reverse proxy
Python/source 개발 서버	보통 localhost 전용
Stdio mode	HTTP 경로 없음. 로컬 MCP client 사용