Korea Ground-Truth MCP

Headless, KI-native SaaS, deren Kunde ein KI-Agent ist. Sie stellt koreanische Faktenprüfungs-Tools über MCP (Streamable HTTP) und REST bereit; die Abrechnung erfolgt über Prepaid-Credits.

Live: https://kr-groundtruth-mcp.vercel.app — /llms.txt, /openapi.json, /pricing.json. MCP-Endpunkt: /api/mcp.

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

Stack

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

Related MCP server: apick-mcp

Infrastruktur

• Supabase-Projekt kr-groundtruth-mcp (ref kzjzjahokqduktphxpsj, ap-northeast-2)

• Vercel-Projekt chloepark85s-projects/kr-groundtruth; Umgebungsvariablen für die Produktion gesetzt (vercel env ls)

• Einträge: Official MCP Registry io.github.ChloePark85/kr-groundtruth (server.json + mcp-publisher), Smithery hapark85/kr-groundtruth (smithery mcp publish … --config-schema), Glama (automatisch indexiert; beansprucht über /.well-known/glama.json), mcp.so (Issue chatmcp/mcpso#3776)

• MCP-Authentifizierung: Discovery (initialize/tools/list) ist öffentlich; tools/call benötigt einen Schlüssel über Authorization: Bearer, x-api-key oder ?apiKey=

Einrichtung

1. Supabase-Projekt → supabase/migrations/0001_core.sql im SQL-Editor ausführen (oder supabase db push).

2. .env.example → .env.local kopieren und Schlüssel eintragen:

   • DATA_GO_KR_KEY: Bei data.go.kr die Nutzung von 「국세청_사업자등록정보 진위확인 및 상태조회」 und 「국토교통부_아파트 매매 실거래가」 beantragen (automatische Genehmigung)

   • JUSO_KEY: Genehmigungsschlüssel bei business.juso.go.kr beantragen

   • DART_KEY: Authentifizierungsschlüssel bei opendart.fss.or.kr beantragen

   • LAW_OC: Bei law.go.kr die OPEN API beantragen (Admin-Freigabe 1~2 Tage)

   • TOSS_CLIENT_KEY / TOSS_SECRET_KEY: 토스페이먼츠-Testschlüssel

3. npm run dev

4. Die DART-Namenssuche benötigt die Unternehmenscodeliste: npx tsx scripts/sync-dart-corp-codes.ts (monatlich erneut ausführen).

Ablauf

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)

Designhinweise

• src/lib/tools/registry.ts ist die einzige Quelle für MCP-Tools, REST-Routen, OpenAPI, Preise und llms.txt. Die Preise werden außerdem in tool_prices eingespielt; die DB-Zeile ist die Belastungsgrundlage für debit_credits.

• Belastung vor dem Upstream-Aufruf; bei Upstream-Fehler → automatische Erstattung (credit_ledger.reason='refund').

• credit_ledger ist append-only (per Trigger) mit unique(reason, ref_id), sodass der Toss-Erfolgs-Redirect und der Webhook beide sicher laufen können.

• Alle Tabellen haben RLS aktiviert und keine Policies; nur der Service-Role-Schlüssel (Server) kann auf sie zugreifen.

Metriken

• npm run metrics [-- --days 7 --include-test] — wöchentlicher Bericht (Nordstern = wöchentlich aktive API-Schlüssel; Funnel: Konto erstellt → erster Aufruf → Aufruf am 2. Tag → 402 → Aufladung; Zeit bis zum ersten Aufruf; Aufrufe nach Tool; Umsatz). Testkonten (@example.com) sind ausgeschlossen, außer wenn --include-test angegeben ist.

• GET /v1/admin/metrics?days=7 mit Header x-admin-token: $ADMIN_TOKEN liefert dasselbe JSON (metrics_report() in supabase/migrations/0002_metrics.sql).

Verifizierungs-Checkliste

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