Korea Ground-Truth MCP

SaaS headless y nativo de IA cuyo cliente es un agente de IA. Expone herramientas de verificación de datos de Corea a través de MCP (Streamable HTTP) y REST, con consumo medido mediante créditos prepagados.

En vivo: https://kr-groundtruth-mcp.vercel.app — /llms.txt, /openapi.json, /pricing.json. Endpoint MCP: /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, sin estado) · Supabase Postgres · Toss Payments · Vercel.

Related MCP server: 갈피 법령조회 MCP

Infraestructura

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

• Proyecto de Vercel chloepark85s-projects/kr-groundtruth-mcp; variables de entorno configuradas para producción (vercel env ls)

• Listados: Official MCP Registry io.github.ChloePark85/kr-groundtruth (server.json + mcp-publisher), Smithery hapark85/kr-groundtruth (smithery mcp publish … --config-schema), Glama (indexado automáticamente; reclamado mediante /.well-known/glama.json), mcp.so (issue chatmcp/mcpso#3776)

• Autenticación MCP: el descubrimiento (initialize/tools/list) es público; tools/call requiere una clave mediante Authorization: Bearer, x-api-key o ?apiKey=

Configuración

1. Proyecto de Supabase → ejecutar supabase/migrations/0001_core.sql en el editor SQL (o supabase db push).

2. Copiar .env.example → .env.local y rellenar las claves:

   • DATA_GO_KR_KEY: Solicitar el uso de 「국세청_사업자등록정보 진위확인 및 상태조회」 y 「국토교통부_아파트 매매 실거래가」 en data.go.kr (aprobación automática)

   • JUSO_KEY: Solicitar la clave de aprobación en business.juso.go.kr

   • DART_KEY: Clave de autenticación en opendart.fss.or.kr

   • LAW_OC: Solicitar la OPEN API en law.go.kr (aprobación del administrador en 1~2 días)

   • TOSS_CLIENT_KEY / TOSS_SECRET_KEY: Clave de prueba de Toss Payments

3. npm run dev

4. La búsqueda de nombres en DART necesita la lista de códigos de corporaciones: npx tsx scripts/sync-dart-corp-codes.ts (volver a ejecutar mensualmente).

Flujo

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)

Notas de diseño

• src/lib/tools/registry.ts es la fuente única de las herramientas MCP, las rutas REST, OpenAPI, los precios y llms.txt. Los precios también se cargan en tool_prices; la fila de la base de datos es lo que cobra debit_credits.

• Debitar antes de la llamada upstream; si la llamada upstream falla → reembolso automático (credit_ledger.reason='refund').

• credit_ledger es de solo añadir (trigger) con unique(reason, ref_id), por lo que tanto la redirección de éxito de Toss como el webhook pueden ejecutarse de forma segura.

• Todas las tablas tienen RLS habilitado sin políticas; solo la clave de rol de servicio (servidor) puede acceder a ellas.

Métricas

• npm run metrics [-- --days 7 --include-test] — informe semanal (métrica North Star = Weekly Active API Keys; embudo: clave creada → primera llamada → llamada al segundo día → 402 → recarga; tiempo hasta la primera llamada; llamadas por herramienta; ingresos). Las cuentas de prueba (@example.com) se excluyen salvo que se use --include-test.

• GET /v1/admin/metrics?days=7 con la cabecera x-admin-token: $ADMIN_TOKEN devuelve el mismo JSON (metrics_report() en supabase/migrations/0002_metrics.sql).

Lista de verificación

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