IATO MCP Plugin Documentation

Overview

IATO MCP turns any self-hosted WordPress site into an MCP server. The plugin runs entirely inside WordPress as a REST API endpoint — no external server or infrastructure required. AI clients like Claude Desktop, Gemini, and ChatGPT connect directly to your site via the Model Context Protocol.

AI Client (Claude Desktop / Gemini / ChatGPT)
    |
    |  MCP JSON-RPC over HTTP (one POST per call)
    |
WordPress Plugin  (iato-mcp)
  POST /wp-json/iato-mcp/v1/message    ← all MCP tool calls
  POST /wp-json/iato-mcp/v1/rollback   ← rollback a change by receipt ID
  GET  /wp-json/iato-mcp/v1/oauth/*    ← Claude Desktop auth flow
    |
    |  With IATO API key configured, bridge tools call:
    |
IATO Platform  (iato.ai/api/v1)
  Auth: Authorization: Bearer {iato_api_key}
  Read-only: sitemap, SEO fixes, orphans, broken links, suggestions

Requirements

The plugin works on any self-hosted WordPress installation. No special server configuration needed.

Quickstart

One screen, five steps, under five minutes. The 40 WordPress tools work immediately. The 12 bridge tools require an IATO API key.

1. Install the plugin from the WordPress.org plugin directory (search "IATO MCP" in WP Admin → Plugins → Add New), then activate.
2. Open the Setup Wizard at Settings → IATO MCP. The wizard is a single screen — no multi-step flow.
3. Generate an Application Password for your WordPress user (Users → Profile → Application Passwords). The wizard shows you exactly where to click.
4. Paste the JSON snippet shown in the wizard into your MCP client's configuration (Claude Desktop → Settings → Developer, or equivalent). The snippet includes the endpoint URL and the Bearer token the wizard just generated.
5. (Optional) Paste your IATO API key into the wizard field to enable the 12 bridge tools. Validate explicitly via the Test connection button — saving is fast and local. Skip this step if you only need the WordPress tools.

Restart your MCP client. The 40 WordPress tools (52 with an IATO key) will appear in the client's tool list.

Configuration

All settings are managed in WP Admin under Settings → IATO MCP.

Connecting AI Clients

Any AI client that supports the Model Context Protocol can connect to your WordPress site.

Claude Desktop (OAuth)

Go to Claude Desktop → Settings → Connectors → Add. Enter your site's MCP endpoint URL (shown in Settings → IATO MCP). Click Authorize — the OAuth flow completes automatically.

Manual Configuration

For other MCP clients, add this to your client's configuration file:

{
  "mcpServers": {
    "wordpress": {
      "url": "https://yoursite.com/wp-json/iato-mcp/v1/message",
      "headers": {
        "Authorization": "Bearer IATO-XXXXXXXX"
      }
    }
  }
}

Replace the URL and API key with the values from Settings → IATO MCP.

Tool Reference

The plugin exposes 40 WordPress tools plus 12 IATO bridge tools (the bridge tools require an IATO API key). Grouped by category. Frozen as of plugin v1.4.0.

Content 5 tools

Site 3 tools

SEO 4 tools

Media 2 tools

Navigation 6 tools

Taxonomy 6 tools

Redirects 1 tool

Comments 1 tool

Rollback 1 tool

Elementor — Document level 3 tools

Elementor — Widget v2 8 tools

Widget-grained editing — patch a single widget without re-uploading the whole document. All writes accept if_revision for optimistic concurrency and idempotency_key for safe retries (60-second replay window).

IATO Bridge Tools 12 tools — requires IATO API key

Tools that call the IATO API. The read tools resolve IATO node/page IDs to WordPress post IDs and slugs so your AI client can chain directly into the WP native tools. The crawl management tools let Claude trigger and monitor crawls without leaving the conversation.

Read 9 tools

Crawl Management 3 tools

Widget-Grained Editing

Plugin v1.3.0 introduced 8 widget-level Elementor tools that patch a single widget without re-uploading the whole document. A 4-page heading-level flip dropped from ~100 KB / 16 requests on v1.2 to ~2.2 KB / 1 request on v1.3 — ~60× wire reduction.

Picking the right tool

Optimistic concurrency — the if_revision flow

Every get_elementor_data and widget-level read returns a canonical revision hash. Pass it as if_revision on a write to fail fast if the document changed since you read it:

// 1. read
const { revision, widgets } = await get_elementor_widget({ post_id: 42, widget_id: "abc123" });

// 2. write with the revision you read
await update_elementor_widget({
  post_id: 42,
  widget_id: "abc123",
  settings_patch: { title: "New title" },
  if_revision: revision,
  idempotency_key: "set-hero-title-2026-04-28"
});

If the revision doesn't match the current document state, the write is rejected with a conflict error so your client can re-read and decide. Without if_revision, last-write-wins.

Idempotency — the idempotency_key flow

Pass idempotency_key on any widget write to make retries safe. The plugin caches the response for 60 seconds, scoped per (user, tool) pair. A retry within that window with the same key returns the cached result without re-applying the write.

Use any string — UUID, slugified intent, request id from your client. The plugin only checks for collisions; it doesn't interpret the value.

Replace-only array semantics

settings_patch on update_elementor_widget and update_elementor_widgets_bulk uses replace-only semantics for arrays — if you patch an array setting, you replace the entire array. There is no merge for nested array elements.

To insert, remove, or reorder items inside an array without rewriting the whole array, use update_elementor_patch with RFC 6902 JSON Patch operations (add, remove, replace, move, copy, test).

Theme Builder shadowing

Elementor's Theme Builder can override the default WordPress render of a slug with a template. A request to /about/ may render the singular page template, an Elementor Theme Builder singular template, or a more specific page-about template — depending on the rewrite cascade.

Two ways to detect this:

• resolve_url walks the rewrite cascade for any URL and reports the resolved post + any shadowing template overriding it.
• get_post accepts include_shadowing: true for the same detection inline on a known post.

Full detection requires Elementor 3.20+. On older versions, the resolver returns limited_resolution: true and falls back to the WordPress-only cascade.

Capability discovery

The MCP initialize handshake advertises plugin capabilities so clients can feature-detect without a tools/list round-trip. When Elementor is active, the response includes:

{
  "capabilities": {
    "elementor": { "v2": true }
  }
}

Absent or false means the v2 widget tools won't be registered — either Elementor isn't installed, or the plugin is on an older version. Clients should gate widget-level prompts on this flag.

Example prompts

Two prompts that exercise the v2 capability end-to-end:

• “Set every H2 heading to H1 across these 4 Elementor pages” — uses find_elementor_widgets to locate all heading widgets, then update_elementor_widgets_bulk with set_heading_level semantics in a single HTTP call.
• “Change the button color on all CTA widgets to #ff0000 across the site” — uses find_elementor_widgets with type and setting filters, then update_elementor_widgets_bulk with settings_patch on each match.

SEO Plugin Adapter

The plugin auto-detects which SEO plugin is active and reads/writes the correct post meta keys. Detection priority: Yoast → RankMath → SEOPress → Fallback. No configuration needed.

Redirect Plugin Detection

The update_redirect tool auto-detects which redirect plugin is active and uses its API. If no plugin is found, a built-in option-based fallback handles redirects.

Change Receipts

Every write tool returns a change_receipt object in its response, providing a full audit trail for AI-made changes.

Receipt Format

{
  "change_id": "wr_a1b2c3d4e5f67890",
  "post_id": 42,
  "target_type": "page",
  "field": "meta_description",
  "before_value": "Old description",
  "after_value": "New SEO-optimized description",
  "applied_at": "2026-03-26T14:30:00Z"
}

Target Types

Receipts are stored in the {prefix}iato_change_receipts database table, created automatically on plugin activation.

Rollback Endpoint

Restore any AI-made change using its change receipt ID.

Endpoint

POST /wp-json/iato-mcp/v1/rollback

Authentication

Same as MCP endpoint: Bearer token (Authorization: Bearer IATO-XXXXXXXX).

Request Body

{
  "change_id": "wr_a1b2c3d4e5f67890",
  "post_id": 42,
  "target_type": "page",
  "field": "meta_description",
  "before_value": "New SEO-optimized description"
}

Validation

Response

{
  "success": true,
  "rolled_back_at": "2026-03-26T15:00:00Z",
  "change_id": "wr_a1b2c3d4e5f67890"
}

Supported rollbacks: all write tool changes including SEO meta, alt text, menu items, taxonomy, canonical URLs, structured data, and redirects.

Setup Wizard

Accessible at wp-admin/admin.php?page=iato-mcp-setup. Requires manage_options capability. One screen — no multi-step flow.

Authentication

The plugin uses a plugin-generated API key stored in wp_options, plus support for WordPress-native Application Passwords. Four authentication methods are supported.

Key generation: on plugin activation, wp_generate_password(32, false) creates the key. Users can regenerate via Settings → IATO MCP → Regenerate Key.

Data Flows

Two example workflows showing how the plugin bridges AI clients, WordPress, and IATO.

1. AI calls get_iato_seo_fixes(crawl_id)
   → Plugin calls IATO: run_seo_audit + get_seo_issues
   → Returns: [{url, issue_type, current, suggested, wp_post_id, wp_slug}]

2. AI calls update_seo_data(id: wp_post_id, description: suggested)
   → Plugin writes to Yoast/RankMath/SEOPress meta on each post

1. AI calls get_iato_nav_audit(sitemap_id)
   → Plugin calls IATO: get_menus + get_menu_items + find_orphan_pages
   → Returns: {menus: [...], orphans: [{url, wp_post_id, wp_slug}]}

2. AI calls update_menu_item(menu_id, post_id: wp_post_id, dry_run: true)
   → Preview what would be added

3. AI calls update_menu_item(menu_id, post_id: wp_post_id)
   → wp_update_nav_menu_item() adds page to menu

Troubleshooting

Changelog

v1.3.5 — Docs accuracy pass

• FAQ entry corrected: "30 built-in tools" → "39 WordPress native + 12 IATO bridge = 51 total"
• Added two example prompts demonstrating widget-grained edits ("Set every H2 heading in these Elementor posts to H1", "Find all button widgets on the site and change their color to #ff0000")
• No code changes

v1.3.4 — Bulk receipt optimization

• update_elementor_widgets_bulk no longer echoes change_receipt on per-result rows. Receipts still persist to the iato_change_receipts audit table; bulk callers can query by post_id + applied_at. Saves ~120 bytes per result.
• 4-page H1-flip benchmark response now under the v2 spec's <2 KB hard target.
• Singleton update_elementor_widget and update_elementor_patch responses keep the slim receipt for backward compatibility and convenience.

v1.3.3 — Revision payload optimization

• v2 write tools (update_elementor_widget, update_elementor_patch, update_elementor_widgets_bulk) elide previous_revision from per-result responses unless the caller passed if_revision.
• Rationale: a client that passed if_revision already knows the prior hash; a client that didn't pass it gets current_revision to chain the next write. Saves ~93 bytes per result on the op: replace path.

v1.3.2 — Receipt schema fix

• Fix: v2 write tools were echoing a verbose change_receipt with the entire applied_patch JSON-stringified into before_value. That duplicated the top-level applied_patch field and pushed bulk-update payloads over the spec's <2 KB target on a 4-page sweep. The before_value was also semantically wrong (should be the value being replaced, not the patch).
• Storage rows now record the canonical previous_revision → current_revision pair; API response carries only the receipt id + metadata ({change_id, target_type, field, applied_at}). Full audit data still queryable from the iato_change_receipts table for rollback.
• Per-update savings ~0.6–0.8 KB; 4-page bulk sweep saves ~3 KB on the wire.

v1.3.1 — v2 capability fixes

• Fix: update_elementor_widgets_bulk and find_elementor_widgets no longer reject every request with auth_denied. The handlers were calling current_user_can('edit_post', $post_id) per-target, but bearer-authenticated MCP requests don't establish a logged-in WP user — wp_get_current_user() returns 0 and meta-cap checks against post objects always fail. v2 handlers now match v1's IATO_MCP_Auth::require_cap() flag-check semantics.
• Fix: idempotent one-shot migration on plugin update. Existing installs upgrading from 1.2.x previously saw the 9 new Elementor v2 tools auto-disabled because saved iato_mcp_tools toggle arrays didn't include the new names. The migration appends new tool names on first request after upgrade. New installs unaffected.

v1.3.0 — Widget-grained Elementor editing

• 8 new widget-level Elementor tools: list_elementor_widgets, get_elementor_widget, find_elementor_widgets, set_heading_level, set_widget_setting, update_elementor_widget, update_elementor_widgets_bulk, update_elementor_patch
• New resolve_url tool walks the WordPress rewrite cascade and detects Elementor Theme Builder template shadowing
• 30 → 39 WordPress tools, 42 → 51 total
• Optimistic concurrency via if_revision (canonical revision hash returned by reads); idempotency via idempotency_key (60-second replay window, scoped per (user, tool))
• update_elementor_patch applies RFC 6902 JSON Patch operations as a surgical escape hatch for the replace-only array semantics on the higher-level write tools
• get_elementor_data accepts format: raw | compact | summary for flexible introspection
• initialize handshake advertises capabilities.elementor.v2: true so clients can feature-detect without a tools/list round-trip
• Performance: a 4-page heading-level flip dropped from ~100 KB / 16 requests on v1.2 to ~2.2 KB / 1 request on v1.3 — ~60× wire reduction
• Theme Builder shadowing detection requires Elementor 3.20+; older versions return limited_resolution: true and fall back to the WordPress-only cascade

v1.2.0 — Crawl management

• New start_iato_crawl, get_iato_crawl_status, list_iato_crawls MCP tools
• 9 → 12 bridge tools, 39 → 42 total
• New FAQ entry on the dual auth methods (Application Password vs. Bearer token)

v1.1.12 — Marketing-page parity

• Plugin URI added to plugin header
• Contextual links to iato.ai across description / install / FAQ
• Documentation page link in install instructions

v1.1.11 — Readme accuracy pass

• Tool count corrected (17 → 30) in the readme description and FAQ
• Min WordPress version bumped to 6.2 in plugin header (and in FAQ)
• Feature list expanded with Elementor / canonical / structured data / redirects / excerpt support

v1.1.10 — Initial WP.org submission

• Pure MCP server scope: 30 WordPress tools + 9 IATO bridge tools (since superseded by 1.2.0's 12)
• AJAX Save Settings to sidestep host-level options.php timeouts
• Test connection button replaced inline validation
• Tab-based Settings UI (General + Diagnostics)
• Plugin Check clean (0 errors / 0 warnings)

v1.0.0 — WordPress.org submission

Initial public release. Pure MCP server for self-hosted WordPress: 30 WordPress tools plus 9 IATO bridge tools.

Deliberate scope changes from pre-release builds:

• Autopilot with governance — removed from v1.0.0, returning in a future release. The Review Queue, approve/reject flow, and auto-apply engine are deferred so they can be rebuilt properly: async sync, correct approve→apply→receipt wiring, and resilience when the platform is slow. See the Roadmap.
• wp-admin Dashboard Widget — removed, returning with Autopilot. The SEO health widget depends on Autopilot data, so it ships when Autopilot does.
• Four aggregator MCP tools that bundled WP→IATO sync calls into single high-level operations — sync_wp_pages_to_iato, sync_wp_taxonomy_to_iato, sync_wp_meta_to_iato, sync_wp_menus_to_iato — were removed in v1.0.0. The user-facing WordPress Sync feature on the IATO dashboard is unaffected because it composes the existing read tools (get_posts, get_terms, get_menus, get_menu_items) directly. The aggregator tools will return in a future release alongside Autopilot once the async-sync redesign is complete.

What's in v1.0.0:

• 39 MCP tools (30 WordPress + 9 IATO bridge), all synchronous
• Application Password + Bearer token authentication (plus OAuth for Claude Desktop)
• Change receipts on every write tool, with a POST /wp-json/iato-mcp/v1/rollback endpoint
• SEO plugin adapter (Yoast / RankMath / SEOPress) with fallback
• Redirect plugin detection (Redirection / Safe Redirect Manager / Yoast Premium) with fallback
• One-screen Setup Wizard