# MCP Hub Toolkit 사용 가이드

> **대상**: 고객사 관리자 / 사내 개발자 — Studio 에서 툴킷을 만들고 WRKS AI 에 연결해서 사용하는 전 과정
> **선행 조건**: 커넥터 설치 완료 ([Connector 설치 가이드](/guides/connector-installation) 참고)
> **소요 시간**: 단순 DB 툴킷 1개 기준 약 10~20 분

---

## 1. 툴킷 (Toolkit) 이 무엇인가요?

**툴킷** 은 사내 시스템 1개 (예: ERP DB 1개, 사내 REST API 1개) 를 **WRKS AI 가 호출할 수 있는 도구 묶음** 으로 등록한 단위입니다.

```
                          ┌─────────────────────────────────────────┐
                          │ Studio 에서 1개 툴킷 = 1개 사내 시스템 │
                          └─────────────────────────────────────────┘

WRKS AI ─ MCP 도구 호출 ─ Hub ─ 커넥터 (mTLS 터널) ─ 사내 DB / API
```

한 사내 시스템에 여러 도구 (예: 조회·집계·등록) 가 있어도 **툴킷 1개** 로 묶입니다.

### 툴킷 종류

| 종류              | 사례                                   | 작동 방식                                                                                   |
| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- |
| **HTTP 툴킷**     | 사내 REST API, SAP OData, ERP 외부 API | OpenAPI 명세 (JSON / YAML) 로 도구 자동 생성                                                |
| **Database 툴킷** | PostgreSQL / MySQL / MS SQL / Oracle   | `describe_schema` (스키마 조회) + `execute_query` (SELECT 실행) 두 가지 표준 도구 자동 제공 |

---

## 2. 사전 준비

1. **커넥터가 "연결됨" 상태** — Studio 의 "커넥터" 메뉴에서 확인
2. **사내 시스템 접속 정보** — DB 호스트/포트/DB명/사용자명, API base URL 등
3. **자격증명은 커넥터 호스트의 secrets 파일에 저장** — 비밀번호는 Studio 에 직접 입력 X (다음 섹션 참고)

> 자격증명 secrets 파일 만드는 법은 [Connector 설치 가이드](/guides/connector-installation) 의 4-3 절 참고.

---

## 3. 비밀번호 등 변수 (Secrets) 처리 원칙

**Studio 에 비밀번호를 평문으로 입력하지 마세요**. WRKS Hub 는 비밀번호를 저장하지 않고, **placeholder** 만 저장합니다. 실제 값은 커넥터가 호출 직전 사내 secrets 파일에서 치환합니다.

```
Studio 에 입력하는 값:   postgres://erp_user:${DB_PASSWORD}@db.internal:5432/erp
                                              ▲
                                       이 부분이 placeholder
                                       (변수명만 적음)

커넥터 호스트의 파일:   /etc/mcp-connector/secrets/erp.env
                       DB_PASSWORD=실제비밀번호값

→ 호출 직전 커넥터가 치환:
                       postgres://erp_user:실제비밀번호값@db.internal:5432/erp
                       (Hub 메모리에도 잠시도 머무르지 않음)
```

### Placeholder 규칙

| 형식                     | 사용처                           | 예시                                |
| ------------------------ | -------------------------------- | ----------------------------------- |
| `${변수명}`              | DB URL, HTTP 인증 헤더 등 어디든 | `${DB_PASSWORD}`, `${ERP_TOKEN}`    |
| 변수명 컨벤션            | 대문자 + 숫자 + 언더스코어       | `DB_PASSWORD` ✓ / `db-password` ✗   |
| 같은 변수 여러 곳 재사용 | OK                               | URL 과 인증 헤더 둘 다 `${API_KEY}` |

### secrets 파일 예시 (커넥터 호스트)

`/etc/mcp-connector/secrets/erp.env`:

```
DB_PASSWORD=Pa55word!2024
DB_USER=erp_readonly
ERP_TOKEN=Bearer-token-from-erp
SAP_USER=mcpuser
SAP_PASS=sap-password-123
```

> 파일명은 자유 (`erp.env`, `db.env`, `sap.env` 등). 폴더 안의 모든 `*.env` 가 자동 로드.

### 어떤 필드에 placeholder 를 쓸지 — 선택 정책

| 필드                          | 평문 입력 | placeholder 사용                              | 권장 |
| ----------------------------- | --------- | --------------------------------------------- | ---- |
| **비밀번호 / 토큰 / API Key** | ✗ (금지)  | ✅ **항상** placeholder (`${DB_PASSWORD}` 등) | ✅   |
| Host / Port / Database / User | ✅ (가능) | ✅ (선택 — `${DB_HOST}`, `${DB_NAME}` 등)     | 상황 |
| Base URL / OpenAPI URL        | ✅ (가능) | ✅ (선택)                                     | 상황 |

- **항상 placeholder**: 비밀번호 / 토큰 / API Key — 노출되면 보안 사고가 나는 값들. Hub DB 에 평문 저장 자체를 막아야 함.
- **선택**: Host / Database / User 등 토폴로지 정보 — 평문이어도 직접적인 보안 사고는 아니지만, **Hub DB 에 토폴로지가 그대로 저장되는 게 부담스러우면** 모두 placeholder 로 작성. 이 경우 secrets 파일에 같이 적어두면 됨.
- 두 방식은 **혼용 가능**. 예: Host 만 평문, 나머지는 placeholder.

> 정책 결정: 사내 보안팀이 토폴로지 평문 저장도 금지하면 "모두 placeholder", 그렇지 않으면 비밀번호만 placeholder 로 두고 나머지는 평문 — 둘 다 정상 동작합니다.

---

## 4. HTTP 툴킷 만들기 (REST API / SAP OData)

### 4-1. "+ 새 Toolkit" 시작

Studio 상단 메뉴 **"툴킷"** → 우측 상단 **"+ 새 Toolkit"** 클릭.

![툴킷 메인 페이지 + 새 Toolkit 버튼](screenshots/01-toolkits-main.png)

### 4-2. 기본 정보 입력

| 필드         | 입력값 예시                        | 설명                                                  |
| ------------ | ---------------------------------- | ----------------------------------------------------- |
| **종류**     | "HTTP" 선택                        | OpenAPI 명세 기반                                     |
| **이름**     | `erp-api`                          | 영문/숫자/하이픈. WRKS AI 가 도구 이름 prefix 로 사용 |
| **커넥터**   | 드롭다운에서 선택                  | 미리 설치한 커넥터                                    |
| **Base URL** | `https://erp.internal.company.com` | 사내 API base URL                                     |

### 4-3. OpenAPI 명세 입력

3가지 방법 중 택일:

| 방법                  | 언제 사용                                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **파일 업로드**       | OpenAPI JSON / YAML 파일이 있을 때                                                                                                 |
| **텍스트 붙여넣기**   | JSON 을 직접 복사                                                                                                                  |
| **URL 에서 가져오기** | API 가 swagger 같은 명세 endpoint 제공 시 (예: `https://erp.internal/api-docs-json`) — **커넥터를 통해 가져오므로 사내 URL 도 OK** |

> SAP ECC 사용 시: OData `$metadata` XML URL 을 그대로 입력하면 자동으로 OpenAPI 로 변환됩니다.

![HTTP 툴킷 생성 폼](screenshots/02-toolkit-http-form.png)

### 4-4. 인증 설정

Studio 인증 방식 라디오 순서 (실제 UI): **None → API Key (헤더 기반) → Basic Auth (사내 SAP / ECC) → OAuth (per-user, WRKS 중계) → OAuth Client Credentials (M2M)**.

| 인증 종류                          | 사용처                                                                                              | placeholder 예시                                |
| ---------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **None**                           | 인증 불필요한 API                                                                                   | —                                               |
| **API Key (헤더 기반)**            | `X-API-Key: xxx` 식                                                                                 | `${API_KEY}`                                    |
| **Basic Auth (사내 SAP / ECC)**    | `Authorization: Basic base64(user:pass)`                                                            | `${SAP_USER}` / `${SAP_PASS}`                   |
| **OAuth (per-user, WRKS 중계)**    | 사용자별 다른 토큰 — Hub 가 외부 OAuth 를 대행해서 사용자마다 다른 access_token 발급·저장·자동 갱신 | 하단 "OAuth per-user 툴킷 만들기" 참고          |
| **OAuth Client Credentials (M2M)** | 사용자 무관, 시스템 계정으로 API 호출 (예: Salesforce/Oracle APEX)                                  | `${OAUTH_CLIENT_ID}` / `${OAUTH_CLIENT_SECRET}` |

**"생성"** 버튼 클릭 → 툴킷 생성 + 도구 자동 추출 + 도구 목록 페이지 이동.

### 4-5. OAuth 두 방식 — 언제 어느 걸 쓰나요?

두 OAuth 방식은 **누구의 권한으로 API 를 호출하는가** 로 갈립니다.

| 항목                       | **OAuth per-user (`oauth_user`)**                          | **OAuth Client Credentials (`client_credentials`)**        |
| -------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
| 누구의 권한                | 사용자 (Alice, Bob …) 개인                                 | 시스템 계정 1개 (공용)                                     |
| 토큰 발급 시점             | Alice 가 처음 도구 호출 시 로그인 화면 → 승인              | Connector 가 시작 시 client_id/secret 으로 token 자동 발급 |
| 사용자별 데이터 격리       | 예 (Alice 는 자기 데이터만)                                | 아니오 (모두 같은 계정으로 조회)                           |
| 대표 예시                  | Google Drive (개인 문서), Salesforce (개인 리드)           | Oracle APEX API, Auth0 M2M, 내부 Salesforce 조회           |
| Studio 인증 방식 선택      | `OAuth (per-user, WRKS 중계)`                              | `OAuth Client Credentials (M2M)`                           |
| 실제 client_id/secret 보관 | Connector `secrets/*.env` (Hub 는 이름만)                  | Connector `secrets/*.env` (Hub 는 이름만)                  |
| WRKS AI 등록 시 인증 방식  | **OAuth (DCR)** 선택 — MCP URL 하나만 붙여넣으면 자동 등록 | **API Key** (커넥터가 만든 토큰이 알아서 헤더에 실림)      |

> **선택 팁**: "이 API 결과가 사용자마다 달라져야 하는가?" 예 → per-user. 아니오 → client_credentials. per-user 는 사용자마다 로그인 화면을 봐야 하고 토큰 저장·refresh 흐름이 복잡하니, 사용자 격리가 정말 필요할 때만.

### 4-6. OAuth per-user 툴킷 만들기 (`oauth_user`)

대상 시스템이 **사용자별로 다른 권한** 을 요구하는 경우 (예: 각 직원이 자기 Google
Drive 파일만 보게) 이 authType 을 씁니다. Hub 가 OAuth Authorization Server 역할을
맡아 사용자별로 외부 서비스 로그인 화면을 대행해 띄우고 access_token 을 발급·저장·
자동 갱신합니다.

Studio 툴킷 생성 시 **또는** 이후 툴킷 상세의 "인증" 섹션에서 **변경/편집** 가능.
인증 방식 **OAuth (per-user, WRKS 중계)** 선택 → 다음 6개 필드 입력:

![OAuth per-user 폼](screenshots/11-toolkit-oauth-user-form.png)

| 필드                              | 의미                                                                                                                    | 예시                                                                    |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Authorization endpoint URL** \* | 외부 OAuth 서비스의 승인 endpoint                                                                                       | `https://accounts.google.com/o/oauth2/v2/auth`                          |
| **Token endpoint URL** \*         | 외부 서비스의 code → token 교환 endpoint                                                                                | `https://oauth2.googleapis.com/token`                                   |
| **Scope** (선택, 공백 구분)       | 외부 서비스에서 요구하는 최소 권한. **Entra ID (M365) 는 `offline_access` 필수 포함** — 없으면 refresh_token 발급 안 됨 | `openid email profile drive.readonly`                                   |
| **Client ID placeholder** \*      | 외부 OAuth 앱의 Client ID 를 담을 **secret 이름** (실제 값 아님). `${VAR}` placeholder 규약                             | `${OAUTH_CLIENT_ID}` (또는 `${GOOGLE_CLIENT_ID}` 등 provider 별 접두어) |
| **Client Secret placeholder** \*  | 외부 OAuth 앱의 Client Secret 을 담을 secret 이름. 마찬가지로 placeholder                                               | `${OAUTH_CLIENT_SECRET}`                                                |
| **Userinfo endpoint URL** (선택)  | 사용자 profile 조회 endpoint. 발급된 토큰의 소유자 확인용                                                               | `https://openidconnect.googleapis.com/v1/userinfo`                      |

핵심 규칙 (반드시 지킬 것):

- **secret 값은 Studio 에 저장 안 함.** clientIdVar / clientSecretVar 는 이름
  (`${OAUTH_CLIENT_ID}` 등) 만. 실제 값은 커넥터의
  `/etc/mcp-connector/secrets/*.env` 파일에 한 줄로. §3 의 placeholder 규약과 동일.
- **외부 OAuth 앱의 Callback URL** 은 **엔드포인트 발급 후** 확인 가능. 발급 결과
  카드에 "사내 OAuth 앱 등록용" 섹션에서 `https://<hub>/oauth/<slug>/callback`
  형태로 표시. 이 URL 을 외부 OAuth 앱 (Google Cloud Console 의 "승인된
  리디렉션 URI" · Azure AD 의 "Redirect URI" 등) 에 미리 등록해야 사용자가
  로그인 화면에서 `redirect_uri_mismatch` 없이 진입 가능.
- Google 대응 시 Hub 이 자동으로 `access_type=offline` + `prompt=consent` 파라미터를
  붙여 refresh_token 을 확보합니다. **별도 설정 불필요.**
- 등록 후 WRKS AI 쪽 도구 등록 절차는 [WRKS AI 연동 가이드](/guides/wrks-ai-integration) §9
  "OAuth (per-user) 툴킷 등록" 참고.

secrets 파일 예 (커넥터 호스트):

```
# /etc/mcp-connector/secrets/google.env
OAUTH_CLIENT_ID=123456789.apps.googleusercontent.com
OAUTH_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxx
```

> 여러 provider 를 같은 커넥터에서 쓴다면 접두어로 구분: `OAUTH_GOOGLE_CLIENT_ID`, `OAUTH_AZURE_CLIENT_ID` 등. Studio 의 placeholder 도 그에 맞춰 지정.

### 4-7. Client Credentials 툴킷 만들기 (M2M)

Studio → "OAuth Client Credentials (M2M)" 선택 시 나오는 필드:

| 필드                      | 설명                                        | 예시                                        |
| ------------------------- | ------------------------------------------- | ------------------------------------------- |
| Token URL                 | 외부 OAuth 서비스의 token endpoint          | `https://accounts.example.com/oauth2/token` |
| Client 인증 방식          | Basic Auth 헤더 (권장) / Request Body       | Basic Auth 헤더                             |
| Client ID placeholder     | Connector env var 이름 (실제 값 아님)       | `${OAUTH_CLIENT_ID}`                        |
| Client Secret placeholder | 위와 동일                                   | `${OAUTH_CLIENT_SECRET}`                    |
| Scope (선택)              | 공백 구분, 외부 서비스가 요구하는 최소 권한 | `read:orders write:leads`                   |

> **Client 인증 방식 선택 팁**: 신규 등록은 **Basic Auth 헤더 (권장)** 로 시작.
> Oracle APEX ORDS · Ping · 대부분 사내 IdP 는 Basic 만 허용합니다. 저장 후에도
> `invalid_client` 오류가 계속 뜨면 **Request Body** 로 바꿔보세요 (Auth0 ·
> Salesforce 계열은 body 방식만 허용하는 경우도 있음). 이 옵션은
> **커넥터 v0.2.6 이상** 에서만 동작합니다.

저장 후 Connector `secrets/*.env` 에 실제 값 놓기:

```
OAUTH_CLIENT_ID=abc123
OAUTH_CLIENT_SECRET=xyz789
```

커넥터는 매 도구 호출 전 (또는 캐시된 token 만료 시) Token URL 로
`grant_type=client_credentials` 요청 → 받은 access_token 을 Authorization
헤더에 자동 실어 대상 API 로 forward. Hub / Studio 는 이 흐름에 개입하지
않음.

**WRKS AI 등록 시 인증 방식**: `API Key` 선택 (per-user 와 다름). Hub
엔드포인트는 그냥 static Bearer 로 노출되고, 사용자 매핑은 이 흐름에서
무의미합니다.

---

## 5. Database 툴킷 만들기

### 5-1. 공통 흐름

Studio 상단 메뉴 **"툴킷"** → **"+ 새 Toolkit"** → 종류 **"Database"** 선택.

| 필드                    | 설명                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **이름**                | 영문/숫자/하이픈. 자동으로 `db:` prefix 가 붙음 (예: `db:erp-prod`)                 |
| **커넥터**              | 사내망 안의 커넥터 선택                                                             |
| **Dialect**             | PostgreSQL / MySQL / MS SQL / Oracle DB 선택                                        |
| **Host**                | DB 호스트 주소 (커넥터 호스트에서 접근 가능해야 함). 평문 OR `${DB_HOST}`           |
| **Port**                | dialect 별 default 값 자동 채워짐 (5432 / 3306 / 1433 / 1521). 평문 OR `${DB_PORT}` |
| **Database**            | DB 이름 (또는 Oracle 의 SERVICE_NAME). 평문 OR `${DB_NAME}`                         |
| **User**                | DB 사용자명. **읽기 전용 권한 권장**. 평문 OR `${DB_USER}`                          |
| **비밀번호 (환경변수)** | **반드시 placeholder** — `${DB_PASSWORD}` (실제 값 입력 금지)                       |
| **SSL/TLS**             | 보통 "사용 (CA 검증 없음) — 권장 default" 선택                                      |

> 어떤 필드든 `${VAR}` 형식으로 placeholder 사용 가능. **비밀번호는 무조건 placeholder**, 나머지 (Host / Port / Database / User) 는 사내 정책에 따라 평문/placeholder 둘 다 OK — 자세한 정책은 §3 의 "어떤 필드에 placeholder 를 쓸지" 참고.

![DB 툴킷 생성 폼](screenshots/03-toolkit-db-form.png)

### 5-2. Dialect 별 입력 예시

#### PostgreSQL

| 필드     | 값                                               |
| -------- | ------------------------------------------------ |
| Host     | `pg-erp.internal`                                |
| Port     | `5432`                                           |
| Database | `erp`                                            |
| User     | `erp_readonly`                                   |
| 비밀번호 | `${DB_PASSWORD}`                                 |
| SSL      | 사용 (CA 검증 없음) — 사내 사설 인증서일 때 권장 |

> 미리보기에 표시되는 최종 baseUrl: `postgres://erp_readonly:${DB_PASSWORD}@pg-erp.internal:5432/erp`

#### MySQL

| 필드     | 값                   |
| -------- | -------------------- |
| Host     | `mysql-app.internal` |
| Port     | `3306`               |
| Database | `appdb`              |
| User     | `app_readonly`       |
| 비밀번호 | `${DB_PASSWORD}`     |
| SSL      | 사용 (CA 검증 없음)  |

#### MS SQL (SQL Server)

| 필드     | 값                                   |
| -------- | ------------------------------------ |
| Host     | `mssql-erp.internal`                 |
| Port     | `1433`                               |
| Database | `ERPProd`                            |
| User     | `erp_reader`                         |
| 비밀번호 | `${MSSQL_PASS}`                      |
| SSL      | disable / require / verify 환경 맞춰 |

> 비밀번호에 `@` 같은 특수문자가 있으면 secrets 파일에서 따옴표 처리 필요할 수 있음.

#### Oracle DB

| 필드     | 값                                          |
| -------- | ------------------------------------------- |
| Host     | `oracle-erp.internal`                       |
| Port     | `1521`                                      |
| Database | `ERPSVC` ← **SERVICE_NAME** (SID 가 아니라) |
| User     | `mcp_reader`                                |
| 비밀번호 | `${ORACLE_PASS}`                            |
| SSL      | disable (사내망) 또는 require (TCPS)        |

> 미리보기: `oracle://mcp_reader:${ORACLE_PASS}@oracle-erp.internal:1521/ERPSVC`
> 11g 이상 모든 버전 지원 (Thin 모드 자동, Instant Client 불필요).

### 5-3. 자동 생성되는 도구 2개

DB 툴킷은 **OpenAPI 명세 입력 불필요**. 자동으로 두 도구 생성:

| 도구 이름                       | 역할                                                                  |
| ------------------------------- | --------------------------------------------------------------------- |
| `db_<툴킷이름>_describe_schema` | DB 의 테이블 / 컬럼 / 타입 목록 반환. WRKS AI 가 SQL 만들기 전에 호출 |
| `db_<툴킷이름>_execute_query`   | 읽기 전용 (SELECT / WITH) SQL 실행. DDL / DML 자동 거부, 100 행 제한  |

> **DB 사용자 권한은 SELECT 만** 권장 — execute_query 가 코드 단에서 SELECT 만 허용하지만, DB 레벨에서도 보호하는 게 안전.

### 5-4. secrets 파일 확인

DB 툴킷 만든 직후 화면 하단에 안내 표시:

> `Connector 의 secrets 폴더에 다음 한 줄 추가하세요: DB_PASSWORD=실제비밀번호`

커넥터 호스트의 `/etc/mcp-connector/secrets/<파일>.env` 에 한 줄 추가하면 1초 내 자동 반영 (재시작 불필요).

---

## 6. 도구 (Tools) 페이지 — 만든 도구 살펴보기

생성된 툴킷 카드 → **"도구"** 탭 클릭.

![도구 탭](screenshots/04-toolkit-tools-tab.png)

표 항목:
| 컬럼 | 의미 |
|------|------|
| **slug** | WRKS AI 가 호출할 도구 이름 (예: `db_erp_prod_describe_schema`). 편집 가능 |
| **설명** | WRKS AI 가 도구 선택 시 참고하는 설명. **여기를 좋게 쓰면 AI 가 더 정확히 호출** |
| **파라미터** | 도구가 받는 인자 목록 |
| **활성** | 토글로 도구별 개별 on/off |
| **AI 추천** | ✨ 버튼 — 설명을 LLM 이 자동 개선 |

---

## 7. 도구 테스트 호출

도구 행의 **▶ 테스트** 버튼 → 모달이 열림.

![테스트 호출 모달](screenshots/05-mcp-test-dialog.png)

- **Tool**: 도구 드롭다운
- **Arguments (JSON)**: 인자 입력. DB describe_schema 는 `{}` 면 됨. execute_query 는 `{"sql": "SELECT 1"}` 식
- **호출** 버튼 → 실제 사내 시스템 호출 → 결과를 모달 하단에 표시

> 이 흐름은 WRKS AI 가 호출할 때와 **완전히 동일한 경로** (Hub → 커넥터 → 사내 시스템). 여기서 OK 면 AI 도 OK.

테스트 실패 시 확인:

- `connector_not_connected` — 커넥터 상태 (Studio 의 커넥터 페이지)
- `placeholder_unresolved: ${DB_PASSWORD}` — secrets 파일에 변수 누락
- DB 측 에러 (인증 실패, 호스트 도달 불가) — 커넥터 호스트에서 `psql / sqlcmd / sqlplus` 등으로 직접 접속 가능한지 점검

---

## 8. WRKS AI 에 MCP 도구로 연결하기

### 8-1. Endpoint 발급

툴킷의 **"엔드포인트"** 탭 → **"+ 새 엔드포인트"** 클릭.

발급 다이얼로그 상단에서 **인증 방식** 선택:

- **API Key** (static Bearer) — 대부분 툴킷 (DB · API Key · Basic · Client Credentials)
- **OAuth (per-user)** — 사용자별 로그인이 필요한 툴킷 (`oauth_user` authType 툴킷 한정)

![엔드포인트 발급](screenshots/06-endpoint-issue.png)

**API Key (static Bearer) 발급 결과:**

| 항목             | 의미                                                                                                  |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| **MCP URL**      | `https://mcp-hub.wrks.ai/mcp/<슬러그>` 형식. WRKS AI 가 호출할 endpoint                               |
| **Bearer Token** | 발급 직후 1회만 화면에 표시 — **반드시 안전한 곳에 저장**. 분실 시 재발급만 가능 (revoke + 새로 발급) |

**OAuth (per-user) 발급 결과:**

발급 결과 카드가 **3섹션으로 분리**되어 각 값을 어디에 써야 하는지 명확히 안내:

1. **권장 안내 배너** — WRKS AI 는 DCR 을 지원하므로 MCP URL 하나만 등록하면 자동. 나머지 표는 다른 MCP 클라이언트 (DCR 미지원) 를 위한 참고
2. **WRKS AI 등록용 (필수)** — **MCP URL** 하나. WRKS AI 는 이 값 하나만으로 metadata discovery + DCR 자동 처리
3. **사내 OAuth 앱 등록용** — **Callback URL** (`https://mcp-hub.wrks.ai/oauth/<슬러그>/callback`). Google Cloud Console · Azure AD 등의 "허용된 리디렉션 URI" 목록에 등록해야 함

> Authorize URL · Token URL 은 표준 discovery 로 자동 발견되므로 별도 표시하지 않습니다 (예전에는 표시했으나 사용자 혼동 유발로 숨김 처리).

### 8-2. WRKS AI 의 MCP 도구 등록

절차는 [WRKS AI 연동 가이드](/guides/wrks-ai-integration) 에 상세. 요약:

- **API Key 툴킷**: URL + Bearer Token 붙여넣기 → 저장
- **OAuth per-user 툴킷**: URL 만 붙여넣기 → 인증 방식 "OAuth (DCR)" 선택 → 저장. Client ID/Secret 은 자동 등록됨

저장 후 WRKS AI 가 자동으로 도구 목록 (`tools/list`) 을 받아옴. 채팅에서 "ERP 어제 매출" 같은 자연어로 질문하면 AI 가 해당 툴킷 도구를 자동 선택해 호출.

---

## 9. 자주 쓰는 운영 동작

### 9-1. 도구 설명 개선 (정확도 향상)

도구 행에서 **✨ AI 추천** 버튼 → Hub 의 LLM 이 OpenAPI spec / 파라미터 기반으로 자연어 설명 자동 생성. WRKS AI 가 도구 선택할 때 이 설명을 보고 판단하므로 **설명 품질 = AI 호출 정확도**.

### 9-2. 사용량 확인

툴킷 카드 → **"호출 로그"** 탭. 시간 / 사용자 / 도구 / 응답 상태 / 지연시간 별로 검색 가능.

### 9-3. 일시 중지 / 재개 (Kill Switch)

Studio 헤더의 **"⏸ 일시중지"** 버튼 — 해당 enterprise 의 모든 MCP 호출 즉시 차단. 사고 발생 시 응급 차단용. 재개도 동일 버튼.

### 9-4. Endpoint 회수 (Revoke)

엔드포인트 탭의 **🗑 회수** 버튼 → 그 URL/토큰 즉시 무효. 토큰 유출 시 응급 대응.

> **재발급 시 주의 (OAuth per-user):** 새 슬러그로 재발급하면 옛 슬러그는 즉시 무효. **WRKS AI 는 옛 URL 을 캐시**할 수 있어 도구 호출 시 `unknown_endpoint` 로 실패. 이 경우 WRKS AI 관리 UI 에서 이 도구를 **삭제 후 새 MCP URL 로 재등록** 필요 ([WRKS AI 연동 가이드](/guides/wrks-ai-integration) §9-5 참고).

---

## 10. 트러블슈팅

| 증상                                                                                                           | 원인 / 해결                                                                |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 툴킷 생성 시 `connector_not_active`                                                                            | 커넥터 미실행. `docker logs` 로 확인                                       |
| 테스트 시 `placeholder_unresolved: ${DB_PASSWORD}`                                                             | secrets 폴더에 변수 없음. `/etc/mcp-connector/secrets/*.env` 에 한 줄 추가 |
| 테스트 시 `connection refused: <host>`                                                                         | 커넥터 호스트에서 그 호스트로 네트워크 도달 X. ping / telnet 점검          |
| 테스트 시 SSL 관련 에러                                                                                        | SSL/TLS 옵션 조정 — 사내 자체서명 인증서면 "사용 (CA 검증 없음)"           |
| describe_schema 가 너무 많은 테이블 반환                                                                       | DB 사용자에게 특정 스키마만 권한 주기 (혹은 view 만 노출)                  |
| 응답이 100 행에서 끊김                                                                                         | 정상 동작 (안전 제한). 더 많은 데이터 필요시 SQL 의 WHERE 로 좁히기        |
| MCP 도구 호출 시 401                                                                                           | Bearer token 잘못됨. 재발급                                                |
| WRKS AI 가 도구를 안 쓰고 그냥 응답함                                                                          | 도구 설명 빈약. ✨ AI 추천 으로 설명 개선                                  |
| OAuth per-user 관련 에러 (`upstream_token_expired_no_refresh`, `upstream_refresh_failed`, `invalid_client` 등) | [WRKS AI 연동 가이드](/guides/wrks-ai-integration) §9-5 문제해결 표 참고   |

---

## 11. 빠른 체크리스트

새 DB 툴킷 등록 시:

- [ ] 커넥터가 "연결됨" 상태
- [ ] DB 사용자 SELECT 권한 (DDL 금지)
- [ ] 커넥터 호스트에서 DB 호스트로 네트워크 도달 가능 (telnet 등)
- [ ] secrets 파일 (`/etc/mcp-connector/secrets/*.env`) 에 비밀번호 라인 추가
- [ ] Studio 에서 툴킷 생성 — 비밀번호는 `${VAR}` placeholder 만
- [ ] 도구 ▶ 테스트 호출로 describe_schema 통과 확인
- [ ] (선택) ✨ AI 추천 으로 도구 설명 개선
- [ ] 엔드포인트 발급 후 Bearer 토큰 안전 보관
- [ ] WRKS AI 에 MCP 도구 등록

---

## 12. 문의

- 도구 사용법 / 도구 설명 개선 / 호출 정확도 향상: WRKS 담당자에게 연락
- 사내 DB / API 환경 특수성: 사내 인프라 담당자와 협업

> 다음 문서도 같이 보세요:
>
> - 커넥터 설치 가이드 → [Connector 설치 가이드](/guides/connector-installation)