# WRKS AI 에 MCP 도구 연결 가이드 > **대상**: WRKS AI 사용자 / 운영자 — Studio 에서 만든 툴킷을 WRKS AI 채팅에서 사용 > **선행 조건**: 툴킷 1개 이상 생성 + 도구 테스트 호출 성공 ([Toolkit 사용 가이드](/guides/toolkit-usage)) --- ## 1. 흐름 한 눈에 보기 ``` [WRKS AI 채팅] │ │ (자연어 질문) ▼ ┌─ WRKS AI 가 "이 질문에 답하려면 ERP 도구 필요" 판단 │ │ (MCP 도구 호출) ▼ [MCP Hub Endpoint] ←── 우리가 등록할 URL + Bearer 토큰 │ ▼ [커넥터 (사내망)] │ ▼ [사내 DB / API] │ │ (응답) ▲ [WRKS AI 가 결과를 자연어로 정리해서 답변] ``` --- ## 2. Studio 에서 엔드포인트 발급 엔드포인트 = WRKS AI 가 호출할 **외부에서 접근 가능한 URL + (툴킷 유형에 따라) 인증 정보**. ### 2-1. 절차 1. Studio → 해당 툴킷 카드 클릭 → **"엔드포인트"** 탭 2. **+ 엔드포인트 발급** 클릭 3. (선택) 라벨 입력 — 운영 식별용 (예: "운영용 ERP", "테스트용") 4. **인증 방식** 선택 — **API Key** (대부분) 또는 **OAuth (per-user)** (툴킷이 `oauth_user` authType 인 경우) 5. **확인** 클릭 → 방식에 따라 다른 발급 결과 표시 ### 2-2. 발급 결과 — API Key 방식 | 항목 | 형식 | 보관 | | ------------ | ------------------------------------ | ------------------------------------------------ | | MCP URL | `https://mcp-hub.wrks.ai/mcp/<해시>` | 영구 (revoke 전까지) | | Bearer Token | `eyJ...` 또는 random hex 32+ 글자 | **발급 직후 1회만 화면 노출** — 안전한 곳에 저장 | ⚠️ **Bearer Token 분실 시 재발급 = 새 토큰 발급 + 옛 토큰 revoke**. 옛 등록도 새 토큰으로 갱신해야 함. ### 2-3. 발급 결과 — OAuth (per-user) 방식 발급 결과 카드가 **3섹션 분리**: - **WRKS AI 등록용**: MCP URL 하나만 (WRKS AI 가 DCR 로 나머지 자동 처리) - **사내 OAuth 앱 등록용**: Callback URL (Google Cloud Console · Azure AD 의 "허용된 리디렉션 URI" 에 등록) 상세는 §9 "OAuth (per-user) 툴킷 등록" 참고. ### 2-4. URL 의 의미 ``` https://mcp-hub.wrks.ai/mcp/abc123def456... │ └────┬───┘ │ └── 엔드포인트 해시 (random, 추측 불가) — 이것만으로 lookup + 인증 모두 가능 └── 고정 prefix /mcp/ ``` > 옛 발급 URL (`/mcp/<번호>/<해시>` 형식) 도 한동안 정상 동작합니다 — enterprise ID segment 는 무시되고 해시만으로 식별합니다. 같은 enterprise / 같은 툴킷이라도 **엔드포인트는 여러 개 발급 가능** — 용도별로 (예: WRKS AI 일반 / 챗봇 통합 / 자동화). --- ## 3. WRKS AI 에 도구 등록 > WRKS AI **관리자 권한** 필요. 일반 사용자 계정은 메뉴가 보이지 않습니다. ### 3-1. 메뉴 진입 WRKS AI 우측 상단 **관리자** → 좌측 **"사내 에이전트/비서 > 에이전트 도구 관리"** (직접 URL: `https://wrks.ai/ko/admin/mcp-tools`) 화면 우측 상단 **"+ 도구 추가"** 클릭 → **"외부 제공 도구 추가"** 다이얼로그가 열립니다. ![에이전트 도구 관리 페이지 — 우측 상단 + 도구 추가 버튼](screenshots/08-wrksai-tool-admin.png) ### 3-2. 입력 필드 | 필드 | 입력값 | 비고 | | ---------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------- | | **도구 이름** \* | WRKS AI UI 에 표시될 이름 (예: "ERP 조회", "사내 고객 DB") | 필수 | | **도구 설명** | 어떤 도구인지 한 줄 — **에이전트가 도구 선택 시 참조** (예: "ERP 의 주문/매출 데이터 조회. 자연어 OK") | 선택 — **있어야 정확도 ↑** | | **지시 사항** | 도구 사용 시 에이전트에 전달할 가이드 (예: "결과는 표 형식으로 정리. 100 행 초과 시 WHERE 로 좁혀라.") | 선택 — 다음 §4 참고 | | **도구 링크** \* | Studio 에서 발급한 **MCP URL** 그대로 (§2-2 · §2-3) | 필수 | | **전송 방식** | `Streamable HTTP (권장)` 선택 | 우리 Hub 가 이 방식 사용 | | **인증 방식** | `API Key` 선택 (기본) / OAuth per-user 툴킷은 `OAuth 2.0 Dynamic Client Registration (DCR)` 선택 (§9 참고) | 툴킷 authType 에 따라 다름 | | **API Key** | 다음 §3-3 참고 — Header name + Secret Key | API Key 방식일 때만 | | **연결 확인** | 클릭 → Hub 에 `tools/list` 호출 → 도구 목록 반환되면 성공 | 등록 전 검증 단계 | | **아이콘** | (선택) 도구 카드에 표시할 아이콘 PNG/SVG | 미입력 시 default 아이콘 | ![외부 제공 도구 추가 다이얼로그 — 상단 (이름/설명/지시 사항/도구 링크/전송 방식)](screenshots/09-wrksai-add-tool-form.png) ### 3-3. ⚠ 인증 입력 — Authorization 헤더 + Bearer prefix WRKS AI 의 **API Key** 모드는 일반 HTTP 헤더 형식입니다. 우리 Hub 는 **`Authorization: Bearer <토큰>`** 만 받으므로: | Header name | Secret Key | | --------------- | ---------------------------------------------------------------------------- | | `Authorization` | `Bearer eyJhbGciOi...` (실제 토큰 앞에 **`Bearer ` (대문자 B + 공백)** 포함) | > 토큰만 붙여넣으면 Hub 가 `missing_bearer` 로 401 반환합니다. 반드시 `Bearer ` 를 앞에 붙이세요. ![외부 제공 도구 추가 다이얼로그 — 하단 (인증 방식 / API Key / 연결 확인 / 아이콘)](screenshots/10-wrksai-add-tool-auth.png) ### 3-4. 추가 후 확인 다이얼로그 하단 **추가하기** 클릭 → 도구 관리 화면 목록에 새 row 가 보입니다. | 컬럼 | 역할 | | ------------- | --------------------------------------------------------------- | | **노출 순서** | 에이전트가 여러 도구 중 우선 고려할 순서 | | **허용 여부** | ON / OFF — OFF 면 사용자에게 노출 안 됨 | | **관리** | 수정 / 삭제 | | **권한 관리** | 어떤 사용자 / 팀에 노출할지 제한 (default: 모든 직원이 사용 중) | --- ## 4. "지시 사항" 활용 — 변수 슬롯 대신 자연어 가이드 WRKS AI 의 도구 추가 다이얼로그에는 **별도 "변수 슬롯" UI 가 없습니다**. 대신 **"지시 사항"** 텍스트 필드에 자연어로 가이드를 적어두면, 에이전트 LLM 이 도구 호출 시 그 가이드를 컨텍스트로 사용합니다. ### 4-1. 언제 무엇을 적을지 | 상황 | "지시 사항" 에 적을 내용 | | -------------------------------- | ----------------------------------------------------------------------- | | 결과 표현 가이드 | "결과는 표 형식으로 정리. 금액 컬럼은 천 단위 구분자." | | 큰 조회 방지 | "100 행 제한이 있으니 WHERE 조건 (날짜, 고객사) 으로 좁힌 뒤 호출하라." | | 도구 우선순위 | "사용자가 '주문 / 매출 / 거래' 키워드 쓰면 이 도구를 1순위 고려." | | DB 별 SQL 차이 안내 | "Oracle 이므로 LIMIT 대신 ROWNUM <= N 사용. DATE 함수는 TO_DATE." | | 사용자 컨텍스트 (부서/권한) 반영 | "현재 사용자가 영업팀이면 dept = 'SALES' 필터 자동 적용." | ### 4-2. 사용자 별 다른 값 처리 (부서, 권한 등) WRKS AI 가 도구를 호출할 때 **사용자 정보를 자동으로 전달** 합니다. 도구 측에서 활용하려면: - **"지시 사항"** 에 "현재 사용자의 부서 코드를 SQL `WHERE dept = '...'` 에 반영하라" 같은 가이드를 적으면 LLM 이 알아서 채움 - 더 엄격하게 권한 분리하려면 **사용자 그룹 별 별도 엔드포인트 발급** → WRKS AI 도구 등록도 그룹 별로 (권한 관리 컬럼에서 사용자/팀 매핑) ### 4-3. 변수 처리가 굳이 필요하지 않은 이유 대부분 PoC / 운영 시나리오: - WRKS AI 가 자연어 → SQL/API 호출을 LLM 으로 **자동 변환** - 사용자 입력 (날짜, 키워드, 부서) 은 SQL/JSON arguments 안에 LLM 이 알아서 채움 - ⇒ 별도 변수 등록 없이도 **대부분 잘 동작** 처음엔 **"지시 사항" 만 적고 시작**, 운영 중 특정 패턴이 자꾸 안되면 그 케이스만 지시 사항에 한 줄 추가하는 식으로 점진 보강 권장. --- ## 5. 동작 확인 (채팅으로 직접 사용) ### 5-1. 단순 질문 시도 WRKS AI 채팅에서 자연어로: - "어제 매출 알려줘" - "고객사 A 의 최근 주문 5건" - "재고 가장 부족한 상품 10개" WRKS AI 가: 1. 등록된 MCP 도구 목록 확인 2. 질문에 가장 적합한 도구 선택 (도구 설명 기반) 3. 도구 호출 (DB 의 경우 `describe_schema` → `execute_query` 순) 4. 결과를 자연어로 정리 + 표 / 차트 등 시각화 ### 5-2. 작동 안 할 때 점검 순서 | 순서 | 점검 | | ---- | ------------------------------------------------------------------------------------------------- | | 1 | Studio 의 **호출 로그** 탭 — 호출이 도달했는가? | | 2 | 도달했으면 응답 상태 (200 / 4xx / 5xx) 확인 | | 3 | 도달 안 했으면 WRKS AI 측에서 도구를 안 골랐을 가능성 — **도구 설명** 보강 (Studio 의 ✨ AI 추천) | | 4 | 5xx 면 커넥터 / 사내 시스템 측 에러. 커넥터 로그 확인 | | 5 | 4xx + 401 면 Bearer 토큰 잘못. 재등록 | --- ## 6. 운영 정착 후 챙길 것 ### 6-1. 도구 설명 품질 관리 WRKS AI 의 도구 선택 정확도 = **도구 설명 품질**. 정기적으로: - Studio 의 ✨ AI 추천 버튼으로 설명 자동 개선 - 실제 사용자가 자주 묻는 패턴을 도구 설명에 반영 (예: "주문 / 매출 / 거래" 키워드) ### 6-2. 사용량 / 호출 빈도 모니터링 - Studio 의 **호출 로그** — 누가 / 언제 / 얼마나 자주 호출했는지 - 비정상 패턴 (수만 건 / 초) 감지 시 일시중지 ### 6-3. Bearer 토큰 로테이션 - **API Key (static Bearer)** — 6개월 ~ 1년 주기 권장. 새 토큰 발급 → WRKS AI 측 등록 갱신 → 옛 토큰 revoke - **OAuth (per-user)** — 사용자별 access_token 은 짧은 주기로 Hub 이 자동 갱신 (refresh_token 사용). 별도 로테이션 불필요. refresh_token 자체가 만료 (Google 기본 없음, Entra ID 기본 90일) 되면 사용자가 재로그인만 하면 됨 ### 6-4. 사고 대응 | 사고 | 응급 조치 | | ------------ | --------------------------------------------------------- | | 토큰 유출 | Studio 에서 해당 엔드포인트 **회수 (revoke)** — 즉시 무효 | | 사내 DB 부하 | Studio 헤더의 **⏸ 일시중지** — 모든 호출 차단 | | 잘못된 응답 | DB 사용자 권한 / 노출 view 조정 | --- ## 7. 트러블슈팅 | 증상 | 원인 / 해결 | | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | WRKS AI 가 "관련된 도구가 없습니다" 라고 답 | 도구 설명 빈약. ✨ AI 추천 → 설명 개선 / "지시 사항" 에 키워드 보강 | | 도구 호출은 됐는데 응답이 이상함 | LLM 이 만든 SQL 부정확. Studio 의 호출 로그에서 SQL 확인 후 "지시 사항" 에 가이드 추가 | | 401 + `missing_bearer` | Secret Key 에 `Bearer ` prefix 누락. `Authorization` 헤더의 값은 `Bearer eyJ...` 형태여야 함 (§3-3 참고) | | 401 + `invalid_bearer` | 토큰 자체가 잘못 / revoke 됨. Studio 에서 재발급 → WRKS AI 측 도구 수정으로 갱신 | | 504 Gateway Timeout | 사내 DB 응답 지연. DB index 확인 또는 "지시 사항" 에 "큰 조회 피하기" 가이드 | | WRKS AI 응답에 데이터가 잘려서 옴 | 정상 — 100 행 제한. WHERE 조건으로 좁히도록 도구 설명/지시 사항 보강 | | WRKS AI 도구 추가 다이얼로그의 **연결 확인** 이 실패함 | (1) 도구 링크 오타 (2) Secret Key 에 Bearer prefix 없음 (3) Studio 측 엔드포인트 revoke 상태 — Studio 의 엔드포인트 탭에서 재확인 | | OAuth per-user 관련 에러 (`upstream_token_expired_no_refresh` · `upstream_refresh_failed` · `redirect_uri_mismatch` · `invalid_client` · `unknown_endpoint` 등) | §9-5 OAuth 문제해결 표 참고 | --- ## 8. 자주 묻는 질문 (FAQ) **Q1. WRKS AI 가 어떻게 도구를 자동으로 골라요?** A. 등록 시 받아온 도구 목록 + 각 도구의 설명 (description) 을 LLM 이 보고 판단. **설명 품질이 곧 정확도**. **Q2. 같은 툴킷에 엔드포인트를 여러 개 만들어도 되나요?** A. 네. WRKS AI 일반 / 사내 챗봇 / 자동화 등 용도 별로 분리 권장 — 사고 시 부분 회수 가능. **Q3. WRKS AI 외 다른 MCP 클라이언트 (Claude Desktop 등) 도 같은 엔드포인트로 연결되나요?** A. 네. MCP 표준 프로토콜이라 호환. Bearer 만 같이 전달하면 됨. **Q4. 호출 로그가 너무 많아져요. 자동 삭제 되나요?** A. 90일 이상 된 로그는 자동 삭제 (TTL). 별도 보관 필요시 별도 export. **Q5. 명시적 "변수" 입력 UI 가 없는데, 사용자 별 다른 값은 어떻게 넘기나요?** A. WRKS AI 의 도구 추가 다이얼로그에는 별도 변수 슬롯이 없습니다. 대부분의 경우 **"지시 사항"** 필드에 자연어 가이드 (예: "현재 사용자의 부서 코드를 SQL WHERE 절에 반영하라") 만 적어두면 에이전트 LLM 이 호출 시 알아서 채웁니다. 더 엄격한 권한 분리가 필요하면 사용자 그룹 별 **별도 엔드포인트** 를 발급한 뒤 각 그룹에 다른 도구로 등록하세요 (§4 참고). **Q6. WRKS AI 인증 방식에 "OAuth" 도 있는데 그건 언제 쓰나요?** A. 툴킷이 **oauth_user 인증 방식** (외부 OAuth 로 사용자별 토큰 발급) 으로 만들어졌으면 **OAuth 2.0 Dynamic Client Registration (DCR)** 를 선택합니다. WRKS AI 가 Hub 를 OAuth Authorization Server 로 취급해 MCP 표준 discovery + DCR 로 client 자동 등록, 사용자 (Alice, Bob …) 별로 사내 OAuth (Google · Entra ID 등) 로그인 화면을 띄우고 access_token 을 획득합니다. Hub 이 그 토큰을 암호화 저장·자동 갱신하며 도구 호출 시 사용자에 맞는 토큰으로 대상 API 호출. 자세한 등록 절차는 §9 "OAuth (per-user) 툴킷 등록" 을 참고하세요. API Key vs OAuth 결정 기준: - 호출자가 모두 같은 계정으로 대상 시스템에 접근 → **API Key** - 사용자별 권한이 달라야 함 (예: Alice 는 자기 잔액만, Bob 은 자기 잔액만) → **OAuth (per-user)** --- ## 9. OAuth (per-user) 툴킷 등록 Toolkit 이 **oauth_user** 인증으로 만들어진 경우 이 섹션을 참고하세요. WRKS AI 는 Hub 의 각 엔드포인트를 독립 OAuth Provider 로 취급합니다. ### 9-1. Studio 에서 OAuth 엔드포인트 발급 1. Studio → 툴킷 상세 → **엔드포인트 발급** 2. 발급 다이얼로그에서 **인증 방식: OAuth** 선택 3. **Redirect URI** 입력 — WRKS AI 콜백 URL (WRKS AI 가 승인 완료 후 사용자를 되돌려보낼 주소) - 일반: `https://gateway-api.wrks.ai/mcp/oauth/callback` - 공공: `https://gov-api.wrks.ai/mcp/oauth/callback` 4. **발급** 클릭 → 다음 값들이 1회만 화면에 표시됩니다. 안전한 곳에 저장하세요. **WRKS AI 등록용 (필수)** | 값 | 예시 | | ------- | ------------------------------------ | | MCP URL | `https://mcp-hub.wrks.ai/mcp/` | WRKS AI 는 이 MCP URL 하나만 있으면 나머지 (Authorize/Token endpoint · Client ID · Client Secret) 를 **MCP 표준 discovery + DCR 로 자동 등록**합니다. 별도 붙여넣기 불필요. **사내 OAuth 앱 (Google Cloud Console / Azure AD 등) 등록용** | 값 | 예시 | 어디에 씀 | | ------------ | ----------------------------------------------- | ---------------------------- | | Callback URL | `https://mcp-hub.wrks.ai/oauth//callback` | 사내 OAuth 앱의 리디렉션 URI | > Callback URL 이 사내 OAuth 앱 (Google Cloud Console, Azure AD, Salesforce 등) 의 > "허용된 리디렉션 URI" 목록에 반드시 등록돼 있어야 합니다. 없으면 사용자가 > 로그인 화면에서 `redirect_uri_mismatch` 로 실패합니다. ### 9-2. WRKS AI 에 OAuth 도구로 등록 WRKS AI 관리 UI → 도구 추가: | 항목 | 값 | | ------------- | ---------------------------------------------------- | | 도구 URL | 위에서 받은 **MCP URL** | | **인증 방식** | **OAuth 2.0 Dynamic Client Registration (DCR)** 선택 | ![WRKS AI 에 OAuth (DCR) 도구 추가](screenshots/13-wrksai-oauth-dcr-form.png) **끝.** Client ID / Secret / Authorize URL / Token URL 은 붙여넣지 않습니다. WRKS AI 가 MCP 표준 discovery (RFC 9728 → RFC 8414) 로 metadata 를 자동 발견하고, DCR (RFC 7591) 로 client 를 자동 등록합니다. 인증 방식 셀렉터 위에 자동으로 표시되는 `OAuth Callback URL: https://gateway-api.wrks.ai/mcp/oauth/callback` 이 사내 OAuth 앱 등록 시 사용됩니다. > WRKS AI 가 아닌 다른 MCP 클라이언트가 DCR 미지원인 경우에만 수동 등록 대안이 있습니다 (Studio 발급 화면의 "고급" 옵션). 일반 WRKS AI 사용에는 필요 없습니다. ### 9-3. 사내 OAuth 앱 사전 세팅 체크리스트 **Google Cloud Console (예: Google Workspace API 접근):** - OAuth 2.0 Client ID 유형: **Web application** - Authorized redirect URIs: `https://mcp-hub.wrks.ai/oauth//callback` - Hub 가 자동으로 `access_type=offline` + `prompt=consent` 파라미터를 붙여 refresh_token 을 요청합니다. 별도 설정 불필요. **Microsoft Entra ID (M365):** - App registration 유형: **Web** (Public 아님 — client_secret 사용) - Redirect URI: `https://mcp-hub.wrks.ai/oauth//callback` - **Scope 에 `offline_access` 필수 포함** — 없으면 Entra ID 가 refresh_token 을 발급하지 않아 매 시간 재로그인 필요. Studio 툴킷 편집 화면의 "Scope" 필드에 예: `openid profile offline_access User.Read` 형태로. **Salesforce Personal / 기타:** - Provider 별로 refresh_token 발급 요구사항 다름. 대부분 scope 또는 별도 옵션이 필요. Provider 문서 확인 필수. ### 9-4. 첫 사용 흐름 (Alice 예시) 1. Alice 가 WRKS AI 에서 이 도구를 처음 호출 2. WRKS AI 가 사내 OAuth (Google / Entra ID) 로그인 화면을 Alice 브라우저에 노출 3. Alice 가 로그인 + 권한 승인 4. Hub 이 access_token + refresh_token 을 암호화 저장 (Alice ↔ 이 도구 매핑) 5. 이후 Alice 의 도구 호출은 로그인 없이 저장된 토큰으로 자동 처리 6. **1시간 후 upstream access_token 만료 시 Hub 이 refresh_token 으로 자동 갱신** — Alice 는 아무것도 안 느낌 7. Bob 은 다른 로그인 → 다른 토큰. 서로 격리됨. refresh_token 자체가 만료 (Google 기본 없음, Entra ID 기본 90일) 되거나 사용자가 사내 OAuth 앱에서 권한 취소 시에만 재로그인 필요. ### 9-5. 문제해결 | 증상 | 원인 · 조치 | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `redirect_uri_mismatch` (로그인 화면) | Callback URL 이 사내 OAuth 앱의 허용 목록에 없음. §9-1 하단 표의 Callback URL 을 사내 앱에 등록. | | `invalid_client` (401) | 사내 OAuth 앱의 Client ID/Secret 이 커넥터 host 의 `.env` 파일과 불일치. `OAUTH_CLIENT_ID` / `OAUTH_CLIENT_SECRET` 값 재확인. | | `unknown_endpoint` / `endpoint_not_oauth` (404) | Studio 에서 엔드포인트가 재발급됐는데 WRKS AI 가 옛 URL 을 캐시. WRKS AI 에서 이 도구 삭제 후 새 MCP URL 로 재등록. | | `upstream_token_expired_no_refresh` | 사내 OAuth 앱이 refresh_token 을 발급 안 함. Entra ID 는 scope 에 `offline_access` 포함 (§9-3). Google 은 예전 로그인 세션에는 없을 수 있음 — **한 번 재로그인** 후 해결. | | `upstream_refresh_failed` (에러 메시지 뒤 `401` / `400`) | 사용자가 사내 OAuth 앱에서 앱 권한을 취소했거나 관리자가 access 를 revoke. WRKS AI 도구 재승인 (재로그인) 필요. | | `pkce_S256_required` / `invalid_code_challenge_length` (400) | WRKS AI 쪽 OAuth 구현이 PKCE S256 미지원. WRKS AI 팀에 문의. | --- ## 10. 문의 - WRKS AI 측 UI / 등록 절차 최신 안내: WRKS AI 담당자 - 도구 정확도 튜닝 / 도구 설명 컨설팅: WRKS 담당자 > 같이 보세요: > > - 툴킷 사용 → [Toolkit 사용 가이드](/guides/toolkit-usage) > - DB 별 연동 → [DB 연동 가이드](/guides/db-connection) > - 커넥터 설치 → [Connector 설치 가이드](/guides/connector-installation)