ACF Setup Suite

Prerequisites

• Advanced Custom Fields installed and active (free is fine for the core field-group + field-level tools; three site-setup tools require ACF Pro — noted per tool)
• Royal MCP Pro installed and licensed (see Getting Started)
• MCP client connected to your site (Claude Desktop, ChatGPT connector, Cursor, or any MCP-compatible client)
• Your MCP-connecting WordPress user needs manage_options (site administrator) — ACF field groups + registered CPTs + registered blocks are site-wide configuration, not per-post edits

Tools that need ACF Pro when ACF Pro is missing return acf_pro_required. Tools that touch a field group by ID or slug refuse when the group can't be resolved and return field_group_not_found. Nothing is partially written on a resolution failure.

Capability model

Every ACF Setup Suite tool requires manage_options (site administrator). Field groups, field definitions, registered CPTs, and registered blocks are site-wide configuration — there's no per-object capability that scopes down further.

This is different from the per-post edit-capability model most Royal MCP Pro write tools use (Elementor, Divi, WooCommerce). ACF Setup Suite is a site-configuration surface, not a content surface. If your MCP-connecting user is an administrator this is transparent.

Shared safety layer

Every ACF Setup Suite write tool runs through the same safety layer used across Royal MCP Pro's write surface, with a couple of ACF-specific patterns:

• Cap checks. Every tool requires manage_options at minimum. Fails-first with insufficient_caps if the caller doesn't have it — no partial writes.
• Group + field resolution. Tools that reference a field group by ID or slug (or a field by key or name) resolve against ACF's own registry first and refuse with a clear field_group_not_found / field_not_found if the target doesn't exist. No silent creation.
• Idempotency on JSON import. acf_import_field_group_json refuses to overwrite an existing group with the same key unless you pass overwrite: true explicitly. Default is create-if-new, refuse-if-exists.
• 72-hour undo tokens on destructive tools. acf_delete_field_group, acf_delete_field, and acf_update_field_group return an undo token that restores the exact prior definition. acf_register_post_type, acf_create_options_page, and acf_register_block also return undo tokens that reverse the registration.
• ACF Pro gate on Pro-only tools. acf_create_options_page, acf_register_post_type, and acf_register_block return acf_pro_required when only free ACF is active. No partial state is written.
• Audit Log row on every call. Success, error, and undone states all produce audit rows.

The 15 tools

Grouped by function. Field group CRUD and JSON bridge are the core surface. Field-level CRUD manages individual fields inside groups. Introspection tools are read-only. Site-setup primitives register options pages, custom post types, and ACF Blocks.

Field group CRUD (4)

Create, clone, update, and delete ACF field groups end-to-end from an MCP client. Every destructive write returns a 72-hour undo token.

Create an ACF field group titled "Product Details" that shows on the "product" post type. Include text fields for SKU and manufacturer, plus a number field for wholesale price.

Clone the "Product Details" field group as "Service Details" and target the "service" custom post type.

Change the "Product Details" field group location from post_type=product to post_type IN [product, variant].

Delete the "Product Details" field group entirely.

JSON bridge (2)

Import and export field groups as ACF-compatible JSON. Same JSON shape ACF's own Tools → Import / Export uses — portable across sites, agencies, and version control.

Import this ACF field group JSON from our staging site so the same field structure lands on production.

Export the "Product Details" and "Service Details" field groups as JSON so I can commit them to version control.

Field-level CRUD (4)

Add fields to an existing group, update their definition, reorder them, and delete individual fields without touching the parent group.

Add a required text field named "gtin" (label "GTIN / Barcode") to the "Product Details" field group, positioned after the SKU field.

Change the "gtin" field's label to "GTIN or UPC" and mark it optional (required=false).

Delete the "wholesale_price" field from the "Product Details" group.

In the "Product Details" group, reorder the fields to be: sku, gtin, manufacturer, wholesale_price.

Introspection (2)

Read-only tools that answer "what does this site actually have?" for a coding-adjacent agent that needs to know before writing.

Show me the full config of the "Product Details" field group so I can add a new conditional field.

List every ACF field type available on this site so I know what I can use in a new field group.

Site-setup primitives (3)

Register options pages, custom post types, and ACF Blocks. All three require ACF Pro because they wrap features that ship only in the paid ACF plugin. Every write returns a 72-hour undo token that reverses the registration.

Register an ACF options page titled "Site Settings" as a top-level admin menu with the dashicons-admin-generic icon.

Register a "product" custom post type with singular label "Product", plural "Products", the dashicons-cart icon, and support for title, editor, and thumbnail.

Register a block named "product-card" titled "Product Card", category "widgets", icon "cart", rendering through /theme/blocks/product-card.php.

Related reading

• Undo Tokens & Reversibility — how the 72-hour undo tokens returned by every destructive ACF tool work, when they expire, and how to consume them via royal_mcp_undo_last_operation.
• Universal Audit Log — every ACF tool call is captured, including field group + field-level writes and undo dispatch.
• ACF Local JSON — ACF's built-in mechanism for tracking field groups in version control. Complements acf_import_field_group_json / acf_export_field_group_json.
• Advanced Custom Fields Pro — the paid ACF plugin required for the three site-setup primitives (acf_create_options_page, acf_register_post_type, acf_register_block).

Still Stuck? Two-Step Support Path

If an ACF Setup Suite tool isn't behaving the way you expected, work through these two steps in order — most tool-level failures resolve at Step 1 because they're actually MCP-connection, host-layer, or ACF-Pro-availability issues, not ACF Setup Suite specific.

Step 1: Start with the Royal MCP Troubleshooting Guide

Royal MCP Troubleshooting — Start Here covers MCP-layer issues. If Claude can't reach your site at all, the tool call never fires — that guide is where to start.

For Pro-specific patterns:

• Undo token errors — expired, consumed, or handler missing
• Undo Tokens & Reversibility — how the 72h undo flow on destructive tools works
• Pro tool returned upgrade prompt with valid license

For ACF-specific patterns:

• acf_pro_required on the site-setup tools. acf_create_options_page, acf_register_post_type, and acf_register_block require ACF Pro. Free ACF is fine for every other tool on this page. Install ACF Pro (or ACF Pro 6.1+ for acf_register_post_type) to unlock the site-setup surface.
• field_group_not_found / field_not_found. The tool couldn't resolve the group or field by the key / slug / name you passed. Run acf_get_field_group_config first to confirm the target exists and the key is spelled correctly — especially useful right after an acf_import_field_group_json.
• field_group_exists on JSON import. acf_import_field_group_json refuses to silently overwrite by default. Pass overwrite: true if you want the existing group updated in place, or delete the existing group first and re-import.
• reorder_incomplete on acf_reorder_fields. The ordered_keys array must include every field currently in the group. Missing or extra keys are refused — run acf_get_field_group_config to grab the current field list, reorder it locally, and pass the full array back.

Step 2: Email priority support

If you've worked through Start Here and the relevant Pro-specific doc and the issue still isn't resolved, email priority support from your purchase email address at support@royalplugins.com. Priority email support is included with your license — typical response within 24 hours. Never include your license key in email; we look it up from your purchase address.