Toolkit 사용 가이드

대상: 고객사 관리자 / 사내 개발자 — Studio 에서 툴킷을 만들고 WRKS AI 에 연결해서 사용하는 전 과정 선행 조건: 커넥터 설치 완료 (Connector 설치 가이드 참고) 소요 시간: 단순 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개 로 묶입니다.

툴킷 종류

2. 사전 준비

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

자격증명 secrets 파일 만드는 법은 Connector 설치 가이드 의 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 규칙

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

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

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

4-1. "+ 새 Toolkit" 시작

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

4-2. 기본 정보 입력

4-3. OpenAPI 명세 입력

3가지 방법 중 택일:

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

4-4. 인증 설정

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

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

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

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

선택 팁: "이 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개 필드 입력:

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

• 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 연동 가이드 §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)" 선택 시 나오는 필드:

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" 선택.

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

5-2. Dialect 별 입력 예시

PostgreSQL

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

MySQL

MS SQL (SQL Server)

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

Oracle DB

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

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

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

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

5-4. secrets 파일 확인

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

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

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

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

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

표 항목:

7. 도구 테스트 호출

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

• 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 툴킷 한정)

API Key (static Bearer) 발급 결과:

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 연동 가이드 에 상세. 요약:

• 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 연동 가이드 §9-5 참고).

10. 트러블슈팅

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 설치 가이드