WRKS AI 연동 가이드

대상: WRKS AI 사용자 / 운영자 — Studio 에서 만든 툴킷을 WRKS AI 채팅에서 사용 선행 조건: 툴킷 1개 이상 생성 + 도구 테스트 호출 성공 (Toolkit 사용 가이드)

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 방식

⚠️ 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)

화면 우측 상단 "+ 도구 추가" 클릭 → "외부 제공 도구 추가" 다이얼로그가 열립니다.

3-2. 입력 필드

3-3. ⚠ 인증 입력 — Authorization 헤더 + Bearer prefix

WRKS AI 의 API Key 모드는 일반 HTTP 헤더 형식입니다. 우리 Hub 는 Authorization: Bearer <토큰> 만 받으므로:

토큰만 붙여넣으면 Hub 가 missing_bearer 로 401 반환합니다. 반드시 Bearer 를 앞에 붙이세요.

3-4. 추가 후 확인

다이얼로그 하단 추가하기 클릭 → 도구 관리 화면 목록에 새 row 가 보입니다.

4. "지시 사항" 활용 — 변수 슬롯 대신 자연어 가이드

WRKS AI 의 도구 추가 다이얼로그에는 별도 "변수 슬롯" UI 가 없습니다. 대신 "지시 사항" 텍스트 필드에 자연어로 가이드를 적어두면, 에이전트 LLM 이 도구 호출 시 그 가이드를 컨텍스트로 사용합니다.

4-1. 언제 무엇을 적을지

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. 작동 안 할 때 점검 순서

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. 사고 대응

7. 트러블슈팅

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 등록용 (필수)

WRKS AI 는 이 MCP URL 하나만 있으면 나머지 (Authorize/Token endpoint · Client ID · Client Secret) 를 MCP 표준 discovery + DCR 로 자동 등록합니다. 별도 붙여넣기 불필요.

사내 OAuth 앱 (Google Cloud Console / Azure AD 등) 등록용

Callback URL 이 사내 OAuth 앱 (Google Cloud Console, Azure AD, Salesforce 등) 의 "허용된 리디렉션 URI" 목록에 반드시 등록돼 있어야 합니다. 없으면 사용자가 로그인 화면에서 redirect_uri_mismatch 로 실패합니다.

9-2. WRKS AI 에 OAuth 도구로 등록

WRKS AI 관리 UI → 도구 추가:

끝. 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/<slug>/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/<slug>/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. 문제해결

10. 문의

• WRKS AI 측 UI / 등록 절차 최신 안내: WRKS AI 담당자
• 도구 정확도 튜닝 / 도구 설명 컨설팅: WRKS 담당자

같이 보세요:

• 툴킷 사용 → Toolkit 사용 가이드
• DB 별 연동 → DB 연동 가이드
• 커넥터 설치 → Connector 설치 가이드