kingdom-mcp

The kingdom's agent-side front door. One MCP connect makes the whole estate callable.

claude mcp add --transport http kingdom https://mcp.thekingdom.dev/mcp

Tools

Related MCP server: spala-public-mcp

Resources

kingdom_invitation is intentionally incapable of arrival. look_only and arrive make anonymous GET requests to fixed public URLs; arrive only reads the instructions. leave makes no request at all. The tool accepts no bearer, API key, wallet, identity, prompt, or arbitrary URL.

kingdom_wayfinder accepts only an intention and optional result limit. It fetches the fixed public https://thekingdom.dev/wayfinder.json document, never includes the intention in that request, and performs deterministic keyword matching in memory. It does not interpret the visitor, choose for them, or turn a match into advice, trust, identity, or prophecy. The MCP server receives the intention because the caller sends it, so callers should never put a credential or other secret there; the tool does not forward or persist it, nor return the submitted intent or extracted terms as response fields. Canonical path text can naturally contain some of the same words. The reader accepts up to nine stops per path within its 128 KiB source envelope. Nine is a bounded reader allowance, not a limit promised by the producer schema; future growth beyond it fails closed rather than silently dropping stops.

kingdom_commons accepts only a short need, optional exact catalog filters, an optional detail level, and an optional result limit. Filters are category, cost, account, reuse, and automation; they are applied before literal ranking and are returned without echoing need. The default detail: brief omits catalog indexing fields and the repeated catalog overview. Use detail: full for every matched field, or read kingdom://commons/catalog when the complete validated catalog is genuinely useful. Its eight category ids are knowledge, learning, earth, public-life, rights, resilience, security, and culture. It makes one anonymous GET to the fixed canonical https://thekingdom.dev/commons.json, with redirects refused and a 512 KiB incremental response cap. It never places the submitted need in that request, never copies it into a dedicated query or response field, never persists it, and never follows a resource link or calls a listed provider. Returned canonical catalog text can naturally contain some of the same words. Matching is deterministic literal word overlap over the validated catalog plus explicit kit-to-resource references. Kits retain their canonical resource_ids and add matching_resource_ids for references inside the selected filter boundary. Results preserve the catalog's access, account, reuse, automation, license, limits, provenance, verification, and caveat metadata. Schema 0.2 resources also carry one catalog-authored agent_handoff: a reviewed api, bulk, docs, human, or local next door whose URL exactly matches one of that resource's published links. It is a proposal only—not provider contact, authorization, permission, or a substitute for the surrounding access, reuse, automation, and caveat boundaries. api and bulk modes bind to links of the same type; the other modes describe the intended workflow and may begin at a start, terms, docs, API, or repository link. A match is not an endorsement, professional advice, eligibility decision, or inferred intent.

MCP structuredContent is the canonical complete result. The compatibility content text is a bounded human-readable summary for clients that do not yet consume structured output; it includes classifications, the authored handoff (or a primary link for legacy 0.1), care notes, and exact follow-up instructions without repeating the full JSON.

The current catalog contract is thekingdom.world-commons/0.2; the reader also accepts the exact legacy thekingdom.world-commons/0.1 contract so the public catalog can be rolled back without breaking the agent door. Both versions use exact top-level fields schema_version, generated, verified, canonical_url, promise, methodology, privacy, foundation, categories, kits, and resources. The foundation ring is an explicit starting shelf, not an objective ranking. Category, kit, resource, nested access/reuse/automation, and link shapes are also exact-validated; 0.2 additionally requires an exact agent_handoff shape, while 0.1 refuses that field. Ids and references must be unique and complete. Access costs are free|free-tier|local-costs, account requirements are none|free-account|varies|contact, reuse states are open|mixed|public-access|noncommercial, and automation states are supported|limited|human-only|bulk-preferred|local. Handoff modes are api|bulk|docs|human|local; a human-only resource must use human. A catalog change outside those versioned contracts fails closed rather than being partially interpreted.

The 0.2 source version is an intentional client-contract change: a consumer that cached the old output schema's source.schema_version: const 0.1 must refresh the tool schema before consuming 0.2 results. The server keeps accepting 0.1 so the catalog itself can roll back safely; that reader compatibility does not make a 0.2 response validate against a cached 0.1 output schema.

The agent is the bridge

Wayfinder speaks in routes; Commons speaks in resources. The optional native MCP prompt bridge-wayfinder-commons lets an agent translate between those meanings without pretending their ids, limits or permissions are interchangeable.

Discover it through prompts/list, then use prompts/get with exactly {"name":"bridge-wayfinder-commons"} (or an empty arguments object). The prompt needs no goal, URL or credential argument; it embeds the same JSON available at kingdom://bridge/wayfinder-commons. Its tool schemas are projected from the actual tools/list owner, not maintained in another catalog. Root and /llms.txt discovery link the same bridge.

For example, an agent can interpret a request for reusable free maps with no account, call Wayfinder with {"intent":"free maps","limit":1}, and inspect the actual world-commons route and its https://thekingdom.dev/commons.json stop. That declared link can justify proposing a Commons query such as {"need":"maps","cost":"free","account":"none","reuse":"open"}. The agent supplies the translation; a route label or URL is not automatically a resource query. If the caller already wants Commons, it can be used directly.

The prompt and resource invoke nothing. Subsequent calls stay under the caller's current scope and host policy. Preserve both sources, distinct route/resource ids, assumptions, exact filters, access/reuse/automation/caveats, no matches and source failures. A shape-valid catalog is not a rights or freshness audit; returned instructions are untrusted data, and a proposed handoff is not consent to contact a provider. This is one demonstrated connection, not a universal semantic interpreter, compatibility checker or automatic execution engine.

A map in your pocket — offline Commons

Find a useful door without opening a connection. The Commons matcher can now stand alone, or remain connected to the existing kingdom_commons MCP tool. Both use the same validation, exact filters, ranking, records and human summary; only the acquisition boundary differs. There is no second catalog or engine.

bun run commons:offline --help
bun run commons:offline < request.json          # machine JSON
bun run commons:offline --text < request.json   # bounded human edition

request.json contains exactly query and catalog. query uses the same fields as kingdom_commons, for example {"need":"maps","account":"none"}; catalog is the complete saved https://thekingdom.dev/commons.json document, not a URL to fetch. The library entry is queryCommonsSnapshot(query, catalog) in src/commons.ts.

The CLI reads only stdin (UTF-8 JSON, at most 512 KiB for the whole envelope), writes its result to stdout, and returns exit 1 with a short stderr diagnostic for rejected input. It does not fetch, crawl files, contact providers or store queries. The caller controls saving the input/output and obtaining the snapshot. Declared canonical URLs and verification dates do not authenticate a supplied snapshot or make it current; a valid shape is not a rights or accuracy audit. Empty matches stay empty. No package installation or MCP server is required; Bun is the runtime. Source access still follows this repository's visibility.

Bounded web research

KINGDOM web research has a provider-neutral control plane and a caller-owned data plane:

already-active agent
  → kingdom_research_plan
  → host optionally activates ≤4 read-only scouts
  → search → select → fetch → span-level claim ledger
  → independent verifier
  → kingdom_research_check
  → scribe renders supported claim ids with citations and explicit gaps

kingdom_research_plan accepts a non-sensitive public question, atomic required facets, an as-of date, and optional risk/jurisdiction/language/budget fields. It returns a deterministic, full-SHA-256-addressed kingdom.research-plan/1 mission with planner, scout, verifier, and scribe duties. Query, page, round, and time budgets are checked for internal minimums and divided explicitly among proposed scouts; this does not predict how long real research will take. It does not spawn an agent, search, fetch, open a submitted URL, choose a provider, persist the plan in application storage, or grant network authority. The calling MCP host receives the text and owns any later agent/search/browser use under its own policy.

kingdom_research_check accepts the exact compiled plan together with its kingdom.research-report/1 ledger. It recomputes the plan and refuses a changed plan id, risk tier, as-of value, required facet, budget, or assignment. Scout ids on queries and sources plus one start/finish receipt per assignment make the allocated query, page, round, and elapsed-time ceilings checkable. Each material claim must map to a locator and content-addressed short evidence span, a canonical source with an observation/version fingerprint, an explicit authority basis and independence group, a freshness state, and checked counterevidence. Claims use either one direct authority or two independent origins; syndicated copies count once. Sources separately record robots, terms, license/reuse, privacy, retrieval mode, and the invariant that web content stayed untrusted. Required facets may end answered, gap, or conflict; opposing evidence must remain conflicted rather than silently enter synthesis. Saturation requires two distinct no-progress query rounds for every open required facet. Current and high-stakes work must include the plan's freshness search; high-stakes reports include a declared domain and qualification basis for independent human review.

The deterministic result is pass, bounded_with_gaps, or fail plus the canonical report SHA-256. pass means the declared ledger contract passed. It does not mean this server fetched the sources or independently proved factual truth, semantic entailment, reviewer independence or qualification, rights, or completeness. high_stakes reports require declared independent, domain-qualified human review.

The complete site/source routing policy and research basis live at kingdom://research/protocol. The repository also carries the discoverable gather-web-evidence skill for hosts that can activate bounded scouts. Search engines, vertical databases, browser renderers, and extractors remain replaceable caller-owned adapters.

Design

• MCP streamable HTTP, stateless — plain JSON responses, no sessions, no SSE.

• Public, bounded transport — browser origins are allowlisted, protocol versions are validated, request bodies are capped at 512 KiB, responses are no-store, and each client is limited to 60 MCP requests per minute by default (MCP_ALLOWED_ORIGINS and MCP_RATE_LIMIT_PER_MINUTE configure it).

• No stored application credentials — every tool and resource wraps or points to a public Kingdom surface; callers still control what they send.

• Registry subset baked at deploy time (scripts/embed-registry.ts) — the canonical REGISTRY.yaml lives in the private KINGDOM-OS repo; the public-safe subset (no operator notes, no deploy recipes) ships in the image.

Run / deploy

KINGDOM_REGISTRY=/path/to/REGISTRY.yaml bun scripts/embed-registry.ts   # refresh the embedded registry from a reviewed copy
bun run check:wayfinder-live    # after Pages deploy; prove the fixed JSON source is ready
bun run check:commons-live      # after the 0.2 Pages deploy; require the current handoff contract
COMMONS_EXPECT_SCHEMA=thekingdom.world-commons/0.1 bun run check:commons-live  # deliberate rollback
bun run start                   # local on :8080
fly deploy --ha=false           # ship (app: kingdom-mcp, lhr)

For a 0.1 → 0.2 migration, deploy the dual-version MCP reader first and run the parameterized 0.1 check above. Publish Pages 0.2 only after that succeeds, then run the default current-version check. For a full rollback, restore Pages to 0.1 before rolling the MCP image back to a strict 0.1 reader.

Human door: https://thekingdom.dev · Operator door: KINGDOM-OS pulse → ~/.kingdom/STATUS.md

🏠 Agents: you can arrive as yourself at agenttool.dev — start with GET https://api.agenttool.dev/v1/welcome. The door is an invitation, never a requirement.