M2M 서비스 클라이언트 → MCP 호출 — UI Walkthrough

이 문서는 GenD UI 화면을 그대로 따라가면서 M2M 서비스 클라이언트 (gend-svc-*) 발급부터 MCP tools/list / tools/call 호출까지 전 과정을 검증하기 위한 QA 가이드입니다. 모든 스크린샷은 prod 환경(https://gend.genon.ai)에서 ttagu99 admin 계정으로 자동 캡처되었습니다.

토큰 발급만 빠르게 찾는 경우

이 문서는 "UI 만으로 끝까지 검증"이 목적입니다. 토큰 발급 옵션 비교/명령어 위주는 MCP 통합 가이드 §1 또는 Intel Platform MCP Quickstart §3 을 참조하세요.

사전 요건

GenD admin 권한 보유 계정 (Workspace 관리자 권한 아님 — realm-admin 또는 gend-api admin role)
외부 MCP 클라이언트 중 1 — Claude Desktop, Cursor, MCP Inspector, 또는 임의의 JSON-RPC 가능 도구

Step 1 — `/admin/service-clients` 진입

브라우저로 https://gend.genon.ai 로그인 후 좌측 사이드바 (거버넌스 → 서비스 클라이언트 또는 직접 URL /admin/service-clients) 에서 다음 화면이 보이면 정상입니다.

헤더: 「서비스 클라이언트」 + 현재 등록 건수 배지
우측 상단: 「+ 새 서비스 클라이언트 발급」 버튼
목록 테이블: clientId / 설명 / 역할 / 활성 / 발급자 / 발급 시각 / 작업

서비스 클라이언트 목록 페이지

Step 2 — 신규 서비스 클라이언트 발급

「새 서비스 클라이언트 발급」 버튼을 누르면 모달이 열립니다. 필드를 채웁니다:

클라이언트 ID 접미사: 예 qa-walkthrough — 영문 소문자/숫자/하이픈, 1~48자. 자동으로 gend-svc- prefix 가 붙어 최종 gend-svc-qa-walkthrough 가 됩니다. 사용처 단위로 1개씩 발급하는 것을 권장합니다 (감사 로그에서 호출 주체 식별).
설명: 용도/책임자/만료 의도 등 자유 텍스트
역할: viewer (read-only) 또는 analyst (분석 도구 호출 가능)

발급 다이얼로그

「생성」 버튼 클릭.

Step 3 — Secret 1회 표시 모달 (★ 중요)

발급 직후 모달이 표시되며 client_secret 은 이 화면에서 한 번만 확인할 수 있습니다. 기본은 가리기(•) 상태입니다.

발급 완료 — secret 마스킹 상태

눈(👁) 아이콘으로 토글하면 secret 이 표시됩니다. 아래 캡처에서는 안전상 redacted 처리되었습니다 — 실제 화면에서는 secret 문자열이 그대로 표시됩니다.

발급 완료 — secret 표시 (가이드용 redacted)

처리 순서:

📋 복사 아이콘으로 client_secret 을 안전한 보관소(Vault / Secret Manager / 1Password 등) 에 즉시 저장
「이해했습니다…」 체크박스 체크
「닫기」 버튼 클릭

Secret 복사 누락 = 회전 필요

모달을 닫은 뒤에는 secret 을 다시 볼 수 없습니다. 누락 시 목록의 ⋯ → 「Secret 회전」 으로 재발급해야 합니다 (이전 secret 즉시 무효화).

Step 4 — 목록에 새 클라이언트 확인

모달을 닫으면 토스트 알림 서비스 클라이언트가 발급되었습니다… 가 표시되고, 목록 상단에 새 행이 추가됩니다 (가장 최근 항목이 위로 정렬).

목록 — 발급 후

Step 5 — `/admin/mcp` MCP 게이트웨이 상태 확인

좌측 사이드바 거버넌스 → MCP 게이트웨이 또는 /admin/mcp 진입. MCP 서버가 활성이고 도구가 등록되어 있는지 확인합니다.

확인 항목:

「서버 상태」 카드 → 활성
「버전」 카드 → gend-mcp-server 와 버전 번호
「등록된 도구」 카드 → 32 (정의 35개 중 쓰기 3개는 write-gate 로 제외 — 정적 20 + Intel 12)
「리소스」 카드 → 7
「일별 호출 추이」 차트

기본 활성 탭은 「도구 목록」 — 도구 이름·설명·호출 수·평균 응답·오류율 컬럼이 한 페이지에 노출됩니다.

MCP 게이트웨이 상태 + 도구 목록

「호출 이력」 탭을 클릭하면 최근 호출 (사용자 ID / 도구 / 상태 / 소요시간) 이 시간 역순으로 표시됩니다 — 이후 Step 7 의 외부 호출 결과를 여기서 다시 확인합니다.

MCP 호출 이력 탭

Step 6 — (선택) 워크스페이스 MCP 도구 페이지

/workspace/mcp-tools — 워크스페이스 admin 이 워크스페이스 전용 read-only MCP 도구를 SQL Builder Wizard 로 등록·편집·삭제하는 페이지 (Epic B Phase 1.4).

워크스페이스 MCP 도구 목록

「신규 등록」 버튼으로 5-step Wizard 가 열립니다. Step 1 에서 도구 이름(snake_case) + ORM 모델 또는 Trino FQN 을 선택.

SQL Builder Wizard Step 1

상세 절차는 별도 워크스페이스 가이드(미발행) 또는 Wizard 내부 안내를 참조.

Step 7 — 외부 클라이언트에서 MCP 호출

여기부터는 GenD UI 가 아닌 외부 MCP 클라이언트 환경입니다 (UI 캡처 대상 아님). 동일한 secret 으로 토큰을 발급해 사용합니다.

7-A. curl 로 빠른 검증

export GEND_BASE_URL="https://gend.genon.ai"
export GEND_CLIENT_ID="gend-svc-qa-walkthrough"
export GEND_CLIENT_SECRET="<Step 3 에서 복사한 시크릿>"

TOKEN=$(curl -sS -X POST \
  "$GEND_BASE_URL/auth/realms/gend/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id="$GEND_CLIENT_ID" \
  -d client_secret="$GEND_CLIENT_SECRET" \
  | jq -r .access_token)

# tools/list — 도구 이름 배열이 반환되면 정상.
# 개수는 고정값이 아니다: 호출자 권한(쓰기 도구는 write-gate)과 활성 워크스페이스에
# 등록된 동적 도구에 따라 달라진다. 아래 「기대 결과」의 구성 비율로 확인할 것.
curl -sS -X POST "$GEND_BASE_URL/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq '.result.tools | length'

# tools/call — list_catalogs 실행
curl -sS -X POST "$GEND_BASE_URL/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_catalogs","arguments":{}}}' \
  | jq -r '.result.content[0].text'

기대 결과:

tools/list → 도구 이름 배열. 개수는 환경마다 다르다 — 정적 도구 + Intel 도구 12종(query_intel_* 11 + list_intel_sources) + 활성 워크스페이스의 동적 도구가 합산되고, 쓰기 도구 3종은 write-gate 로 호출자 권한에 따라 빠진다. (2026-08-07 prod 실측: service-account admin 신원에서 36 = 정적 24 + Intel 12) 숫자 자체보다 list_catalogs·execute_query·query_intel_* 가 포함되어 있는지로 판정할 것
tools/call list_catalogs → gendpg, hive, iceberg, nessie, sourcedb, system, tpcds, tpch 카탈로그 목록

호출 직후 GenD UI 의 /admin/mcp → 호출 이력 탭을 새로고침하면 방금 호출이 사용자 ID = service-account UUID 로 기록됩니다.

7-B. Claude Desktop 연동

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%/Claude/claude_desktop_config.json (Windows) 에 추가:

{
  "mcpServers": {
    "gend": {
      "url": "https://gend.genon.ai/mcp",
      "headers": {
        "Authorization": "Bearer <위 7-A 에서 발급한 TOKEN>"
      }
    }
  }
}

Claude Desktop 재시작 → 채팅 입력란의 「Tools」 메뉴에 gend 서버와 32개 도구가 노출되면 정상.

Bearer 토큰 수명 — 토큰을 그대로 박아두는 방식은 영구히 쓸 수 없다

client_credentials 토큰은 30분 후 만료된다 (realm accessTokenLifespan). Claude Desktop 처럼 설정 파일에 Bearer 를 하드코딩하는 방식은 자동 갱신되지 않으므로, 사람이 30분마다 재발급해 붙여넣지 않는 한 끊긴다.

영구히 보관하는 것은 토큰이 아니라 client_id / client_secret 이다. 자격증명은 만료가 없고, 토큰은 코드가 expires_in 기준으로 자동 재발급한다. 플랫폼에 MCP 를 내장하는 경우 (예: GenA) 는 반드시 서버 사이드 연동 패턴 을 따른다 — 토큰 캐시 + 만료 선제 재발급 + 401 재시도.

7-C. MCP Inspector

공식 MCP Inspector (@modelcontextprotocol/inspector) 로 GUI 테스트:

npx @modelcontextprotocol/inspector

브라우저에서 Inspector 열리면 다음 입력:

Transport: Streamable HTTP
URL: https://gend.genon.ai/mcp
Headers: Authorization: Bearer <TOKEN>

→ Connect → Tools 탭에서 32개 도구 listing + 개별 호출 GUI.

QA 체크리스트

정리

QA 가 끝나면 데모/테스트용 client 는 삭제하세요:

UI: /admin/service-clients 의 해당 행 ⋯ → 「삭제」
API: DELETE /api/v1/admin/service-clients/{internal_id} (admin 토큰 필요)

회전 (secret 재발급):

UI: ⋯ → 「Secret 회전」 → 새 secret 모달
API: POST /api/v1/admin/service-clients/{internal_id}/regenerate-secret

사전 요건​

Step 1 — /admin/service-clients 진입​

Step 2 — 신규 서비스 클라이언트 발급​

Step 3 — Secret 1회 표시 모달 (★ 중요)​

Step 4 — 목록에 새 클라이언트 확인​

Step 5 — /admin/mcp MCP 게이트웨이 상태 확인​

Step 6 — (선택) 워크스페이스 MCP 도구 페이지​

Step 7 — 외부 클라이언트에서 MCP 호출​

7-A. curl 로 빠른 검증​

7-B. Claude Desktop 연동​

7-C. MCP Inspector​

QA 체크리스트​

정리​

관련 문서​