An AI agent that builds pages in WordPress needs to know which blocks your site has and what each one accepts. Agent Abilities for MCP 1.10.0 gives it three tools for that: aafm/list-block-types lists the registered block types, aafm/get-block-type reads one block’s attributes, supports, styles and, for an Advanced Custom Fields (ACF) block, its field names, and aafm/replace-block swaps a single block without resending the page. All three are off until you enable them.
How does an AI agent learn which blocks my WordPress site has?
It calls aafm/list-block-types, which lists every block type registered on the site: core, theme and plugin blocks, ACF blocks included. Then it calls aafm/get-block-type with one name, such as core/group, to read that block’s attributes, supports and styles. For an ACF block it also gets the field names and an example payload.
Takeaways:
- The block tools came out of a test build of seven pages through MCP on a classic theme with ACF Pro blocks, running plugin 1.9.0.
- Agents can now list block types, read one block type (ACF fields and an example included) and replace one block by its position, without resending the page.
- Plain text in block attributes, such as an
&, is stored as written for users who may post unfiltered HTML. Style and script elements are removed with their contents. - Writes now warn about an unregistered block, an unknown ACF field, invalid attribute JSON and a block gap WordPress ignores. The warnings never refuse a write.
- There is still no dry run, and the plugin cannot replay the block editor’s own validity check.
What the test build found
On 30 October a test build put seven pages together through MCP. The site used a classic theme with ACF Pro blocks, and the plugin was at 1.9.0. The report listed ten gaps and 26 findings, and we checked each one against the code before deciding anything.
Several were real, some were WordPress core or theme behaviour, and a few were deliberate. These are the ones that shaped 1.10.0.
| What the build hit | What we found | What 1.10.0 does |
|---|---|---|
| The agent could not see which blocks existed, or what fields an ACF block takes | True. No ability read the block registry, and the ACF data shape was documented nowhere | Two new read abilities, with the field names and an example for ACF blocks |
An & in an ACF field came back as &, and &t=10 in an embed URL changed too |
True and reproduced. Every agent write of page content went through wp_kses_post(), which entity-encodes attribute text |
Plain attribute text is stored as written for users who may post unfiltered HTML |
CSS text from a <style> element stayed in the page |
True and reproduced | Style and script elements are removed with their contents, with a warning |
| Block attribute JSON with a trailing comma lost its attributes with no message | True. The block lost its attributes and content_warnings was empty |
An invalid_block_attributes warning |
A blockGap of clamp() or calc() did nothing |
WordPress core drops it when it renders | A block_gap_dropped warning, and the description now says what works |
| Changing one block meant resending the whole page | True. aafm/replace-in-post refuses structural changes on purpose |
A new aafm/replace-block |
New drafts reported a date of 0000-00-00 |
True | New drafts report real GMT dates |
Finding the blocks
aafm/list-block-types takes an optional namespace, an optional search that matches a name or a title, and paging. For each block type it returns the name, title, category, description, its allowed parents, whether it is an ACF block and whether it renders on the server. It is not the same as aafm/list-blocks, which lists saved reusable blocks, and 1.10.0 rewords that description so an agent does not mix them up.
| Ability | Lists | Class |
|---|---|---|
aafm/list-block-types |
Block types registered on the site | Read |
aafm/list-blocks |
Saved reusable blocks (synced patterns) | Read |
Both reads need the edit-posts capability. The two block-type reads appear with the other block tools on the Abilities tab.
Reading one block
aafm/get-block-type takes a block name and returns what an agent needs to write it correctly. That is the attributes, the supports, the style variations, the parent and context rules, and whether it renders on the server.
This matters because of where WordPress keeps block data. Per the block attributes reference, attributes without a source are saved in the block comment delimiter, so a wrong attribute name is data stored in a comment, and nothing visibly breaks. Block supports tell the agent which style properties a block can carry, such as spacing.blockGap, which the reference says turns on the spacing control for blocks that also use layout.
One limit to know: the colour palette and theme settings still come from aafm/get-global-styles, which needs the edit-theme-options capability. A connection running as an Editor, or on the Content editor preset, does not reach it.
ACF blocks and their fields
ACF attaches fields to a block with a location rule, as in “Block is equal to Testimonial”, according to the ACF Blocks documentation. aafm/get-block-type finds the field groups with such a rule for the block you ask about, and returns each field’s name, type, choices and sub-fields.
It also returns an example block comment. ACF block attributes are name, data and mode, and the keys inside data are field names. Here is the shape for a hypothetical block called acf/hero with a text field named headline:
<!-- wp:acf/hero {"name":"acf/hero","data":{"headline":"Open late on Fridays"},"mode":"preview"} /-->Image fields take attachment IDs. Repeater rows use ACF’s flattened keys, such as items_0_title, and the plugin’s check for unknown keys understands them.
Replacing one block
aafm/replace-block takes a post ID, a path and the new block markup. It can also take expect_block, a block name such as core/group, and it refuses the write if the block at that path is a different one.
The path is a list of positions: the index among the top-level blocks, then among that block’s inner blocks. Only real blocks count.
WordPress’s parse_blocks() returns top-level non-block content as a block with no name, and those pieces, such as the blank lines between blocks, are skipped. So [2, 0] is the first block inside the third top-level block. The tool’s description tells the agent to read the post with content_format set to raw to count them.
| Ability | Changes | Use it when |
|---|---|---|
aafm/replace-in-post |
Text inside a post, literal find and replace | A wording fix, with no change to structure |
aafm/replace-block |
One whole block, by position | One section needs rebuilding |
aafm/update-post |
The whole page | A new page or a full rewrite |
The plugin leaves every other block’s parsed attributes and HTML unchanged. The tool refuses when the new markup is not exactly one block, when the post’s existing markup does not survive being re-serialized (for example a block with invalid attribute JSON), and when a foreign page builder owns the post. It confirms the write the way aafm/replace-in-post does. While change history is on, the Changes tab can revert the change if the post has not been edited since. WordPress revisions alone leave no earlier copy of a post’s first edit.
Two honest limits. It reads the page, swaps the block and saves, so a save by someone else in between can be overwritten, and we accepted that. For a user who cannot post unfiltered HTML, WordPress may sanitize the whole page on save, as it does in that user’s own editor.
Warnings instead of silent drops
Writes that return content_warnings now flag five more things. They are informational and never refuse a write, strict mode included, so a site on strict mode does not start refusing after the update.
| Code | What it means |
|---|---|
unregistered_block |
No block type of that name is registered, for example a block from a deactivated plugin |
unknown_acf_field |
An ACF block’s data holds a key that matches none of its fields |
invalid_block_attributes |
The block’s attribute JSON did not parse, so its attributes were lost |
block_gap_dropped |
A blockGap value WordPress skips when it renders the layout |
removed_element |
A style or script element was removed with its contents |
WordPress ignores a blockGap that contains (, \, &, =, } or /*, so clamp(), calc() and var() are dropped, while 24px or var:preset|spacing|40 work. The write description tells the agent so, along with the facts that viewport-based block visibility needs WordPress 7.0 or later, and that on 6.9 metadata.blockVisibility: false hides a block everywhere.
What this does not do
There is no dry run. The warnings arrive on every write, so a draft is the dry run, and PHP cannot replay the block editor’s JavaScript save check. A block can therefore still show as needing recovery in the editor even when no warning fired.
Page-builder pages stay protected: the tool refuses a post owned by Elementor, Divi, Beaver Builder, Avada, Visual Composer, Oxygen, Breakdance, Brizy, Bricks or WPBakery, the same way the page builder guard does for other writes. There is also no signed preview link for drafts, because that would be a new unauthenticated way to read them.
Since 1.12.0 (2026-11-15): Avada and WPBakery Page Builder pages now have their own editing tools, and Restore revision works on them; the other eight builders are still refused. The same release fixed Divi detection, which had looked for a meta key Divi never stores, so from 1.7.4 through 1.11.2 a write to a Divi page was not refused. See Page builders and the changelog.
Turning the tools on
The two reads are shown with the other block tools on the Abilities tab. aafm/replace-block is on the Content tab, next to Replace in post, and needs the same edit access to the post as aafm/update-post. The Read only access preset reaches the two reads, and the Content editor and Shop manager presets reach all three.
Agent Abilities for MCP is best for site owners who want an agent to build and edit block pages within limits they set: each tool is off until enabled, checked against the connected user’s capabilities, and recorded in the audit log.
ChatGPT keeps the tool list it saw when it connected, so after you switch abilities on or off, open Settings, then Integrations, then Plugins, pick the app and choose Refresh. OpenAI’s help center lists write tools for ChatGPT Business and Enterprise/Edu plans, while Pro connects with read and fetch tools only.
A copy-paste prompt for the first read is in the Prompt Library as find the block types you can use on this site, and the reference is in the block tools docs. For safe habits when an agent writes, read draft posts without touching anything live. The release itself is in what 1.10.0 adds, and the full catalog is on abilities.
Questions
Does it work on a classic theme? Yes, the test build ran on one. A classic theme without block-template support usually has no templates, so aafm/list-templates can return an empty list there.
Does it need ACF? No. The ACF fields appear only for ACF blocks. Core, theme and plugin blocks are listed and read without it.
Will it change blocks I did not name? No. The other blocks keep their parsed attributes and HTML.