@cloudhal/mcp-server

The Model Context Protocol surface of Cloudhal (spec 2026-07-28, @modelcontextprotocol/server 2.3). ADR-0004 and ADR-0011.

Tools: every tool, with its scopes and whether a person approves it, is in the tool reference below, generated from the definitions in src/tools.ts (node scripts/mcp-tools-doc.ts; CI fails when it is stale). The server lists them in a fixed order. Every tool has JSON Schema input/output (built from the contract schemas), honest annotations and structuredContent. Updates need the current rev (optimistic locking). Every mutation snapshots automatically (exactly one snapshot per call; governance snapshots carry cloudhal.opId).

Taxonomy (RFC-0002): create_entry / update_entry take terms: { [taxonomy]: { set?, add?, remove?, primary? } } with values by id, slug, old slug, name, synonym or singular/plural, resolved by the store; an unknown or ambiguous value is an error with suggestions (unknown_term, ambiguous_term), never an implicit create. tags is a deprecated alias for terms.tag.add. list_entries takes the RFC §5 filter. Agents add terms only through propose_term (allowNewTerms: none → denied, propose → proposed, free → active; an existing match is returned). Structural tools (site:write) always wait for a person; their prompts list the articles touched and every redirect. Agents never redirect off-site, never reclaim slugs and never approve their own proposals (checked before anyone is asked). Store invariant errors map to stable codes (required_term, too_many_terms, …) with the next step in the text. Assignment deltas and governance results (opId, counts, redirects) go into the audit row's input.effect.

Approval: publish, rollback, delete_* and the structural taxonomy/redirect tools return MCP's multi-round-trip input_required with an elicitation (the message carries the diff summary) and an HMAC-signed requestState bound to the tool, the arguments and the principal. The person answers in their client; the call completes only on an explicit accept. Clients without elicitation get a confirmToken to pass on a second identical call (confirmTokenFallback: false turns that off).

Skills: skill://<name>/SKILL.md and skill://<name>/references/<file> resources. A client that follows a skill sends _meta["cloudhal.skill"] = "<name>"; the policy engine then limits the call to that skill's declared scopes.

import { createCloudhalMcpServer } from "@cloudhal/mcp-server";          // McpServer for one principal
import { serveCloudhalStdio } from "@cloudhal/mcp-server/stdio";          // what `cloudhal mcp` runs
import { createCloudhalMcpHandler } from "@cloudhal/mcp-server/http";     // fetch(request, principal) — mounted at /mcp by @cloudhal/api

tools.ts is SDK-independent (defineTools(), runTool() = policy → audit → handler) and is what the tests exercise first; test/e2e.test.ts runs a real client ↔ server pair over the in-memory transport and proves the Sprint 5 exit criterion.

Tool reference

110 tools, in the order the server lists them.

| Tool | Scopes | Kind | Approval | What it does | |---|---|---|---|---| | list_sites | site:read | read | — | Sites this principal can operate. | | get_site | site:read | read | — | A site with its page order, locales, theme, published snapshot and per-collection settings (collections.<key>.permalink, e.g. /blog/{slug}; a collection without one lives at /<c… | | list_pages | content:read | read | — | Pages of a site in navigation order (all statuses). | | get_page | content:read | read | — | One page with its sections and current revision (send rev back when updating). | | create_page | content:write | write | by the key's mode | Create a draft page and append it to the site's navigation. | | update_page | content:write | write | by the key's mode | Replace a page's title, path, sections or seo, or set its own motion level and chrome (RFC-0025: header default|transparent|hidden, footer default|minimal|hidden; null goes back t… | | get_catalog | content:read | read | — | The components a page surface may use on this site (RFC-0020): Cloudhal's layout, content and interactive primitives plus the theme's block types, with their props, child rules, b… | | patch_draft | content:write | write | by the key's mode | Build or change a page step by step with RFC 6902 JSON Patch operations on /title, /sections and /seo, e.g. {"op":"add","path":"/sections/-","value":{…a surface…}}. | | import_surface | content:write | write | by the key's mode | Add (or replace) a page surface from another generative-UI format: a2ui takes A2UI v0.9 messages (createSurface, updateComponents, updateDataModel; basic catalog), json-render… | | export_surface | content:read | read | — | A page's surface section in another generative-UI format: a2ui (A2UI v0.9 messages for the basic catalog, images as absolute URLs when the site has a primary domain) or json-re… | | delete_page | content:write | write (destructive) | by the key's mode | Delete a page and remove it from navigation. | | list_entries | content:read | read | — | Content entries, newest first. | | get_entry | content:read | read | — | One content entry with its body and current revision. | | create_entry | content:write | write | by the key's mode | Create a draft content entry (markdown body) in an existing collection (list_collections; a new one needs create_collection first), optionally filed under existing terms (terms;… | | update_entry | content:write | write | by the key's mode | Update title, summary, body, slug, status (draft → review → published), terms (terms: add, remove or set categories and tags by id, slug or name) or typed custom fields (fields… | | add_correction | content:write | write | by the key's mode | Append a correction, clarification or update notice to an article (RFC-0019 §2) when a published story changed in substance. | | delete_entry | content:write | write (destructive) | by the key's mode | Delete a content entry. | | list_translations | content:read | read | — | Every language version of a page or entry (its translation group): locale, status, method (original, human, machine, machine-reviewed), whether it is stale (its source changed sin… | | list_stale_translations | content:read | read | — | Translations whose source changed since they were made (or whose source is gone), optionally in one locale: the work queue for keeping languages in step. | | get_translation_source | content:read | read | — | What you need to translate a page or entry into locale: the source (translate its title, text, summary and SEO; keep section ids, kinds, links, numbers, images and bindings), fo… | | save_translation | content:write | write | by the key's mode | Save your translation of a page or entry into locale as a draft linked to the source's current revision, with your model as its provenance. | | search_site | content:read | read | — | Find nodes by words instead of listing everything. | | get_theme_settings | content:read | read | — | The theme's design settings (RFC-0017): their schema (colors as #rrggbb, enums, numbers; per-locale titles), the contrast rules colors must meet, and the site's current values. | | set_theme_settings | site:write | write | always a person | Change the site's design settings (colors, type, spacing: get_theme_settings lists them). | | list_block_types | content:read | read | — | The typed blocks this site can use (RFC-0015): callouts, buttons, video embeds, FAQs and the theme's own. | | get_body | content:read | read | — | Read a markdown body (an article's, or a page's rich-text section) as blocks: each with its id, hash, type, markdown and who last changed it. | | edit_body | content:write | write | depends on the call | Change a markdown body by block instead of rewriting it: replace a block, replace text inside one, insert, move or delete blocks, insert a typed block (insertBlock: a callout, a b… | | diff_node | content:read | read | — | Compare one page or article between two versions: the fields that changed, and its body (or each rich-text section) block by block, with the words that changed inside edited block… | | get_design | site:read | read | — | Read this first when you build or redesign pages (RFC-0021). | | get_design_tokens | site:read | read | — | The site's design tokens as a W3C Design Tokens (DTCG 2025.10) file, for Figma (Tokens Studio), Style Dictionary or a designer: the color roles for light and dark, corner radii, s… | | set_design | site:write | write | always a person | Replace the site's design rules (DESIGN.md, Markdown, at most 24,000 characters; null removes them). | | get_chrome | site:read | read | — | The site's header, footer and brand (RFC-0025): what is set, what pages show (the defaults filled in), the form schemas with every allowed value, and the menu keys the header and… | | set_chrome | site:write | write | always a person | Change the site's header and footer (get_chrome lists the fields and allowed values). | | set_brand | site:write | write | always a person | Change the site's brand (get_chrome lists the fields): logo and logoDark as an image asset of the site (asset:<id>, from list_assets or upload_asset; the site's name shows without… | | render_page | preview:create | read | — | Look at a page's draft as people will see it: renders it in a real browser at desktop (1440), tablet (768) and phone (390) widths and returns screenshots plus automatic checks (si… | | list_taxonomies | site:read | read | — | The site's taxonomies (e.g. category, tag) and their rules: required (review/published articles need a primary term), maxPerEntry, allowNewTerms (none: only people add terms… | | list_terms | content:read | read | — | Terms of one taxonomy with names per locale, synonyms (altNames), old slugs (slugHistory), parent, status, visibility and usage (articles in total and published, last used). | | resolve_terms | content:read | read | — | Which existing terms of a taxonomy the given ids, slugs, names or synonyms mean (the same rules as assigning terms: id → slug → old slug → name → synonym → singular/plural). | | propose_term | content:draft:own | write | by the key's mode | Suggest a new term when no existing one fits (check list_terms / resolve_terms first). | | update_term | content:write | write | by the key's mode | Change a term's text only: names, synonyms, archive intro (description) and SEO per locale, and its image. | | rename_term | site:write | write | always a person | Change a term's slug (its archive URL). | | merge_terms | site:write | write | always a person | Merge duplicate terms into one target term of the same taxonomy: every article is re-filed under the target (primary terms follow), the sources retire and their names and slugs be… | | retire_term | site:write | write (destructive) | always a person | Retire a term: it is removed from every article, its sub-terms move up, and its archive redirects (301) to redirectToId (or, for categories, to its parent) — without a redirect… | | set_term_parent | site:write | write | always a person | Move a term under another term of the same hierarchical taxonomy (null: to the top level). | | set_term_visibility | site:write | write | always a person | Make a term public (archive, feed and sitemap entry; shown on articles) or internal (no public URL; themes and filters may still use it). | | review_term | site:write | write | always a person | Decide on a proposed term: approve (it becomes active and, if public, gets its archive), reject (retired and removed from articles) or merge (into an existing term, mergeIntoId). | | taxonomy_report | content:read | read | — | Findings about the vocabulary: single-use and unused terms, near-duplicates (edit distance ≤ 2, singular/plural) and synonym collisions, empty or oversized categories, archives wi… | | create_taxonomy | site:write | write | always a person | Create a taxonomy (e.g. series, region) with its rules and archive path. | | update_taxonomy | site:write | write | always a person | Change a taxonomy's rules, labels or archive (the key never changes). | | list_redirects | site:read | read | — | The site's redirects (from → to, 301/302, exact/prefix, reason, source node). | | create_redirect | site:write | write | always a person | Redirect a path the site no longer serves to another path of this site (agents cannot redirect to other hosts). | | delete_redirect | site:write | write (destructive) | always a person | Delete a redirect; its old path then answers 404 unless something serves it. | | list_collections | content:read | read | — | The site's collections (RFC-0040): declared ones, ones that already have entries, and posts. | | create_collection | site:write | write | always a person | Declare a new collection (RFC-0040), e.g. events, team or jobs, with its names in the site's default locale (labels), an optional icon, permalink (/<prefix>/{slug}, default /<key>… | | update_collection | site:write | write | always a person | Change a collection's names (merged per locale), icon, feed, sitemap, default sort (RFC-0040) or its typed custom fields (fields, the whole list; RFC-0041), list fields, date-dr… | | preview_structured_data | content:read | read | — | The JSON-LD document an entry's page emits under its collection's structured-data preset (RFC-0042: Event, JobPosting, Product, Recipe), built exactly as the site builds it, with… | | rename_field | site:write, content:write | write | always a person | Rename a typed custom field's key (RFC-0041 §6): every entry's value moves from from to to; nothing is converted. | | change_field_type | site:write, content:write | write (destructive) | always a person | Change a typed custom field's type, or a select's multiple (RFC-0041 §6), converting every value by a closed table (text↔richText, text↔number, text↔select, text↔url, date↔datetim… | | set_field_localized | site:write, content:write | write | always a person | Make a typed custom field localized (each language version has its own value; translations fall back to the original's) or shared (only the original holds it; translations' own co… | | remove_field | site:write, content:write | write (destructive) | always a person | Remove a typed custom field (RFC-0041 §6): its value is deleted from every entry, then its definition. | | set_collection_permalink | site:write | write | always a person | Move where a collection's entries live (RFC-0038): permalink "/blog/{slug}" puts collection "posts" at /blog/<slug>; null goes back to the default /<collection>/{slug}. | | list_menus | site:read | read | — | The site's navigation menus (primary = header, footer, sidebar, custom keys) with id, rev, maxDepth, item count and how many items are hidden on the site. | | get_menu | site:read | read | — | One menu: the stored tree (send its rev back when writing) and, per item for a locale, whether the site shows it (state), why not (reason: missing, unpublished, other-locale,… | | update_menu | site:write | write | always a person | Edit a menu with operations, applied in order and all or nothing: add {item, parent?, index?}, remove {itemId} (with its subtree), move {itemId, parent?, index?}, update {itemId,… | | set_menu | site:write | write | always a person | Replace a menu's whole tree (or create the menu: omit rev). | | delete_menu | site:write | write (destructive) | always a person | Delete a menu; the site falls back to the theme's derived default for that key (e.g. top-level pages in the header). | | list_assets | content:read | read | — | Files of a site's media library, newest first: images, video, audio, documents and data. | | get_asset | content:read | read | — | One file of the media library with its URL, checksum file and every place that uses it (node, field and title). | | upload_asset | asset:upload | write | by the key's mode | Add a file to the site's media library from base64 data (at most 4 MB decoded). | | fetch_asset_url | asset:upload | write | by the key's mode | Have the server download a public https file (at most 25 MB) into the site's media library: the server fetches it under strict rules (https only, no internal hosts or IP addresses… | | update_asset | asset:upload | write | by the key's mode | Change a file's alt text, title or caption (in locale), credit, license, decorative flag, URL slug or an image's focal point (focal: where the subject is, x and y from 0 to 1… | | retire_asset | asset:manage | write | by the key's mode | Hide a file from the library and pickers so nothing new uses it. | | restore_asset | asset:manage | write | by the key's mode | Make a retired file available again. | | delete_asset | asset:manage | write (destructive) | by the key's mode | Delete a file from the media library. | | create_snapshot | content:draft:own | write | by the key's mode | Freeze the current state of the site as an immutable, labelled snapshot. | | list_snapshots | site:read | read | — | Snapshots of a site, newest first, and which one is live. | | diff_snapshots | site:read | read | — | Added, changed and removed nodes between two snapshots. | | preview_page | preview:create | read | — | Render a page (or an article by entryId) to HTML as the site would show it, plus a preview link (signed, to the deployed site, or the cloudhal dev URL). | | publish | site:publish | write (destructive) | always a person | Snapshot the current state and make it live. | | rollback | site:rollback | write (destructive) | always a person | Point production at an earlier snapshot (must be an ancestor of the live one). | | get_analytics | analytics:read | read | — | How the site is doing over a range: page views, visits (entrances from other sites or typed in), unique visitors when the site counts them, the estimated cache-hit ratio (on Cloud… | | top_content | analytics:read | read | — | The most viewed pages, articles and archives in a range, with their current title and path (renamed articles show their new ones; deleted ones read as gone) and the change of page… | | content_stats | analytics:read | read | — | Readers of one page, article or archive (by id, so the history survives slug changes): page views and visits with the previous period, a series, visits by channel, referrer hosts,… | | broken_links | analytics:read | read | — | Requests that ended in 404 or 410 in a range, most hits first, with the same-site pages that link to them, when they were last seen and a suggested target (an existing redirect, o… | | list_comments | comments:read | read | — | Reader comments of a site, newest first (status pending, approved, hidden, spam, deleted, or reported for open reports). | | get_comment_thread | comments:read | read | — | One article's comments in display order (top level oldest first, each followed by its replies), with the thread's state and open reports' details. | | comments_summary | comments:read | read | — | Counts for a site's comments: by status, pending ages, open reports, the busiest threads, labels, unanswered questions and the daily cap. | | label_comments | comments:moderate | write | depends on the call | Add or remove advisory labels on up to 50 comments (spam-suspect, toxic, off-topic, question, needs-reply, praise, personal-data, …) for the people who review them. | | moderate_comments | comments:moderate | write | depends on the call | Change the status of up to 50 comments. | | draft_comment_reply | comments:reply | write | depends on the call | Draft a reply on the site's behalf to an approved comment (plain text, 2–5,000 characters). | | set_comment_thread | comments:moderate | write | depends on the call | Set an article's comment thread: closed (no new comments, existing ones stay) and hidden (nothing shown) reduce visibility; open, default and a closesAt date wait for a person in… | | list_schedule | schedules:read | read | — | What happens on the site between from and to (at most 62 days): releases (scheduled publishes), time gates (embargoes and expiries on articles and pages) and automation runs, with… | | get_schedule | schedules:read | read | — | One item from list_schedule by its id (rel_…, gate:<nodeId>:from|until, occ:<automationId>:<at>), with detail. | | list_releases | schedules:read | read | — | The site's releases (scheduled publishes) in time order, by state: draft, awaiting_approval, scheduled, running, published, conflict, missed, expired, failed, canceled. | | get_release | schedules:read | read | — | A release with its pinned items (titles, paths, pinned and live versions), what the dependency closure added, overlaps with other releases, locked nodes, the approval and the wait… | | propose_release | schedules:write | write | depends on the call | Leave a draft release for a person: the named articles and pages are pinned at their current versions (plus what they need that is not live yet), optionally with a time. | | schedule_release | schedules:write | write | depends on the call | Publish a release (or the named articles and pages, pinned now) at a time, or "on-approval". | | reschedule | schedules:write | write | depends on the call | Move a release to another time. | | cancel_schedule | schedules:write | write | depends on the call | Withdraw a release: nothing in it is published. | | set_embargo | schedules:write, content:write | write | depends on the call | Keep an article or page off the live site until from (an instant): it is absent from every page, list, feed and sitemap until then, enforced by the site itself. | | lift_embargo | schedules:write | write | depends on the call | Ask a person to publish an article or page before its embargo (remove from, or move it earlier). | | schedule_unpublish | schedules:write, content:write | write | depends on the call | Take an article or page off the live site at a time (it disappears from every page, list, feed and sitemap from then on, enforced by the site itself). | | list_automations | schedules:read | read | — | The site's automations: built-in jobs and scheduled agent tasks, with their recurrence, state and next run. | | list_runs | schedules:read | read | — | What happened at each occurrence of an automation or release, newest first: state (ran or not) and outcome (did something or not), usage, taint and the summary. | | get_run | schedules:read | read | — | One run with the audit rows, snapshots and approval requests it produced. | | begin_run | | read | — | Start this automation's run while its window is open (its key works only inside a run). | | end_run | | read | — | Close your run with a short plain-text summary (what you did, what a person should look at) and its outcome: did-work, nothing-to-do, proposed (you left proposals) or waiting-appr… | | pause_automation | | read | — | Stop an automation from running again (your own automation's key, or an automation of the person behind your key). | | get_mode | | read | — | Your current mode, your key's own mode, any time-boxed elevation in force (and when it ends), and the status of your latest elevation request. | | request_elevation | site:read | read | — | Ask a person for a more autonomous mode for a limited time (5–1440 minutes), e.g. AUTO for an hour to publish a series of small article updates. |