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: agntcy-mcp-server

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.

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.

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

bun scripts/embed-registry.ts   # refresh the embedded registry (reads kingdom-os)
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.