Drive the site with MCP tools

Connecting an agent gives you the tools. This page is about using them: the sequence a session follows, the write shapes, and the batching that decides whether an import takes two minutes or twenty.

The opening sequence, every session

1. get-skills, then get-skill on everything relevant to the task.
2. get-site-settings for the types that exist on this site.
3. get-navigations-with-pages when you are going to touch pages.

Skipping step 1 is what produces plausible YAML that does not match the platform. Skipping step 2 is what produces a call against a type that does not exist here.

Read before you write

The write shapes

The three rules behind most 422s:

• Wrapper: update-content writes under custom:, update-itemset-item under data:.
• References come in two shapes: media fields (image, file) take [{id: '<uuid>'}], every reference by id (items, smartselect on a collection, page) takes a flat ['<uuid>']. Never a bare UUID or a URL.
• One locale per write: main data plus one translations.<locale>, never a translation alone.

Full catalogue and per-tool notes in MCP tools.

Order of operations

Dependencies are real, and getting them wrong produces errors that look like something else.

1. collections, because a form's save and a query both target one by key.
2. Content-types and page-types.
3. Routes.
4. Pages, which freeze their page-type at creation.
5. Content: blocks and items.

Batching

Start from the shape of the work, not from a parallelism number. Most of what looks like a batching decision is actually a fan-out the API has already decided for you:

So a bilingual collection of twenty-six entries is fifty-two writes, not twenty-six, and no amount of batching changes that. Sizing the session on the entry count is how a "quick import" turns into an afternoon.

The discipline that matters is not the width of the fan, it is what you send into it. Get one call of a shape to succeed and read what came back, then fan out the other forty-nine. A wrong wrapper or a mis-shaped reference fails identically on the first call and on the fiftieth, and the fiftieth costs you the cleanup.

Serialise on purpose in two cases: when the calls depend on each other, which the order of operations above already tells you, and when you are debugging a shape and want each response attributable to one input.

Verify, do not assume

A tool call returning 200 means the write was accepted, not that the site renders. Close every session with a read-back:

• get-site-settings to confirm the types you created exist;
• get-page-with-content on one page you touched;
• quilium run plus a curl on the affected URLs.

Related