# MCP Hub 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 등) 으로 **정상 접근 가능해야 함**. 일반적으로 같은 사내망에 두면 자동으로 만족.

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

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

---

## 3. 설치 사전 준비

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

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

### WRKS 측에서 제공할 것

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

---

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

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

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

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

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

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

```bash
# 예: 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. 컨테이너 상태 확인

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

### 5-2. 로그 확인

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

### 5-3. Studio 확인

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

---

## 6. 업데이트 절차

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

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

### 업데이트 방법

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

```bash
# 예시 — 같은 컨테이너 이름 + 같은 볼륨 사용 → 인증서 / 페어링 정보 재사용
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 를 보관 중이라면 (이전 가이드대로 설치된 경우), 새 명령으로 처음 갈아끼울 때 한 번만 다음을 수행:

```bash
# 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 인증서** 가 들어있음. 이 볼륨을 실수로 삭제하면 **재페어링 (새 토큰 발급 + 재설치)** 필요.

```bash
# 안전한 백업 (주기적 권장)
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 에서 새 토큰 발급                                    |

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

```bash
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 담당자에게 연락