Connector 설치 가이드

대상: 고객사 관리자 (의사결정자) — 사내 개발자/인프라 담당자에게 작업을 안내하기 위한 문서 소요 시간: 최초 설치 약 15~30 분 (사내 방화벽 정책 협의 시간 별도)

1. 커넥터가 무엇인가요?

MCP Hub Connector 는 WRKS AI 가 사내 시스템 (ERP, 사내 DB, API 등) 을 안전하게 호출할 수 있도록 해주는 사내 환경에 설치하는 작은 게이트웨이 프로그램 입니다.

[ WRKS AI / mcp-hub.wrks.ai ]   ←──── HTTPS 아웃바운드 ─────   [ 커넥터 (Docker) ]
                                     (mTLS 암호화 터널)              ↓
                                                            [ 사내 시스템 (DB, ERP 등) ]

보안 보장

항목	보장 내용
방화벽 inbound 포트 개방 X	커넥터가 우리(WRKS) 에 먼저 접속 (outbound only). 외부에서 사내로 들어오는 포트 안 열어도 됨
데이터 저장 X	우리 서버에 데이터 영구 저장 안 함. 매 호출마다 커넥터가 사내 DB / ERP 에서 즉시 조회 후 응답
상호 인증 (mTLS)	커넥터 ↔ Hub 사이는 인증서 기반 양방향 인증. 도청/위변조 불가
자격증명 사내 보관	DB 비밀번호 같은 자격증명은 커넥터 내부의 secrets 파일 에만 존재. Hub 에는 `${VAR}` placeholder 만 저장

2. 어디에 설치해야 하나요?

권장 위치

위치	권장 여부	이유
사내망 일반 서버 (DB / ERP 와 같은 네트워크)	✅ 가장 권장	사내 시스템 접근이 자연스러움. 외부 인터넷 outbound 만 허용되면 OK
DMZ	△ 가능	DMZ → 사내 시스템 방화벽 룰 추가 협의 필요. 보안팀과 상의
NAT 뒤 사내망	✅ 권장	NAT 가 outbound 만 허용해도 동작 (커넥터가 먼저 우리 쪽에 접속)
클라우드 (AWS / Azure 등) VPC 내부	✅ 권장	사내 시스템과 VPN/Direct Connect 가 연결돼 있으면 사내망과 동일 취급
개인 PC / 노트북	❌ 비권장	24/7 가동 보장 어려움. 서버에 설치

네트워크 요구사항

Outbound (커넥터 → 외부)

대상	포트	용도	필수 여부
`mcp-hub.wrks.ai`	443 (HTTPS)	Hub 와의 mTLS 터널	필수
`ghcr.io`	443 (HTTPS)	커넥터 Docker 이미지 다운로드 (최초 1회 + 업데이트 시)	최초 + 업데이트 시

Inbound (외부 → 커넥터)

없음. 사내 방화벽에 추가 인바운드 포트 개방 불필요.

사내망 → 커넥터 → 사내 시스템

커넥터가 설치된 호스트에서 노출하고자 하는 사내 시스템 (DB, ERP API 등) 으로 정상 접근 가능해야 함. 일반적으로 같은 사내망에 두면 자동으로 만족.

사내 보안팀과 협의가 필요한 항목

outbound 443 (mcp-hub.wrks.ai, ghcr.io) 허용 여부
(DMZ 선택 시) DMZ → 사내 시스템 방화벽 룰
proxy 사용 환경이면 HTTPS_PROXY 환경변수 설정 필요 (담당 개발자에게 별도 안내)

3. 설치 사전 준비

사내 개발자/인프라 담당자에게 요청할 것

Docker 가 설치된 서버 1 대 (사내망 또는 VPC 내부)
- Linux (Ubuntu / RHEL 등) 권장
- Windows / macOS 의 Docker Desktop 도 가능하나 24/7 가동 어려움
- 최소 사양: 2 vCPU / 2 GB RAM / 5 GB 디스크
위 네트워크 요구사항 충족 확인
사내 시스템 자격증명 1 세트 (예: DB 비밀번호) — 커넥터의 secrets 폴더에 저장될 값

WRKS 측에서 제공할 것

페어링 토큰 (pairing token) — Studio 화면의 "+ 새 커넥터 추가" 에서 발급. 1회용, 발급 후 30분 내 사용 권장
이 가이드 문서

4. 설치 명령어 (사내 개발자에게 전달)

4-1. 페어링 토큰 발급 절차 (관리자가 Studio 에서 수행)

Studio (https://mcp-studio.wrks.ai) 접속 → "커넥터" 메뉴
우측 상단 "+ 새 커넥터 추가" 클릭
커넥터 이름 입력 (예: erp-main, db-prod)
환경 선택 (Linux / Docker Desktop) — 사내 개발자에게 확인
발급된 docker 명령어 그대로 복사 → 사내 개발자에게 전달

4-2. 사내 개발자가 받는 명령어 (예시)

이 명령어는 Studio 에서 자동 생성됩니다. 아래는 형식 예시.

docker run -d \
  --name mcp-connector-erp-main \
  --restart unless-stopped \
  -e MCP_HUB_URL=wss://tunnel-mcp-hub.wrks.ai/tunnel \
  -e MCP_HUB_PAIR_URL=https://mcp-hub.wrks.ai/connectors/pair \
  -e MCP_HUB_PAIRING_TOKEN=<발급된 토큰> \
  -v mcp-hub-connector-state-erp-main:/connector-state \
  -v /etc/mcp-connector/secrets:/var/secrets:ro \
  ghcr.io/chain-partners/mcp-hub-connector:0.2.3

옵션 의미:

--name: 컨테이너 이름 (Studio 의 커넥터 이름과 매핑)
--restart unless-stopped: 서버 재부팅 / Docker 재시작 시 자동 재시작
MCP_HUB_URL / MCP_HUB_PAIR_URL: WRKS 서버 주소 (변경 불필요)
MCP_HUB_PAIRING_TOKEN: 1회용 페어링 토큰 (한번 페어링 끝나면 더 이상 사용 안 됨, 자동 삭제됨)
-v mcp-hub-connector-state-...: 페어링 후 발급된 인증서 영구 보관 (이 볼륨이 사라지면 재페어링 필요)
-v /etc/mcp-connector/secrets:/var/secrets:ro: 사내 자격증명 파일 위치 (read-only 마운트)

4-3. 사내 자격증명 (secrets) 파일 만들기

페어링 토큰과 별도로, 사내 시스템 접속 자격증명을 커넥터 호스트의 파일 로 만들어 줍니다. 형식: KEY=VALUE 한 줄씩, .env 확장자.

🔒 secrets 디렉토리는 호스트에 미리 생성 — 처음 한 번만:
sudo mkdir -p /etc/mcp-connector/secrets
sudo chown $USER /etc/mcp-connector/secrets
이렇게 두면 Connector 컨테이너를 갈아끼워도 (docker rm + docker run) secrets 가 호스트에 그대로 남습니다.

# 예: ERP DB 자격증명
sudo tee /etc/mcp-connector/secrets/erp.env > /dev/null <<EOF
DB_PASSWORD=실제비밀번호
SAP_USER=sap_user
SAP_PASS=sap_password
EOF

sudo chmod 600 /etc/mcp-connector/secrets/erp.env

secrets 파일은 커넥터 호스트의 사내 보관 자격증명. WRKS 서버에는 절대 전송되지 않습니다. Studio 에서 baseUrl 을 postgres://user:${DB_PASSWORD}@host/db 식으로 등록하면, 커넥터가 dispatch 시점에 secrets 폴더에서 DB_PASSWORD 값을 찾아 치환합니다.

자격증명을 추가 / 변경 할 때는 secrets 폴더의 파일만 수정하면 됨 — 커넥터가 1초마다 폴더 변화를 감지해 자동 반영 (재시작 불필요).

5. 설치 확인

5-1. 컨테이너 상태 확인

docker ps --filter name=mcp-connector-
# STATUS 가 "Up X minutes" 이어야 함

5-2. 로그 확인

docker logs --tail 20 mcp-connector-erp-main
# 정상 시: "paired connector_id=..." 또는 "resumed connector_id=..."
# 그 다음: "tunnel: connected"

5-3. Studio 확인

Studio 의 "커넥터" 페이지에서 해당 커넥터가 연결됨 상태로 보이면 완료.

6. 업데이트 절차

새 버전 출시 시 Studio 가 자동으로 알림:

Studio 의 "커넥터" 페이지 상단에 새 버전 출시 띠 배너 표시
미달 커넥터 행에 ⚠ v0.2.X 사용 가능 배지 + "업데이트" 버튼 강조

업데이트 방법

Studio 의 해당 커넥터 행에서 "업데이트" 버튼 클릭
모달에 표시된 docker 명령어 복사 (페어링 토큰 없는 새 버전 명령)
사내 개발자가 호스트에서 실행

# 예시 — 같은 컨테이너 이름 + 같은 볼륨 사용 → 인증서 / 페어링 정보 재사용
docker rm -f mcp-connector-erp-main
docker run -d \
  --name mcp-connector-erp-main \
  --restart unless-stopped \
  -e MCP_HUB_URL=wss://tunnel-mcp-hub.wrks.ai/tunnel \
  -e MCP_HUB_PAIR_URL=https://mcp-hub.wrks.ai/connectors/pair \
  -v mcp-hub-connector-state-erp-main:/connector-state \
  -v /etc/mcp-connector/secrets:/var/secrets:ro \
  ghcr.io/chain-partners/mcp-hub-connector:0.2.4   # <— 새 버전 태그

핵심: --name 과 -v 볼륨이 이전과 같으면 재페어링 불필요 (인증서 재사용). secrets 도 그대로.

다운타임: 약 5~10초 (재기동 시간). 그동안의 API 호출은 잠시 실패 후 재기동 후 자동 정상화.

한 번뿐인 마이그레이션 (옛 설치 → 새 명령으로 처음 전환할 때)

옛 Connector 가 anonymous volume 에 secrets 를 보관 중이라면 (이전 가이드대로 설치된 경우), 새 명령으로 처음 갈아끼울 때 한 번만 다음을 수행:

# 1) 호스트 secrets 디렉토리 생성
sudo mkdir -p /etc/mcp-connector/secrets
sudo chown $USER /etc/mcp-connector/secrets

# 2) 옛 컨테이너의 secrets 를 호스트로 백업
docker cp <컨테이너-이름>:/var/secrets/. /etc/mcp-connector/secrets/
ls /etc/mcp-connector/secrets   # *.env 파일들이 보이면 OK

# 3) 위 업데이트 docker rm -f + docker run 명령 실행

이후 업데이트 시엔 호스트 파일이 그대로 남아 추가 작업 불필요.

7. 운영 / 유의 사항

자동 업데이트는 하지 않습니다

이미지 태그를 :latest 같은 sticky 태그로 두지 마세요. WRKS 가 새 버전 출시해도 고객사 확인 후 명시적으로 업데이트 하는 정책. 안정성 / 변경 가시성 보장.

state 볼륨 보호

-v mcp-hub-connector-state-... 볼륨 안에는 페어링 후 발급된 사내 mTLS 인증서 가 들어있음. 이 볼륨을 실수로 삭제하면 재페어링 (새 토큰 발급 + 재설치) 필요.

# 안전한 백업 (주기적 권장)
docker run --rm -v mcp-hub-connector-state-erp-main:/data \
  -v $(pwd):/backup busybox tar czf /backup/state-backup.tgz /data

secrets 볼륨 권한

/etc/mcp-connector/secrets/ 디렉토리는 운영자 사용자 소유 (chown $USER) — 컨테이너는 :ro 마운트라 호스트 권한과 별개로 안전. 안의 *.env 파일들은 600 으로 두어 다른 사용자가 읽지 못하게.

로그 / 모니터링

컨테이너 로그: docker logs -f mcp-connector-...
실시간 상태 / 호출 로그 / 에러: Studio 의 운영 콘솔 (해당 커넥터 카드 클릭)
30초 주기 heartbeat — 30초 이상 응답 없으면 Studio 에 "연결 끊김" 표시 + 알림

재시작이 필요한 경우

상황	재시작 필요?
secrets 파일 추가 / 수정	❌ 자동 감지 (1초 내 반영)
docker / 호스트 재부팅	❌ `--restart unless-stopped` 가 자동
페어링 토큰 발급 직후 (최초 설치)	위 4-2 명령으로 시작
커넥터 업데이트	❌ 위 6번 docker rm/run 흐름
WRKS 가 fingerprint revoke 요청	재페어링 필요 (드물게 보안 사고 대응)

트러블슈팅

증상	원인 / 해결
`tunnel: error:getaddrinfo`	DNS 미작동 — 사내 DNS 설정 확인
`tunnel: error:ECONNREFUSED`	outbound 443 차단 — 방화벽 / proxy 확인
`tunnel: error:socket hang up` 반복	mcp-hub.wrks.ai 의 인증서 / DNS 일시 이슈 가능. 5분 뒤 자동 복구되는지 관찰
Studio 에 "연결 끊김" 표시	`docker ps` 로 컨테이너 살아있는지 → 죽었으면 `docker logs` → 명시적 에러 확인
`placeholder_unresolved: ${DB_PASSWORD}`	secrets 폴더에 해당 key 가 없거나 파일 권한 문제. `/etc/mcp-connector/secrets/` 안 확인
커넥터 페어링 시 `pairing token already used`	토큰 1회용이라 재발급 필요. Studio 에서 새 토큰 발급

컨테이너가 멈췄을 때 — 종료 코드 보는 법

docker inspect --format '{{.State.ExitCode}} {{.State.Status}}' mcp-connector-...

종료 코드	뜻	해야 할 일
`0`	정상 종료	없음 (직접 중지했거나 서버가 재부팅된 경우)
`1`	기동 실패	로그 맨 위 한 줄이 원인입니다. 대부분 페어링 토큰 누락 / 잘못된 주소
`10`	Hub 가 연결을 끊음	재페어링이 필요합니다. Studio 에서 새 토큰을 받아 위 4-2 명령으로 다시 시작하세요. 재페어링 전까지는 `--restart unless-stopped` 때문에 도커가 계속 다시 띄우고 곧바로 또 종료됩니다 — 로그에 같은 오류가 반복돼도 정상이며, 재페어링하면 멈춥니다
`20`	복구 불가한 내부 오류	컨테이너가 자동으로 다시 시작됩니다. 반복되면 로그의 `FATAL` 줄을 담아 문의해 주세요

8. 빠른 체크리스트

설치 전:

사내망 또는 VPC 안에 Docker 설치된 서버 1 대
outbound 443 (mcp-hub.wrks.ai, ghcr.io) 방화벽 허용
노출할 사내 시스템 (DB / ERP) 의 자격증명 확보
Studio 에서 페어링 토큰 발급 (사용자 본인)

설치:

secrets 폴더 / 파일 생성 (/etc/mcp-connector/secrets/*.env, 권한 600)
docker run 명령 실행 (Studio 가 생성한 그대로)
docker logs 로 "tunnel: connected" 확인
Studio 의 커넥터 페이지에서 "연결됨" 확인

운영 정착 후:

state 볼륨 주기적 백업 일정 정의
새 버전 출시 알림 시 업데이트 정책 정의 (예: 매월 첫 주)
사내 모니터링 시스템에 커넥터 컨테이너 헬스체크 등록 (선택)

9. 문의

기술 문의 / 사내 환경 특수성 검토: WRKS 담당자에게 연락