WordPress prerequisites

This page is the single source of truth for what has to be set up before any of the WordPress workflow pages will work. Skim it once, fix anything that’s missing, then move on to the workflow you care about.

1. The site itself

• WordPress 5.5+ (older versions have broken REST behaviour around Application Passwords).
• REST API reachable at https://<site>/wp-json/. Open the URL in a browser — if you get JSON, you’re good. If you get a 401/403/redirect loop, a security plugin or WAF is blocking REST and you need to allow the path before anything else works.

2. App Password

The worker authenticates against WordPress with HTTP Basic Auth using a WordPress Application Password (NOT your login password — that’s deprecated and often blocked by hosts).

1. wp-admin → Users → Your profile
2. Scroll to Application Passwords
3. Type a name like SEO Navigator MCP → click Add New Application Password
4. Copy the 24-character password (shown once)
5. In the worker admin at /admin/sites, click Set app pass on the site row and paste it. The worker stores it encrypted in D1.

The password belongs to a real WP user — that user needs edit_posts and edit_pages capability at minimum. For taxonomy creation, manage_categories helps. Use an account that is an Editor or Administrator role.

3. Site registered in /admin/sites

Required fields:

Field	Value
ID (slug)	Stable identifier used everywhere — viper-template, acme-blog, etc. Cannot be changed later.
Display name	Human-readable, free text
Platform	wordpress
Base URL	https://example.com — no trailing slash
WP username	The login of the user who issued the app password
Page builders	Tick Gutenberg, Elementor, or both (see below)
Default builder	The one Claude uses when not explicitly told which builder to pick
MCP backend	default (REST API) or wp-mcp-adapter (proxy) — see below

4. Page builders

If the site has only Gutenberg installed, tick Gutenberg as the default. That covers create_page_draft for the built-in editor + create_page_from_code for the vibe-code-in-chat flow.

If Elementor is also installed and you want to use the template-duplicate workflow:

• Tick Elementor in the available builders list
• Pick a default (the one Claude picks when no page_builder arg is sent)
• If you tick both Gutenberg and Elementor, Claude must pass page_builder=gutenberg or page_builder=elementor explicitly on create_page_draft, OR call list_builders_for_site first to discover which to use. Calls without a builder arg fail with E_BUILDER_REQUIRED.

5. Elementor-specific setup (only if you tick Elementor)

The Elementor template-duplicate workflow needs _elementor_data exposed via the REST API. Two ways:

A. default MCP backend — paste this into the active theme’s functions.php:

add_action('rest_api_init', function () {
    register_rest_field('page', 'meta', [
        'get_callback' => function ($obj) {
            return [
                '_elementor_data' => get_post_meta($obj['id'], '_elementor_data', true),
                '_elementor_edit_mode' => get_post_meta($obj['id'], '_elementor_edit_mode', true),
                '_elementor_template_type' => get_post_meta($obj['id'], '_elementor_template_type', true),
            ];
        },
        'schema' => null,
    ]);
});

B. wp-mcp-adapter MCP backend — install the wordpress/mcp-adapter plugin + msrbuilds/elementor-mcp plugin. The adapter exposes Elementor data + 74 widget-level tools through its own MCP endpoint, which the worker proxies. No snippet needed.

Run diagnose_site site_id="<wp-site-id>" to verify the snippet (or the adapter) is detected.

6. Code-first pages — optional WP plugin

The create_page_from_code / update_page_from_code tools need a tiny plugin installed on the WP site to emit the inline CSS/JS that the worker attaches to the page as meta.

1. Download from wp-plugins/seo-navigator-code-page in the worker repo
2. Upload as a zip in wp-admin → Plugins → Add New → Upload Plugin
3. Activate
4. Confirm with diagnose_site site_id="<wp-site-id>" — the code_page_plugin.installed flag must flip to true

Skip this step if you don’t use the vibe-code workflow.

7. Token scope

The MCP token presented in /mcp calls must have:

• The site in its allowed_sites (or * wildcard which expands to the user’s user_sites at create time)
• The tools in its allowed_tools — for the WordPress workflows you’ll typically want:
  • Posts: create_draft, update_draft, schedule_draft, unschedule, get_post, list_drafts, upload_media, list_taxonomies, create_taxonomy
  • Pages: create_page_draft, update_page_draft, schedule_page, list_page_templates, list_builders_for_site
  • Code-first: create_page_from_code, update_page_from_code
  • Diagnostic: diagnose_site, list_sites, get_site, ping_site

Quick-pick Select all in the token form covers everything safe. Quick-pick All except destructive excludes proxy delete-* / publish-* tools (those are filtered out of tools/list anyway, but the quick-pick is belt-and-braces).

delete_astro_route is super-admin only and won’t appear in regular-user token forms.

8. Verify with ping_site + diagnose_site

Once everything looks set, ask Claude:

Ping site viper-template and run diagnose.

Both should return ✅ across the board. If diagnose_site flags something red, fix it before running any other workflow tool. The error message tells you what’s missing.

Next

• Blog posts
• Pages (Gutenberg / Elementor)
• Elementor template duplicate
• Code-first pages
• Tags, categories & media