# ACF Setup Suite

> Reference for the 15 ACF Setup Suite tools in Royal MCP Pro: field group CRUD, JSON bridge, field-level CRUD, options pages, post types, and ACF Blocks.

- Canonical: <https://royalplugins.com/support/royal-mcp-pro/acf-setup-suite/>
- Last updated: 2026-09-20
- HTML version: <https://royalplugins.com/support/royal-mcp-pro/acf-setup-suite/>

---

Complete reference for the 15 ACF Setup Suite tools in Royal MCP Pro. End-to-end Advanced Custom Fields management from Claude Desktop, ChatGPT, Cursor, or any MCP client: create and manage field groups, add and update fields, import/export as JSON for cross-site portability, list every registered field type, and register options pages, custom post types, and ACF Blocks that render through your existing template files.

ACF Free vs ACF Pro plugin

The core field-group + field-level tools work with the free Advanced Custom Fields plugin (any recent version). Three tools require ACF Pro specifically because they wrap features that only ship in Pro:

- `acf_create_options_page` — ACF Pro is required for the Options Pages feature
- `acf_register_post_type` — requires ACF Pro 6.1 or later for the built-in CPT UI
- `acf_register_block` — requires ACF Pro for ACF Blocks support

Each of the three returns a clean `acf_pro_required` error envelope when called on a site running only free ACF — no partial state is written. Not to be confused with Royal MCP *Pro*, which is what gates every tool on this page.

## 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](https://royalplugins.com/support/royal-mcp-pro/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.

### acf\_create\_field\_group

Create a new ACF field group with title, key (auto-generated if omitted), and location rules. Field definitions can be included in the same call or added separately with `acf_add_field`.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `title` required | `string` | Display title for the field group. |
| `key` | `string` | ACF group key. Auto-generated (`group_<hash>`) if omitted. |
| `location` | `object[]` | ACF location rules. Standard ACF shape: array of arrays of `{param, operator, value}` objects. Example: `[[{"param":"post_type","operator":"==","value":"post"}]]`. |
| `fields` | `object[]` | Optional field definitions to include on create. Each field is an ACF field payload (`label`, `name`, `type`, `key`, plus type-specific keys). |
| `position` | `string` | One of `normal` (default) / `acf_after_title` / `side`. |
| `style` | `string` | One of `default` / `seamless`. |
| `active` | `boolean` | Whether the group is active on create. Default `true`. |

#### Example prompt

```
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.
```

Undo: 72h token — deletes the created field group and any fields registered inside it.

### acf\_clone\_field\_group

Duplicate an existing ACF field group with a new title and key. Every child field is cloned with a fresh key so the two groups don't collide in the ACF registry.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `source_key` required | `string` | Source field group key (typically `group_<hash>`). |
| `new_title` required | `string` | Title for the cloned group. |
| `new_key` | `string` | Key for the cloned group. Auto-generated if omitted. |
| `location` | `object[]` | Location rules for the clone. If omitted, the source's rules are copied. |

#### Example prompt

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

Undo: 72h token — deletes the cloned group and its child fields.

### acf\_update\_field\_group

Update a field group's metadata (title, location rules, position, style, active state). Does not modify child fields — use `acf_update_field_definition`, `acf_add_field`, or `acf_delete_field` for those.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `key` required | `string` | Field group key. |
| `title` | `string` | New display title. |
| `location` | `object[]` | New location rules. Replaces the existing rules entirely. |
| `position` | `string` | One of `normal` / `acf_after_title` / `side`. |
| `style` | `string` | One of `default` / `seamless`. |
| `active` | `boolean` | Set active / inactive without deleting. |

#### Example prompt

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

Undo: 72h token — restores every changed metadata field to its prior value.

### acf\_delete\_field\_group

Delete a field group and every field inside it. Returns an undo token that restores the exact prior definition including all child fields.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `key` required | `string` | Field group key. |

#### Example prompt

```
Delete the "Product Details" field group entirely.
```

Undo: 72h token — restores the field group and every child field with their original keys and definitions.

### 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.

### acf\_import\_field\_group\_json

Import a field group (or multiple field groups) from an ACF-compatible JSON payload. Refuses to overwrite existing groups with the same key unless `overwrite: true` is passed.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `json_payload` required | `string` | JSON string containing one or more ACF field group definitions. Same shape ACF exports. |
| `overwrite` | `boolean` | When `true`, existing groups with matching keys are updated in place. Default `false` (returns `field_group_exists` instead). |

#### Example prompt

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

Undo: 72h token — deletes every group that was created by this import (skips groups that already existed if overwrite was used).

### acf\_export\_field\_group\_json

Export one or more field groups as an ACF-compatible JSON payload. Includes every child field, location rule, and group setting.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `keys` | `string[]` | Array of field group keys to export. Omit to export every group on the site. |

#### Example prompt

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

Read-only.

### Field-level CRUD (4)

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

### acf\_add\_field

Add a new field to an existing field group. Position is appended to the end unless `after_key` or `after_name` is passed.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `group_key` required | `string` | Parent field group key. |
| `field` required | `object` | ACF field payload — `label`, `name`, `type`, `key` (auto-generated if omitted), plus type-specific keys (`choices` for select/radio, `min`/`max` for number, `toolbar` for wysiwyg, etc.). |
| `after_key` | `string` | Insert the new field immediately after this existing field key. |
| `after_name` | `string` | Insert immediately after this existing field name (alternative to after\_key). |

#### Example prompt

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

Undo: 72h token — deletes the added field.

### acf\_update\_field\_definition

Update a field's definition in place. Partial — only fields you pass are modified. The `type` can be changed but be careful: existing saved values may not deserialize correctly under the new type.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `field_key` required | `string` | The field's ACF key (typically `field_<hash>`). |
| `updates` required | `object` | Partial field payload — only the keys you want to change. Common: `label`, `instructions`, `required`, `choices`, `default_value`, `min`, `max`, `wrapper.width`. |

#### Example prompt

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

Undo: 72h token — restores every changed definition key to its prior value.

### acf\_delete\_field

Delete a single field from its group. The other fields in the group are untouched.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `field_key` required | `string` | The field's ACF key. |

#### Example prompt

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

Undo: 72h token — restores the field definition and its position within the group.

### acf\_reorder\_fields

Reorder fields inside a group by passing an ordered array of field keys. The array must contain every field currently in the group — partial reorderings are refused with `reorder_incomplete`.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `group_key` required | `string` | Parent field group key. |
| `ordered_keys` required | `string[]` | Ordered array of field keys. Must include every field in the group. |

#### Example prompt

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

Undo: 72h token — restores the previous field order.

### Introspection (2)

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

### acf\_get\_field\_group\_config

Fetch the complete configuration of a field group, including every child field and every child field's type-specific keys. Same shape you'd get from `acf_export_field_group_json` but returned as a structured object instead of a JSON string.

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `key` required | `string` | Field group key. |

#### Example prompt

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

Read-only.

### acf\_list\_supported\_field\_types

List every field type ACF supports on this install, including any type registered by add-on plugins (Flexible Content, Repeater, Gallery, extended types from Meta Box add-ons, etc.).

#### Cap

`manage_options`

#### Example prompt

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

Read-only.

### 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.

### acf\_create\_options\_page

Register a site-wide ACF Options Page. Wraps `acf_add_options_page()`. Common use: global site settings, header/footer content, logo, contact info — anywhere you need editable data that isn't attached to a specific post. **Requires ACF Pro.**

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `page_title` required | `string` | Display title for the options page. |
| `menu_title` | `string` | Admin sidebar label. Defaults to `page_title`. |
| `menu_slug` | `string` | URL slug. Auto-generated from `page_title` if omitted. |
| `capability` | `string` | WordPress capability required to view/edit. Default `edit_posts`. |
| `parent_slug` | `string` | Optional parent menu slug — nest as a sub-page under an existing admin menu. |
| `position` | `integer` | Menu position (only for top-level pages). |
| `icon_url` | `string` | Dashicon slug or URL for the admin menu icon. |

#### Example prompt

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

Undo: 72h token — unregisters the options page. Any values already saved to that page persist in the options table but aren't reachable from the admin UI until re-registered.

### acf\_register\_post\_type

Register a custom post type using ACF Pro's built-in CPT UI (introduced in ACF Pro 6.1). Persists to ACF Pro's CPT store, so the CPT survives after Royal MCP Pro is deactivated. **Requires ACF Pro.**

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `post_type` required | `string` | CPT slug (lowercase, no spaces). |
| `label_singular` required | `string` | Singular label for the admin UI (e.g. "Product"). |
| `label_plural` required | `string` | Plural label (e.g. "Products"). |
| `public` | `boolean` | Whether the CPT is publicly viewable on the front end. Default `true`. |
| `has_archive` | `boolean` | Whether to serve an archive page. Default `true`. |
| `menu_icon` | `string` | Dashicon slug or URL for the admin menu. |
| `supports` | `string[]` | Array of supports flags: `title`, `editor`, `thumbnail`, `excerpt`, `author`, `revisions`, `custom-fields`. Default `[title, editor, thumbnail]`. |
| `taxonomies` | `string[]` | Array of taxonomy slugs to attach. |
| `rest_base` | `string` | REST API base slug. Defaults to `post_type`. |

#### Example prompt

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

Undo: 72h token — unregisters the CPT via ACF Pro's CPT UI. Existing posts of that type persist in the database but stop appearing in the admin until re-registered.

### acf\_register\_block

Register an ACF Block that renders through an existing template file. Requires ACF Pro for the ACF Blocks feature. Uses `acf_register_block_type()` so the block is persistent across page loads without needing block.json. **Requires ACF Pro.**

#### Cap

`manage_options`

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `name` required | `string` | Block name (lowercase, no spaces). Prefixed with `acf/` automatically. |
| `title` required | `string` | Display title in the block inserter. |
| `description` | `string` | Description shown in the block inserter. |
| `category` | `string` | Block inserter category. One of `text`, `media`, `design`, `widgets`, `theme`, `embed`, or a custom category slug. Default `widgets`. |
| `icon` | `string` | Dashicon slug or inline SVG for the block inserter. |
| `render_template` required | `string` | Relative path to the block's template file (from the theme root). |
| `keywords` | `string[]` | Search keywords for the block inserter. |
| `supports` | `object` | Standard block supports object — `{align: true, mode: false, anchor: true, ...}`. |

#### Example prompt

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

Undo: 72h token — unregisters the block. Existing posts using the block continue to render at the front end (block.json isn't rewritten) but the block disappears from the inserter.

## Related reading

- [Undo Tokens & Reversibility](https://royalplugins.com/support/royal-mcp-pro/undo-tokens-and-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](https://royalplugins.com/support/royal-mcp-pro/understanding-the-audit-log/) — every ACF tool call is captured, including field group + field-level writes and undo dispatch.
- [ACF Local JSON](https://www.advancedcustomfields.com/resources/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](https://www.advancedcustomfields.com/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**](https://royalplugins.com/support/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](https://royalplugins.com/support/royal-mcp-pro/undo-token-errors/) — expired, consumed, or handler missing
- [Undo Tokens & Reversibility](https://royalplugins.com/support/royal-mcp-pro/undo-tokens-and-reversibility/) — how the 72h undo flow on destructive tools works
- [Pro tool returned upgrade prompt with valid license](https://royalplugins.com/support/royal-mcp-pro/pro-tool-returned-upgrade-prompt/)

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](mailto: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.

What to include in your email

- **Your hosting provider** (SiteGround, Cloudways, Hostinger, Kinsta, WP Engine, Liquid Web, self-hosted VPS, etc.)
- **Royal MCP Pro version** from WP Admin → Plugins
- **ACF version** from WP Admin → Plugins — note explicitly whether it's free ACF or ACF Pro, and the exact version number (the Pro-only tools require ACF Pro 6.1+ specifically for `acf_register_post_type`)
- **Active caching plugins** (LiteSpeed Cache, WP Rocket, W3 Total Cache, SpeedyCache, Hummingbird, none)
- **Active security plugins** (Wordfence, Defender Pro, Solid Security, NinjaFirewall, none)
- **Cloudflare or CDN** in front of the site? If yes, is “Manage AI Bots” or “Bot Fight Mode” on?
- **Which MCP client** — claude.ai web custom connector, Claude Desktop with `mcp-remote`, ChatGPT MCP, Cursor, or another MCP-compatible client
- **The exact ACF tool name and args** you called (e.g. `acf_add_field` with `group_key: "group_abc123"`, `field: {label: "GTIN", name: "gtin", type: "text"}`)
- **The exact error message returned** (from the MCP client's chat surface), plus any `ofid_xxxxx` reference code if claude.ai shows one
- **Screenshot of the most recent Pro tool row in Audit Log** with View Details expanded — or confirmation that the log is empty after a reproduced failure
- **Screenshot of the target field group in ACF admin** (WP Admin → ACF → Field Groups → edit the target) — so we can visually confirm the state we're operating against

[← Royal Affiliate Pro Tools](https://royalplugins.com/support/royal-mcp-pro/royal-affiliate-pro-tools/)
[Universal Audit Log →](https://royalplugins.com/support/royal-mcp-pro/understanding-the-audit-log/)