MCPortal

The missing bridge between data.go.kr and the global MCP ecosystem. MCPortal normalizes Korean public-API specifications into standard OpenAPI 3.1, compiles them into MCP servers, and puts every outbound call behind a hard daily budget with backoff and caching. Fully open source, fully self-hosted.

한국어 문서: README.ko.md — this English README is the canonical document and the Korean file is a translation of it.

Accuracy disclaimer

data.go.kr publishes no "remaining quota" endpoint. MCPortal's usage ledger therefore counts only the calls that went through MCPortal, which makes it a best-effort estimate. Calls that the same serviceKey spends outside MCPortal — another script, the portal console, a different tool — never reach the ledger, so the ledger value is always a lower-bound approximation of real consumption. The axis of trust is not that estimate but the hard budget cap (CALL_BUDGET). Even when the ledger is wrong, the hard guard physically blocks calls beyond the daily cap, so the safety line against quota-related account sanctions always comes from CALL_BUDGET.

The no-key boundary

Every demo, development and CI path in MCPortal runs without a key. The record/replay layer replays cassettes that were recorded earlier, so the same response flow can be reproduced and the whole test suite can go green with no serviceKey present. Spec-to-MCP conversion has already happened at build time — the compiled artifacts are committed under specs/ — so clone the repository and even standing up an MCP server and answering tool calls needs no key: mcportal serve 15000115 --replay serves eight tools over stdio with no serviceKey anywhere in the environment.

That sentence says clone on purpose. Replay needs a cassette, and cassettes are recorded upstream responses that stay in the repository instead of going out in the wheel (note 1), so a bare pip install mcportal has nothing to replay until it is pointed at a checkout with --presets-root <path> or MCPORTAL_PRESETS=<path>. Cassettes exist for three of the four bundles — 15081808 has none in the repository either, because it was deliberately left out of sampling (see Presets below), so that one bundle is live-only.

What does need a key is narrow: live traffic to data.go.kr, and sampling or converting an API that has no cassette yet.

Note 1 — what the wheel carries, and what it does not. Since 0.2.0, the published wheel carries the four preset bundles (16 bundle files plus the two presets/ documents, measured on the built artifact), so a plain pip install mcportal can run mcportal presets with no checkout. Since 0.2.2 the wheel also carries the three sampled_schemas.json files — 15000115, 15101612 and 15102108; 15081808 has none, because it was deliberately left out of sampling. They ship because mcportal compile --check needs them:

... View full README on GitHub