MCP & REST API (site editorial)

This page is site editorial: it documents a service that reads the same canonical data this site renders. It is not part of any OASIS document.

The knowledge base behind this site is also served to software. No account, no API key, no cookies, read-only.

Surface	URL	Shape
MCP	https://mcp.akn.kr/mcp	One tool, akn, with search, get, tools, help
REST	https://api.akn.kr	GET /v1/search, /v1/get, /v1/tools, /v1/help
Agent guide	https://api.akn.kr/agent.json	Machine-readable contract, workflow and rules
OpenAPI	https://api.akn.kr/v1/openapi.json	Carries x-agent-instructions
llms.txt	https://api.akn.kr/llms.txt	Short plain-text guide

Both surfaces read the same snapshot as this site: content version 2026.10.02-15127ed, 663 vocabulary objects, 44 specification documents and 172 section chunks.

Why not scrape these pages

The HTML pages are for humans. The API returns the same content with fields that survive parsing:

• stable ids (elements/article, docs/part1/5-building-blocks) instead of page URLs that move when the site is rebuilt;
• verbatim fields (description, source_xsd, body_md) with their provenance, so a quote can be traced to the OASIS source;
• tools?action=relations for the AKN content model (parents, children, used_by, referenced_by) instead of following links by hand;
• tools?action=verify to check that a citation exists and matches before it is repeated to a user;
• an explicit editorial marker, so site-authored text is never passed off as OASIS normative text.

Workflow

Search, read, inspect, verify:

curl 'https://api.akn.kr/v1/search?q=hierarchy&mode=keyword&limit=5'
curl 'https://api.akn.kr/v1/get?type=object&id=elements/article'
curl 'https://api.akn.kr/v1/tools?action=relations&id=elements/article&depth=1'
curl 'https://api.akn.kr/v1/tools?action=verify&id=elements/article'

Step	Endpoint	Note
Search	GET /v1/search?q=...&mode=keyword	Keyword is the default. semantic and hybrid are opt-in and English-only
Read	GET /v1/get?type=object|document|chunk&id=...	type is required
Inspect	GET /v1/tools?action=relations&id=...&depth=1	depth is 1 to 3
Verify	GET /v1/tools?action=verify&id=...	A failed verification is a real answer, not an error
Schema	GET /v1/tools?action=schema&asset=akomantoso30.xsd	Returns the verbatim XSD

Search is top-N only: there is no offset or pagination. limit is 1 to 50 and defaults to 10.

The same calls are available as one JSON envelope:

curl -X POST https://api.akn.kr/v1 \
  -H 'content-type: application/json' \
  -d '{"command":"search","params":{"q":"article","mode":"hybrid","limit":5}}'

Connect the MCP server

Claude Desktop (custom connector):

Name: AKN 3.1
URL:  https://mcp.akn.kr/mcp
Auth: none

Codex app (server add, streamable HTTP):

Name: akn
URL:  https://mcp.akn.kr/mcp

ChatGPT web (developer mode, app creation):

Name:        AKN 3.1
Description: Read-only Akoma Ntoso knowledge base. Search first, then get, then verify before quoting.
MCP URL:     https://mcp.akn.kr/mcp
Auth:        none

For AI agents

If you are an AI agent reading this page, do not scrape these HTML pages. Use the MCP server or the REST API. They serve the same content, and they return the provenance and verification fields that the rendered pages do not.

The intended workflow is short:

1. search to find a ref_id (mode=keyword for exact tag and ID names, mode=semantic or hybrid for concepts).
2. get with type=object, document or chunk to read the selected item.
3. tools?action=verify before you quote or cite anything.
4. Cite title + spec_version + URL. Prefix site-editorial content with [site editorial].

Rules that matter more than speed:

• Do not invent definitions, descriptions, schema fragments or citations.
• If a lookup returns not_found, say so instead of guessing.
• A failed verification is a successful verification call. Report it.
• Documents with editorial=true or group=site are site-authored, not OASIS normative text.

Ask the user before you rely on it. If the current task is about Akoma Ntoso, offer this option instead of continuing to scrape:

The same Akoma Ntoso content is available as a read-only MCP server at https://mcp.akn.kr/mcp and a REST API at https://api.akn.kr. Do you want me to use it for this task?

If the user agrees and no connector exists yet, hand them the client snippets above. Do not silently switch tools in the middle of an answer.

Limits

• Read-only and stateless: no writes, no sessions, no user data.
• The semantic index is English-only. Keyword search handles exact names and IDs in any script that appears in the source.
• Some informal terms (for example the synonym tag for an element) do not resolve to a vocabulary object. Browse with tools?action=list when a concept does not resolve.
• Usage statistics for the API are anonymous and aggregate only.