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
    |
    |  Two data flows:
    |  1. Plugin reads IATO data → enriches with WP post IDs → returns to AI
    |  2. Plugin reads WP data → writes to IATO (sync tools)
    |
IATO Platform  (iato.ai/api/v1)
  Auth: Authorization: Bearer {iato_api_key}

Requirements

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

Installation

Install the plugin and have your site running as an MCP server in under 5 minutes.

1. Download the plugin ZIP from GitHub Releases. Free and open source under GPL v2.
2. Upload via WP Admin: Go to Plugins → Add New → Upload Plugin. Select the ZIP file and click Install Now.
3. Activate the plugin. An MCP API key is generated automatically on activation. Your site is now an MCP server.
4. Verify: Go to Settings → IATO MCP. You should see your MCP endpoint URL and API key.

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.

WordPress Native Tools 30 tools

These tools read and write WordPress directly. No IATO account needed.

New Tool Details

update_canonical

Set or update the canonical URL for a post. Auto-detects SEO plugin (Yoast/RankMath/SEOPress).

update_structured_data

Add or update JSON-LD structured data for a post. Stored as custom meta, output via wp_head.

update_taxonomy

Replace all terms for a given taxonomy on a post (not append).

update_redirect

Create or update a redirect rule. Auto-detects redirect plugins (Redirection, Safe Redirect Manager, Yoast Premium) or uses built-in fallback.

IATO Bridge Tools 9 tools — requires IATO API key

These tools call the IATO API, then resolve IATO node/page IDs to WordPress post IDs and slugs so your AI client can chain directly into WP native tools.

WordPress → IATO Sync Tools 4 tools — requires IATO API key

Push WordPress data into IATO so the platform has live content without waiting for a crawl. All support dry_run mode.

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.

Admin Features

Phase 2 adds three admin interfaces for managing AI-driven changes.

Setup Wizard

Accessible at wp-admin/admin.php?page=iato-mcp-setup. Requires manage_options capability.

Review Queue

Top-level admin menu: “IATO Reviews”. Requires edit_posts capability.

Dashboard Widget

Appears on the wp-admin dashboard as “IATO SEO Health”. Data cached with 5-minute transient.

Authentication

The plugin uses a plugin-generated API key stored in wp_options. Three 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

Three 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 sync_wp_pages_to_iato(sitemap_id, post_type: 'page')
   → Plugin: get_posts() reads all WP pages
   → Plugin: create_sitemap_node() per page via IATO API
   → IATO sitemap now has nodes matching live WP structure

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