ACF MCP: read schemas, write field values, edit field groups

Before the ACF MCP connection writes anything

The ACF module ships in GoBuildWP Pro and loads only when Advanced Custom Fields 6.5.0 or newer is active. Nothing in it is mirrored into GoBuildWP Free, so a Free-only site sees none of the acf- abilities in its tool list. Start the first session with acf-check-setup: it tells the agent whether the site runs ACF or ACF Pro, which version, and how many ACF-managed post types, taxonomies and options pages already exist. That one answer decides what the rest of the session may attempt, because a payload containing a repeater, flexible content, gallery or clone field is refused with invalid_payload when ACF Pro is not the active edition.

Then decide where schema changes belong. If the theme ships an acf-json folder that lives in version control, a field group edited on production rewrites a JSON file the repository does not know about, and the next deploy can put the old definition back. On those sites, run acf-create-fieldgroup and acf-edit-fieldgroup on staging, commit the JSON ACF writes there, and keep production work to value reads and writes. The create ability reports whether ACF synced the group to local JSON, which is the quickest way to learn which kind of site you are on.

• Read Only profile: setup check, every list and get ability, and acf-read-values. Enough for an audit.
• Production Safe (the default): adds value writes and definition edits; the destructive ones still ask for confirmation.
• Use a dedicated WordPress identity with manage_options, or a super admin on multisite, for the ACF connection. An ordinary editor role is insufficient; narrow the credential scope and enabled abilities to the work agreed.

Raw values, formatted values and the empty-field trap

acf-read-values formats by default, so an image field comes back as an array of sizes and a post object field as the expanded post. That is right for describing content and wrong for copying it: when an agent reads one post to write another, it should read with format_values set to false and send back the stored form, which for relational and media fields is usually an ID.

The second trap is ACF's default value. get_field returns a field's default for a post that has never been saved with it, so a brand-new post can look fully populated. When the task is finding gaps, such as products missing a spec sheet or team members without a job title, read with only_with_values: true and treat anything absent as genuinely empty. That pairing is the basis of most clean-up jobs on ACF sites.

Jobs ACF site owners hand to an agent

Most requests are about values on content that already exists, with a field group change now and then. These are the shapes that fit the abilities as built:

• Fill a missing field across a post type: read with only_with_values to list the gaps, then fields-bulk-update-values with provider acf and dry_run true, review current and planned values, and confirm. Each post gets its own undo entry.
• Copy a field group to another site: acf-get-fieldgroup-schema on the source returns the export shape with keys, and acf-create-fieldgroup on the target accepts it unchanged. Keeping the keys means content imported later still lines up; the create refuses if that key already exists there.
• Move company details into an options page: acf-create-options-page, then write the phone number and address with target type options and the page's post_id, not its menu slug.
• Retire a post type: list its posts first and decide what happens to them, because acf-delete-post-type with force leaves them in the database under a type nothing registers.

Prompts that map cleanly onto ACF

Name the field group and the target object, and say whether existing rows must survive. 'Add a Download URL field after Spec Sheet in the Product Details group, keep every existing field and key' gives the agent what acf-edit-fieldgroup needs: the full fields array with one addition. 'Clear the testimonials' is the kind of request to rephrase, since on a repeater it becomes a replace write that removes every row; ask for the rows to be listed first and say which to keep.

After any group edit, open one affected post in the editor and one front-end template that prints the field. The ability confirms what ACF stored; only the template shows whether the theme reads it the way you expect.