Korea Ground-Truth MCP

헤드리스, AI 네이티브 SaaS로 고객은 AI 에이전트입니다. MCP(Streamable HTTP) 및 REST를 통해 한국 사실 확인 도구를 제공하며, 선불 크레딧으로 사용량이 청구됩니다.

라이브: https://kr-groundtruth-mcp.vercel.app — /llms.txt, /openapi.json, /pricing.json. MCP 엔드포인트: /api/mcp.

claude mcp add --transport http kgt https://kr-groundtruth-mcp.vercel.app/api/mcp --header "Authorization: Bearer kgt_live_..."

스택

Next.js 16 (App Router) · mcp-handler 2 (MCP SDK v2, 무상태) · Supabase Postgres · Toss Payments · Vercel.

Related MCP server: 갈피 법령조회 MCP

인프라

• Supabase 프로젝트 kr-groundtruth-mcp (ref kzjzjahokqduktphxpsj, ap-northeast-2)

• Vercel 프로젝트 chloepark85s-projects/kr-groundtruth-mcp; 프로덕션용 환경 변수 설정됨 (vercel env ls)

• 등록: 공식 MCP 레지스트리 io.github.ChloePark85/kr-groundtruth (server.json + mcp-publisher), Smithery hapark85/kr-groundtruth (smithery mcp publish … --config-schema), Glama (자동 색인됨; /.well-known/glama.json으로 소유권 주장), mcp.so (이슈 chatmcp/mcpso#3776)

• MCP 인증: discovery(initialize/tools/list)는 공개; tools/call은 Authorization: Bearer, x-api-key, 또는 ?apiKey=를 통한 키가 필요

설정

1. Supabase 프로젝트 → SQL 편집기에서 supabase/migrations/0001_core.sql 실행 (또는 supabase db push).

2. .env.example → .env.local 복사, 키 입력:

   • DATA_GO_KR_KEY: data.go.kr에서 「국세청_사업자등록정보 진위확인 및 상태조회」, 「국토교통부_아파트 매매 실거래가」 활용신청 (자동승인)

   • JUSO_KEY: business.juso.go.kr 승인키 신청

   • DART_KEY: opendart.fss.or.kr 인증키

   • LAW_OC: law.go.kr OPEN API 신청 (관리자 승인 1~2일)

   • TOSS_CLIENT_KEY / TOSS_SECRET_KEY: 토스페이먼츠 테스트 키

3. npm run dev

4. DART 이름 검색에는 기업 코드 목록이 필요합니다: npx tsx scripts/sync-dart-corp-codes.ts (매월 재실행).

흐름

POST /v1/accounts {email}            → api_key (once) + 50 free credits
claude mcp add --transport http kgt $URL/api/mcp --header "Authorization: Bearer kgt_live_..."
tools/call → debit_credits (row-locked) → cache → upstream → {ok, data, meta:{cost, balance_remaining}}
402 INSUFFICIENT_CREDITS → POST /v1/topups {credits} → checkout_url → human pays (Toss) → credit_credits (idempotent)

설계 노트

• src/lib/tools/registry.ts는 MCP 도구, REST 라우트, OpenAPI, 가격 책정, llms.txt의 단일 소스입니다. 가격은 tool_prices에도 시드되며, debit_credits가 청구하는 값은 DB 행입니다.

• 업스트림 호출 전 차감; 업스트림 실패 → 자동 환불 (credit_ledger.reason='refund').

• credit_ledger는 unique(reason, ref_id) 제약 조건을 가진 append-only (트리거) 테이블이므로, Toss 성공 리다이렉트와 웹훅이 모두 안전하게 실행될 수 있습니다.

• 모든 테이블에는 정책 없이 RLS가 활성화되어 있으며, 서비스 역할 키(서버)만 접근할 수 있습니다.

메트릭

• npm run metrics [-- --days 7 --include-test] — 주간 리포트 (핵심 지표(north star) = Weekly Active API Keys; 퍼널: 생성 → 첫 호출 → 2일차 호출 → 402 → 충전; 첫 호출까지의 시간; 도구별 호출 수; 수익). 테스트 계정(@example.com)은 --include-test가 없는 한 제외됩니다.

• 헤더 x-admin-token: $ADMIN_TOKEN과 함께 GET /v1/admin/metrics?days=7을 호출하면 동일한 JSON을 반환합니다 (supabase/migrations/0002_metrics.sql의 metrics_report()).

검증 체크리스트

H=http://localhost:3000
curl -X POST $H/v1/accounts -H 'content-type: application/json' -d '{"email":"a@b.com"}'
K=kgt_live_...
curl -X POST $H/api/mcp -H "Authorization: Bearer $K" -H 'accept: application/json, text/event-stream' -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -X POST $H/v1/tools/search_address -H "Authorization: Bearer $K" -H 'content-type: application/json' -d '{"keyword":"세종대로 209"}'
# race test: 50 concurrent calls on a low balance → ledger sum == balance
seq 50 | xargs -P 50 -I{} curl -s -o /dev/null -w '%{http_code}\n' -X POST $H/v1/tools/search_address -H "Authorization: Bearer $K" -H 'content-type: application/json' -d '{"keyword":"테스트 {}"}' | sort | uniq -c