{
  "markdown": "# Korea Business Verify (KBV) — MCP Server\n\n[![M8ven Score](https://m8ven.ai/badge/mcp/wonderfulian-kbv-server-nnj5uy?v=59f4f9779da2cd9d5f2a99ff46cf1436)](https://m8ven.ai/mcp/wonderfulian-kbv-server-nnj5uy)\n\n**KBV is a hosted MCP server that verifies Korean businesses in real time — 10 free calls/day, then pay-per-call (x402).** Give it a 10-digit Korean business registration number (사업자등록번호) and it returns the registration status (active / suspended / closed), tax type, and — optionally — whether the number matches a representative name and opening date. Data comes live from the Korea National Tax Service (NTS) and is returned as clean, English-normalized JSON.\n\nNo account, no API key, no installation — connect any MCP-capable agent to one URL:\n\n```\nhttps://kbv-server-f7vfitmlkq-du.a.run.app/mcp\n```\n\nBuilt for AI agents and developers doing KYB / due-diligence on Korean companies: procurement, contracting, payments, marketplace onboarding.\n\n## Quick facts\n\n| | |\n|---|---|\n| MCP endpoint | `https://kbv-server-f7vfitmlkq-du.a.run.app/mcp` |\n| Transport | MCP Streamable HTTP (`POST`) |\n| Health check | `GET https://kbv-server-f7vfitmlkq-du.a.run.app/health` → `{\"ok\":true}` |\n| Authentication | None required |\n| Price | **10 free calls/day** per IP, then pay-per-call via x402 ($0.02–$0.05) — see [Pricing](#pricing) |\n| Tools | `check_korean_business_status`, `check_korean_business_batch`, `verify_korean_business` |\n| REST API | `GET /v1/business/{number}/status` · `POST /v1/business/verify` · `POST /v1/business/batch` — see [REST API](#rest-api) |\n| Data source | Korea National Tax Service (국세청), official open-data API — queried live per request |\n| Data license | Korean government open data, **no usage restrictions** (이용허락범위 제한 없음) |\n| Privacy | Query contents are never logged — see [Privacy](#privacy) |\n| Region | Google Cloud Run, Seoul (asia-northeast3) |\n\n## Connect your agent\n\n### Claude (claude.ai)\n\n1. **Settings → Connectors → Add custom connector**\n2. URL: `https://kbv-server-f7vfitmlkq-du.a.run.app/mcp`\n3. Enable the connector in a chat and ask: *\"Check the status of Korean business 124-81-00998.\"*\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add --transport http kbv https://kbv-server-f7vfitmlkq-du.a.run.app/mcp\n```\n\n### ChatGPT\n\n1. **Settings → Connectors** (requires a plan with connector / developer-mode support)\n2. Add a custom MCP connector with URL `https://kbv-server-f7vfitmlkq-du.a.run.app/mcp`\n3. Enable it in a conversation and ask about a Korean business number.\n\n### Cursor\n\nAdd to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"korea-business-verify\": {\n      \"url\": \"https://kbv-server-f7vfitmlkq-du.a.run.app/mcp\"\n    }\n  }\n}\n```\n\n### Any other MCP client\n\nUse transport **Streamable HTTP** with the endpoint above. Clients must send `Accept: application/json, text/event-stream` (standard MCP clients do this automatically). Opening `/mcp` in a browser returns `Method not allowed` by design — browsers send `GET`, MCP uses `POST`. Use `/health` for a visual liveness check.\n\n## Tools\n\n### `check_korean_business_status`\n\nCheck the registration status of a Korean business by its 10-digit business registration number.\n\n**Input** — hyphens/spaces allowed; normalized internally:\n\n```json\n{ \"business_number\": \"124-81-00998\" }\n```\n\n**Output** (real example — Samsung Electronics):\n\n```json\n{\n  \"business_number\": \"1248100998\",\n  \"status\": \"active\",\n  \"status_code_raw\": \"01\",\n  \"tax_type\": \"general\",\n  \"closed_date\": null,\n  \"checked_at\": \"2026-08-24T10:08:20.082Z\",\n  \"source\": \"Korea National Tax Service (NTS)\",\n  \"cache\": false\n}\n```\n\n**Field reference:**\n\n- `status`: `active` | `suspended` | `closed` | `not_registered`\n- `tax_type`: `general` | `simplified` | `exempt` | `non_profit` | `unknown`\n- `closed_date`: ISO date (`\"2023-01-31\"`), only for closed businesses, otherwise `null`\n- `checked_at`: ISO 8601 UTC timestamp of the NTS query\n- `cache`: `true` only when the NTS API was temporarily unavailable and a cached result (max 24 h old) was served; `checked_at` then reflects the original fetch time\n\nA number that is well-formed but not registered with the NTS returns `\"status\": \"not_registered\"` (not an error).\n\n### `check_korean_business_batch`\n\nCheck **up to 100 businesses in a single call** — for screening supplier or customer lists without 100 round-trips.\n\n**Input:**\n\n```json\n{ \"business_numbers\": [\"124-81-00998\", \"220-81-62517\"] }\n```\n\n**Output** — one entry per input number (order preserved, same schema as above) plus a summary:\n\n```json\n{\n  \"results\": [\n    { \"business_number\": \"1248100998\", \"status\": \"active\", \"...\": \"...\" },\n    { \"business_number\": \"2208162517\", \"status\": \"active\", \"...\": \"...\" }\n  ],\n  \"summary\": { \"total\": 2, \"active\": 2, \"suspended\": 0, \"closed\": 0, \"not_registered\": 0 }\n}\n```\n\n- The whole batch is answered with **one** upstream NTS query.\n- Numbers checked within the last 24 hours may be served from cache (marked `\"cache\": true` with their original `checked_at`) and are excluded from the upstream query.\n- More than 100 numbers, or any malformed number, is rejected **before** anything is queried.\n\n### `verify_korean_business`\n\nVerify that a business registration number matches the provided representative name and opening date (KYB identity check), and get the current status in the same call.\n\n**Input:**\n\n```json\n{\n  \"business_number\": \"124-81-00998\",\n  \"representative_name\": \"홍길동\",\n  \"opening_date\": \"1969-01-13\",\n  \"address\": \"경기도 수원시\"\n}\n```\n\n- `representative_name` and `opening_date` (`YYYY-MM-DD`) are required.\n- `address` is optional and improves match precision.\n- Names and addresses should be given as registered with the NTS (Korean script).\n\n**Output** — same schema as above plus `identity_match`:\n\n```json\n{\n  \"business_number\": \"1248100998\",\n  \"status\": \"active\",\n  \"status_code_raw\": \"01\",\n  \"tax_type\": \"general\",\n  \"closed_date\": null,\n  \"checked_at\": \"2026-08-24T10:08:23.483Z\",\n  \"source\": \"Korea National Tax Service (NTS)\",\n  \"cache\": false,\n  \"identity_match\": false\n}\n```\n\n`identity_match` is `true` only when the NTS confirms that the number, representative name, and opening date all match its records.\n\n## REST API\n\nThe same three operations are available as plain HTTP endpoints — same JSON schemas as the MCP tools, no auth. **Append `?free=1` to use the daily free tier** (10 lookups per IP per day); without the flag, unpaid requests return `402` with x402 payment requirements:\n\n```bash\n# Registration status (hyphens in the number are fine)\ncurl \"https://kbv-server-f7vfitmlkq-du.a.run.app/v1/business/124-81-00998/status?free=1\"\n\n# KYB identity check\ncurl -X POST \"https://kbv-server-f7vfitmlkq-du.a.run.app/v1/business/verify?free=1\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"business_number\":\"124-81-00998\",\"representative_name\":\"홍길동\",\"opening_date\":\"1969-01-13\"}'\n\n# Batch status check (up to 100 numbers)\ncurl -X POST \"https://kbv-server-f7vfitmlkq-du.a.run.app/v1/business/batch?free=1\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"business_numbers\":[\"124-81-00998\",\"220-81-62517\"]}'\n```\n\nHTTP status codes: `200` success (including cache-served results), `400` invalid input, `402` payment required (no `?free=1`, or the daily free tier is exhausted — pay per call via x402), `503` NTS temporarily unavailable with no cached result.\n\n## Errors\n\nErrors are returned as MCP tool errors (or REST 4xx/5xx responses) with a machine-readable JSON body:\n\n| `error` | Meaning |\n|---|---|\n| `invalid_business_number` | Input is not a 10-digit number, or the date is not `YYYY-MM-DD`. Nothing was queried. |\n| `batch_limit_exceeded` | More than 100 numbers in one batch call. Nothing was queried. |\n| `invalid_request` | (REST only) The request body does not match the expected shape. |\n| `upstream_unavailable` | The NTS API is down or over quota and no cached result exists. Retry later. |\n\n## Data source and license\n\n- All data comes from the **Korea National Tax Service (국세청)** via the official Korean government open-data API (data.go.kr: 사업자등록정보 진위확인 및 상태조회 서비스), queried **live on every request** — KBV stores no business database.\n- The underlying dataset is published under the Korean government open-data policy with **no usage restrictions** (이용허락범위: 제한 없음), so responses may be used commercially and cited freely.\n- KBV normalizes the Korean-language, code-based NTS responses into the stable English JSON schema documented above; raw NTS payloads are never passed through.\n- Freshness: queries hit the NTS registry directly. Newly registered businesses may take 1–2 business days to appear in the NTS system itself.\n\n## Privacy\n\n- **Query contents are never logged.** Business numbers, representative names, and addresses appear in no server logs and are sent nowhere except the official NTS API that answers the query.\n- Server logs contain only request counts, outcomes, and latency metrics.\n- A short-lived in-memory cache (24 h max, hashed keys) exists solely so the service can answer during NTS outages; it is never shared or exported.\n\n## Pricing\n\n- **Free tier: 10 lookups per IP per day** (a batch call counts one per number), resetting at 00:00 UTC. No account or key is needed. MCP tools use it automatically; REST calls opt in by appending **`?free=1`** — without the flag, REST answers `402` with x402 payment requirements. MCP and REST share the same counter.\n- Beyond the free tier, the REST endpoints are **pay-per-call via the [x402](https://www.x402.org/) protocol** (USDC on Base mainnet, agent-payable — no signup):\n  - `GET /v1/business/{number}/status` — **$0.02**\n  - `POST /v1/business/verify` — **$0.05**\n  - `POST /v1/business/batch` — **$0.02 per number** (authorize up to $2.00, settled at actual usage)\n- Over-quota MCP tool calls return a `free_tier_exceeded` error that points to the paid REST endpoints above.\n- Fair use: the upstream NTS quota is shared; the free tier keeps light usage free while heavy traffic moves to paid calls.\n\n## FAQ\n\n**What is a Korean business registration number?** A 10-digit identifier (사업자등록번호, often written `123-45-67890`) issued by the Korea National Tax Service to every registered business in South Korea.\n\n**Can I check whether a Korean company is still operating?** Yes — call `check_korean_business_status`; `\"status\": \"active\"` means the business is currently registered and operating, `\"closed\"` includes the closure date.\n\n**Can I verify a Korean company's identity before a transaction (KYB)?** Yes — call `verify_korean_business` with the number, representative name, and opening date; `identity_match: true` means the NTS confirms all three match.\n\n**Can I screen a whole supplier list at once?** Yes — `check_korean_business_batch` (or `POST /v1/business/batch`) takes up to 100 numbers per call and returns per-number results plus a summary.\n\n**Do I need an API key?** No. Connect to the MCP URL and call the tools, or call the REST endpoints directly.\n\n## Self-hosting / development\n\nThe server is open for local development (Node.js ≥ 22, TypeScript, Express + official MCP SDK):\n\n```bash\ncp .env.example .env       # put your own data.go.kr DECODING key in NTS_SERVICE_KEY\nnpm install\nnpm run dev                # → http://localhost:8080  (MCP at /mcp)\nnpm test                   # vitest, upstream fully mocked — no network\n```\n\nDeployment guide (Google Cloud Run): see [DEPLOY.md](DEPLOY.md). Architecture and design spec: [DESIGN.md](DESIGN.md).\n",
  "bytes": 11475,
  "sha": "c7f45af51619012609528c1c2bcb5e94167beaee47f2083a79f241b69a89470e",
  "repo_slug": "wonderfulian/kbv-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wonderfulian_kbv_server_567dc80e/readme"
}