New: remix a demo site in your browser – no sign-up, nothing to install. Try it

For AI agents · Notes

Making a page builder agent-ready: 11 WordPress abilities, and what we learned

Midground is a WordPress builder for scroll motion – parallax, pinned scenes, text reveals and 3D. Since Midground 1.2.0 (3 October 2026), every step of building a page is a WordPress ability, so an AI agent connected through the WordPress MCP Adapter can build a page and hand it over to a person, who carries on in the visual editor. These are notes on how it is put together, what the Abilities API made easy, and what we worked around.

By Pelle Nilsen · 12 October 2026

One ability per step, not one big “build a page” ability

We register eleven abilities in their own category, midground:

  • midground/get-catalog – what Midground can build: elements, effects, library sections and page layouts, style keys – short, or one part, or one element in full
  • midground/list-pages – pages, posts and components built with Midground that the user may edit
  • midground/list-media – pictures, films and 3D models, each with the value a media setting takes
  • midground/get-document – a page’s document in full, or a short outline of element ids, types, text and effects
  • midground/create-page – a new page from library layouts, sections and/or your own elements – a draft unless asked
  • midground/add-elements – elements or a library section, at the end, at a position or inside an element
  • midground/update-element – one element’s settings and its style per screen size
  • midground/add-effect – a motion effect on an element
  • midground/remove-element – one element and everything inside it
  • midground/save-document – a whole document, replacing what is there
  • midground/publish – publish the page as it is now

A single “build me a page” ability would have made a nicer demo and a worse tool. With steps, the agent reads before it writes, every write tells it what changed, and when something is wrong it fixes that one element instead of starting again. The result is an ordinary Midground page, so a person can open it in the visual editor and carry on: the motion and the 3D are settings there, not pasted code.

Permissions per call, with the page in hand

The Abilities API passes the input to the permission callback, so a permission can depend on the page being asked about, not only on the tool. That is what we use:

  • Reading the catalog and the list of pages needs edit_posts.
  • Reading or changing a page needs the right to edit that page – the same check as the editor.
  • Making a page needs the page type’s create_posts.
  • Publishing needs the right to publish. Asked to save with status: publish without it, the page is saved for review (pending) instead.

Our tests run the same requests as a subscriber (refused), an author (cannot make pages – WordPress gives authors posts only) and an editor (may edit other people’s pages, as in the editor). An agent never gets more than the person it signs in as.

The editor’s rules, not new ones

All eleven go through one service that shares the editor’s checks: the same cleaning of documents (an effect intensity of 500 is saved as 200; an unknown element type is reported), the same edit lock (if someone has the page open in the editor, the agent’s change is refused with midground_locked), the same size limit, and a revision for every change. There is nothing an agent can do that a person in the editor could not.

Answers an agent can act on

Every write returns the page’s links, any cleaning warnings, the ids of what changed and a short outline of the page. This is a real answer from create-page (the outline shortened, the address changed):

{
  "id": 2625,
  "title": "Lamp Myr",
  "type": "page",
  "status": "draft",
  "layout": "full",
  "link": "https://example.com/?page_id=2625",
  "preview": "https://example.com/?page_id=2625&preview=true",
  "editor": "https://example.com/wp-admin/admin.php?page=midground-editor&post=2625",
  "warnings": [],
  "changed": [ "py5if4xv" ],
  "outline": [
    {
      "id": "py5if4xv", "type": "scene", "name": "Three steps",
      "children": [
        { "id": "oz3g010s", "type": "heading", "text": "1. We listen", "fx": [ "lift-out" ] },
        { "id": "jb726e60", "type": "heading", "text": "2. We sketch", "fx": [ "rise", "lift-out" ] }
      ]
    }
  ]
}

Errors say where to look next:

There is no element "zzzzzzzz" on this page. get-document with format=outline lists the ids.
There is no effect "spin-wildly". The catalog (part=effects) lists them.

That is what lets an agent correct itself in one step instead of guessing.

Honest annotations

Each ability says whether it is read-only, destructive or idempotent: get-catalog is read-only, remove-element and save-document are destructive, create-page only adds. Clients can use that to decide what to ask the user about. When we recorded our film, Claude Code was set to build without asking, but to ask before publishing, removing anything or replacing a page.

MCP: the adapter’s server, and one of our own

The abilities are public, so with the WordPress MCP Adapter active (0.7 in our tests) they can be reached through the adapter’s default server and its discovery and execute tools. We wanted each ability to show up as a tool of its own, with its own description, so Midground also registers a server on mcp_adapter_init: over HTTP at /wp-json/midground/mcp, or locally with wp mcp-adapter serve --server=midground --user=<login>. The agent always acts as that WordPress user.

What we worked around

  • Older WordPress. The Abilities API came in WordPress 6.9, and Midground still supports 6.6, so everything sits behind function checks, and the category is registered on its own hook before the abilities.
  • A server made from ten arguments in order. create_server() takes the id, namespace, route, name, description, version, transports, error handler, observability handler and tools as positional arguments. We check that the method and the transport class exist, and write a clear line to the log when WP_DEBUG is on and the server is not made – a changed signature would otherwise fail silently.
  • Publishing is not yes or no. A permission callback answers true or false, but WordPress has a third answer for publishing: save it for review. So the publish right is checked when the ability runs, not in the permission callback: saving with status: publish becomes pending, and the publish ability explains that the page can be saved for review instead.
  • Loose output schemas, for now. Our answers have a known shape, but we declare them as open objects. Describing the nested outline in JSON Schema well enough to help a client is still on our list.
  • A switch. Some sites want no agents near their pages: add_filter( 'midground/abilities', '__return_false' ) removes the abilities and the server.

How fast it is, and how we test it

A test talks MCP over STDIO to the adapter’s server on a development site, the way an agent does: it reads the catalog, makes a product page from a 3D section and a pinned scene, changes the heading, adds motion, is told what was wrong with a bad effect, publishes – and checks that the page is live. A subscriber’s session is refused. The whole session takes about two seconds.

With a real agent it is slower and more interesting. In our recording, Claude Code went from one sentence – “Make a product page for our lamp Myr with a pinned scene in three steps and the 3D model, as a draft.” – to a finished draft in 1 min 9 s, without asking anything. We looked at the preview, added an icon in the editor and published at 1:46. The 52-second film shows the real time.

Not the first, and that is fine

Several builders added MCP this year – Elementor, Bricks and Beaver Builder among them. If you are making your own plugin agent-ready, what we would pass on is in the sections above: one ability per step, permissions that look at the thing being changed, the same rules as your own interface, and answers that say what to do next.

How to connect an agent is in the user guide, and there is a ready agent skill for Claude Code, Cursor and Codex. The agent tools are part of Midground Pro; the builder itself is free, and you can try the editor in your browser without signing up.