Webship 엔지니어링

AI 에이전트를 Webship의 MCP 서버에 안전하게 연결

TLS 1.3, 강력한 베어러 토큰, 루프백 바인딩, SSH 터널, 구성 검증 및 실제적인 인시던트 대응 체크리스트와 함께 Webship의 격리된 MCP 제어 평면을 설정하세요.

2026년 9월 10일에 게시됨

# AI 에이전트를 Webship의 MCP 서버에 안전하게 연결

웹 서버에 대한 MCP 연결은 채팅 위젯이 아닙니다. 이는 운영 인터페이스로, 프로덕션 상태를 점검하고, 라우팅 및 보안 정책을 변경하며, 인증서를 다시 로드하고, 정적 릴리스를 활성화하며, 플릿 변경을 조정하고, 서명된 Webship 업데이트를 설치할 수 있습니다.

적절히 처리하십시오: 특권 관리 API로서 다루십시오. 가장 안전한 Webship 설정은 MCP 리스너를 공개 데이터 평면에서 분리하고, 루프백에 바인딩하며, TLS 1.3와 강력한 베어러 토큰으로 보호하며, 인증된 SSH 터널을 통해 접근합니다.

이 가이드는 그 설정을 구축하고, 각 경계가 존재하는 이유를 설명하며, 편리함을 노출로 바꾸지 않고 운영할 수 있는 체크리스트를 제공합니다.

신뢰 경계에서 시작하세요

Webship의 공개 트래픽과 MCP 트래픽은 별도의 리스너를 사용합니다. MCP 제어 평면은 기본적으로 비활성화되어 있으며 일반 HTTP, HTTP/2, HTTP/3 또는 WebTransport 리스너와 절대 공유되지 않습니다. 활성화되면 전용 TLS 1.3 HTTP/1.1 엔드포인트를 통해 MCP를 제공합니다.

안전한 배포에는 네 가지 독립적인 통제 수단이 있습니다:

네트워크 도달 가능성: MCP 리스너는 공개 또는 사설 LAN 주소가 아닌 127.0.0.1에 바인딩됩니다.
전송 신원: 클라이언트는 자신이 신뢰하는 CA가 발급한 인증서를 검증합니다.
애플리케이션 인증: 모든 요청에는 하나의 강력한 베어러 토큰이 포함됩니다.
관리자 접근: 운영자는 인증된 SSH 계정과 터널을 통해 루프백 수신기에 접속합니다.

이러한 통제 중 어느 것도 다른 것을 대체하지 않습니다. 개인 네트워크 경로가 없는 TLS는 여전히 인증 표면을 노출합니다. 인증서 확인 없는 터널은 엔드포인트의 신원을 모호하게 만듭니다. 세계에서 읽을 수 있는 파일 안의 베어러 토큰은 비밀이 아닙니다.

인증서와 토큰을 준비하세요

내부 CA에서 전용 MCP 인증서를 발급하십시오. 아래에 표시된 터널의 경우, 인증서의 대체 이름(subject alternative names)에 localhost 및 127.0.0.1을 포함한 후, 발급 CA를 MCP 클라이언트 머신의 신뢰 저장소(trust store)에 설치하십시오. 보안이 취약한 TLS 옵션으로 신뢰 오류를 해결하지 마십시오.

공백 없이 최소 32바이트의 인쇄 가능한 ASCII로 이루어진 고유 토큰을 생성하세요. 32바이트의 무작위 값을 16진수로 인코딩하면 64개의 안전한 문자가 제공됩니다:

umask 077
openssl rand -hex 32

Webship는 현재 보호된 TOML 구성에서 MCP 토큰을 직접 읽습니다; token_file은 지원되지 않습니다. 결과를 Webship 서비스 계정과 그 관리 그룹만 읽을 수 있는 구성 파일에 저장하십시오. 토큰을 systemd 유닛, 셸 히스토리, 티켓, 채팅 메시지 또는 AI 모델에 전송된 프롬프트에 넣지 마십시오.

일반적인 Debian 호스트에서:

sudo chown root:webship /etc/webship/production.toml
sudo chmod 0640 /etc/webship/production.toml
sudo chown root:webship /etc/webship/mcp-cert.pem /etc/webship/mcp-key.pem
sudo chmod 0644 /etc/webship/mcp-cert.pem
sudo chmod 0640 /etc/webship/mcp-key.pem

서비스 사용자와 그룹을 설치 환경에 맞게 조정하십시오. 개인 키와 구성 파일은 Webship에서 읽을 수 있어야 하지만 관련 없는 계정에서는 읽을 수 없어야 합니다.

격리된 수신기를 활성화하세요

이 섹션을 활성 Webship 구성에 추가하세요:

[security.mcp]
enabled = true
listen = "127.0.0.1:9443"
token = "replace-with-your-generated-64-character-token"
allowed_ips = []
expose_remote = false

[security.mcp.tls]
cert = "/etc/webship/mcp-cert.pem"
key = "/etc/webship/mcp-key.pem"

빈 allowed_ips 목록은 엔드포인트를 열지 않습니다. 루프백 클라이언트는 기본적으로 허용됩니다. expose_remote = false는 의도된 경계를 명확히 합니다: 누군가 나중에 listen를 비루프백 주소로 변경하면, Webship는 제어 평면을 조용히 게시하는 대신 구성을 거부합니다.

Webship는 TLS가 없거나, 토큰이 없거나, 짧거나 공백이 포함된 토큰이 있거나, 인증서 경로가 비어 있는 활성화된 MCP 리스너도 거부합니다. 공개 플레이스홀더 토큰은 원격 노출 전에 거부됩니다.

다시 시작하기 전에 확인

MCP 리스너, TLS 신원 및 토큰 변경은 제어 평면을 재구성하므로 프로세스 재시작이 필요합니다. 먼저 전체 구성을 검증하십시오:

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
sudo systemctl restart webship
sudo systemctl status webship --no-pager

리스너가 루프백에서만 존재하는지 확인하십시오:

ss -ltn | grep '127.0.0.1:9443'

포트 9443을 호스트의 공용 방화벽 규칙에 추가하지 마십시오. 다음 단계에서는 SSH를 통해 접근합니다.

개인 터널을 만드세요

관리자 워크스테이션에서 로컬 포트를 Webship의 루프백 리스너로 포워딩합니다:

ssh -N \
  -L 127.0.0.1:19443:127.0.0.1:9443 \
  webship-admin@edge.example.com

MCP 클라이언트가 이제 https://localhost:19443/mcp에 연결됩니다. TCP가 SSH 서버에 도달하면, SSH가 연결을 호스트로 전달하고, 호스트는 최종적으로 루프백에서 Webship에 대한 연결을 엽니다. SSH 세션을 닫으면 해당 경로가 즉시 제거됩니다.

키 기반 SSH 인증을 사용하고, 터널을 열 수 있는 관리자를 제한하며, 일반적인 호스트 접근 제어를 적용하십시오. 점프 호스트가 필요한 경우, MCP 리스너를 Webship 호스트의 루프백 인터페이스에 유지하고, 리스너를 넓히는 대신 SSH 경로를 확장하십시오.

MCP 클라이언트를 구성합니다

클라이언트 구성 형식은 다르지만, 일반적인 HTTP MCP 항목은 다음과 같이 보입니다:

{
  "mcpServers": {
    "webship-production": {
      "url": "https://localhost:19443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

클라이언트에 보호된 비밀 메커니즘이 있는 경우 이를 사용하십시오. 그렇지 않으면 클라이언트 구성을 현재 운영 체제 계정으로 제한하십시오. HTTP 클라이언트가 모델이 아닌 권한 부여 헤더를 첨부해야 합니다. 라이브 토큰을 대화에 절대 붙여 넣지 마십시오.

인증서 검증을 계속 활성화 상태로 유지하십시오. 클라이언트가 인증서를 거부하면 인증서의 주체 대체 이름을 수정하거나 올바른 내부 CA를 설치하십시오. 영구적인 우회는 추가하지 마십시오.

첫 번째 세션을 읽기 전용으로 설정하세요

터널과 클라이언트가 연결된 후, 디스커버리 및 점검을 시작하십시오:

tools/list을 요청하세요; 그 응답은 실행 중인 릴리스에 대한 권위 있는 논증 스키마입니다.
webship.get_config를 호출하고 현재 구성 버전을 기록하십시오.
해당되는 경우 webship.reverse_proxy.get_status, webship.security.get_status, webship.ddos.get_status, 및 webship.tls.get_status을 점검하십시오.
정책을 변경하기 전에 webship.policy.explain 또는 webship.security.simulate를 사용하십시오.
반환된 구성에서 베어러 토큰이 삭제되는지 확인하십시오.

그때 비로소 비운영 환경에서 변이를 테스트하십시오. Webship의 구성 변이는 현재 버전 ID가 필요합니다. 오래된 쓰기는 최신 변경 사항을 덮어쓰는 대신 거부됩니다. 후보 정책은 활성화 전에 섀도우 검증 및 트래픽 실험 시나리오로 확인할 수 있습니다.

Webship는 또한 선택된 실시간 보안 다운그레이드를 거부합니다. MCP 요청은 활성화된 WAF, DDoS 레이어, API Shield, 봇 챌린지, 엣지 인증 정책 또는 응답 헤더 레이어를 끌 수 없습니다. 프로세스 바운드 리스너, 프로토콜, 워커, 런타임 및 MCP 인증 변경에는 신중한 재시작이 필요합니다.

그 경비원들은 실수를 줄이지만, 모든 승인된 행동을 무해하게 만들지는 않습니다. 이 토큰은 업데이트 및 릴리스 작업을 포함한 강력한 제어 권한을 부여합니다. 제안된 도구 호출을 검토할 때는 관리자의 셸 명령을 검토하는 것과 정확히 같은 방식으로 검토하십시오.

원격 바인딩이 불가피한 경우

루프백과 SSH를 함께 사용하는 것이 권장 설계입니다. 환경에서 프라이빗 네트워크 리스너가 필요하다면, 예외를 명확히 하십시오:

[security.mcp]
enabled = true
listen = "10.20.0.15:9443"
expose_remote = true
allowed_ips = ["10.20.10.0/24"]
token = "replace-with-your-generated-64-character-token"

앞서 예제의 TLS 블록을 유지하고, 개인 DNS 이름과 일치하는 인증서를 사용하며, 호스트 및 네트워크 방화벽에서 동일한 소스 범위를 적용하십시오. 편의를 위해 0.0.0.0/0 또는 ::/0를 허용 목록으로 사용하지 마십시오. 애플리케이션 허용 목록은 실제로 Webship에 도달하는 소스 주소를 보므로, 로드 밸런서, NAT 게이트웨이 또는 서비스 메시가 그 앞에 있는 경우 동작을 확인하십시오.

원격 노출은 중앙 집중식 접근 로그, 짧은 운영 창 및 빠른 회전의 가치를 높입니다. 단지 MCP 클라이언트가 다른 기기에서 실행된다고 해서 필요하지 않습니다. 그것이 바로 SSH 터널이 해결하는 문제입니다.

제어 평면을 신중하게 조작하십시오

제작을 위해 이 체크리스트를 사용하세요:

에이전트나 운영자가 필요하지 않은 곳에서는 MCP를 비활성 상태로 유지하세요.
기본적으로 루프백에 바인딩하고 SSH 터널을 사용합니다.
전용 TLS 아이덴티티를 사용하고 인증서 확인을 활성화 상태로 유지하세요.
각 Webship 환경에 대해 고유한 베어러 토큰을 생성하십시오.
파일 시스템 권한으로 TOML, 클라이언트 구성, TLS 키, SSH 키를 보호하십시오.
개발, 테스트 및 운영 자격 증명을 분리하십시오.
변경 사항 전에 상태 및 정책 시뮬레이션 도구로 세션을 시작하십시오.
Webship의 보안 감사 이벤트를 보존하고 검토하십시오.
토큰을 회전시키고 의심되는 노출 후 Webship를 재시작하십시오.
관리 세션이 끝나면 터널을 닫으세요.

사고 대응을 위해, 활성 터널을 종료하고 SSH 계정을 제한하며, 보호된 TOML에 있는 MCP 토큰을 교체하고, Webship을 재시작하며, 최근 보안 감사 및 구성 버전 기록을 검토하십시오. TLS 개인 키가 노출될 수 있는 경우, 동일한 재시작 과정에서 새 인증서와 키를 발급하십시오. 이후 이전 토큰을 테스트하고 거부되는지 확인하십시오.

컨트롤 플레인은 컨트롤 플레인으로 남아 있어야 한다

MCP는 에이전트가 실제 상태를 검사하고 검증된 변경 사항을 적용할 수 있도록 해주기 때문에 유용합니다. 이러한 작업을 공용 요청 경로를 통해 수행할 필요가 없습니다. 하지만 컨트롤 리스너가 다른 인터넷 엔드포인트가 되면 그 장점은 사라집니다.

경계를 단순하게 유지하세요: 별도의 리스너, 루프백 도달 가능성, 검증된 TLS, 하나의 보호된 인증 자격 증명, 인증된 터널, 버전이 확인된 변경 사항, 강력한 작업에 대한 인간 검토 프로세스. Webship은 프로토콜과 안전장치를 제공하며, 운영자가 누가 접근할 수 있는지 결정합니다.

이 가이드는 Webship 1.3.1 운영자 문서, 제공된 구성 예제, MCP 검증 및 전송 코드, 런타임 구성 보호 기능, 도구 카탈로그를 기반으로 합니다. 다른 릴리스에 적용하기 전에 현재 Webship 문서와 실행 중인 서버의 tools/list 응답을 검토하십시오.