Royal MCP Reference

Installation

From WordPress.org (recommended)

Manual installation

Configuration

The main Royal MCP settings page showing API key and endpoint configuration.

Adding and configuring AI platforms with API keys and model selection.

Supported AI platforms

Royal MCP supports multiple AI platforms, configured independently. See AI IDE Compatibility → for the full IDE and CLI list.

Cross-plugin composers

The composer pattern stitches multiple write operations into a single atomic MCP call. Instead of asking the AI to make five separate calls (upload image, create post, set featured image, assign categories, write SEO meta), the composer does it in one, with each step logged and any failure surfaced as a warning rather than a hard error.

Available composers

Composition pattern

Composers follow a best-effort shape:

1. One step is the anchor. If it fails, the whole call fails. In wp_publish_and_promote the anchor is post creation.
2. Every other step is best-effort. Failures surface as warnings in the response but don’t block the anchor step.
3. Every step’s status is logged in the steps array of the response, so an AI agent can inspect exactly what worked and what didn’t.

Example queries

• “Draft a blog post titled ‘Winter Sale is Live’ from the outline in my notes, sideload the hero image from this URL, categorize under ‘Announcements’, tag ‘sale’ and ‘winter’, write SEO meta, and publish immediately.”
• “Schedule this launch post to publish next Tuesday at 9am with a featured image from the /media/hero.jpg URL and set the meta description to ‘...’.”
• “Save the following as a draft, categorize under ‘Case Studies’, tag with ‘retail’, and write SEO title and description. I’ll review and publish manually.”

Undo tokens

Royal MCP ships an undo-token system for reversible operations. Every destructive tool call that supports it returns a short opaque undo_token in its response. Passing that token to the mcp_undo_last_operation tool reverses the operation. Tokens live for 72 hours by default. Shipped across the Free plugin starting in v1.4.39 and expanded in v1.4.40.

Tools that issue undo tokens (Free)

• wp_delete_post restores the deleted post (or page, product, or custom post type) including all meta, terms, and revisions.
• wp_delete_term restores the deleted taxonomy term and re-attaches it to every post that had it before deletion.
• wp_delete_menu_item restores the deleted menu item at its original position.
• wp_reorder_menu_items reverts a menu reorder to its prior order.

How to use it

The flow is one extra call. When the AI agent runs a destructive tool, the response includes an undo block:

{
  "ok": true,
  "deleted_post_id": 142,
  "undo": {
    "token": "opaque-string-here",
    "expires_at": "2026-08-24T14:30:00Z"
  }
}

To reverse it, call mcp_undo_last_operation with that token:

mcp_undo_last_operation({ token: "opaque-string-here" })

Or just tell your AI in natural language: “Undo that,” “wait, restore that post,” “revert the last menu reorder.” Claude and other MCP-capable clients handle the token roundtrip internally when they see an undo block in a prior response.

Token lifetime

Undo tokens live for 72 hours after issuance. After that, the reverse-state is garbage-collected on the daily royal_mcp_token_cleanup cron. If the token is used before expiry, the reverse-state is consumed and removed. Each token is single-use.

Activity Log

Royal MCP logs all API interactions for security and debugging.

Accessing the log

Navigate to Royal MCP → Activity Log in your WordPress admin.

What each entry contains

• Timestamp when the request occurred
• MCP server which AI platform made the request
• Action the MCP tool that was called
• Status success or error
• Request and response detailed data (expandable)

Activity log showing all AI interactions with timestamps, actions, and status.

REST API reference

Endpoints

Authentication

All API requests require authentication via the WordPress API key:

Authorization: Bearer your-api-key

See API Keys → for the full authentication reference, or OAuth Connector Deep Dive → for the primary token-negotiated path.

GuardPress integration

When GuardPress is active, Royal MCP registers 7 additional tools for monitoring site security, viewing scan results, and reviewing the audit log from any AI client. Use it for daily security check-ins, on-demand vulnerability scans, blocked-IP review, failed-login analysis, and audit-log queries.

Example queries

• “What’s my current security score?”
• “Run a vulnerability scan and tell me what it finds.”
• “Show me all failed login attempts from the last 24 hours.”
• “List the IPs blocked in the past week and the reason for each block.”
• “Are there any plugins on this site with known CVEs?”
• “Summarize the security audit log for high-severity events this month.”

SiteVault integration

When SiteVault is active, Royal MCP registers 6 additional tools for triggering backups, listing backup history, and reviewing schedules. Use it for pre-update backup automation, backup health checks, “is the latest backup complete yet?” status polling, and schedule audits.

Example queries

• “Trigger a full backup before I install this plugin update.”
• “When was the last successful backup, and how big was it?”
• “Is the backup that’s currently running complete yet?”
• “Run a database-only backup right now.”
• “Show me my backup schedules and when each one runs next.”
• “What’s the total size of all my backups on disk?”

Redirection integration

When Redirection (John Godley’s plugin, 2M+ active installs) is active, Royal MCP registers 4 additional tools for listing, creating, and updating redirects, plus listing redirect groups. Added in v1.4.38.

Use it for bulk 301 setup during a site migration, cleaning up 404s an AI agent found in your Activity Log, staging redirect changes during a URL structure refactor, or asking Claude to audit redirect groups before an SEO audit.

Example queries

• “Set up 301 redirects for every old /blog/YYYY/MM/ URL to the new /articles/ structure.”
• “List every redirect in the ‘Modified Posts’ group with a hit count above 100.”
• “The old /pricing-2024/ URL is still getting hits. Redirect it to /pricing/ permanently.”
• “Show me all redirects pointing at pages that don’t exist anymore.”
• “Change the target of the /old-about redirect from /company to /about.”

Royal AI Firewall integration

When Royal AI Firewall is active, Royal MCP registers 6 additional tools for reading firewall stats, inspecting recent bot activity, and adjusting per-bot policies through natural language. Added in v1.4.37.

Royal MCP and Royal AI Firewall work as a companion pair. Royal AI Firewall sees HTTP-layer AI bot traffic hitting your site; Royal MCP lets your own AI clients act on your site. Together they give complete visibility over both sides of AI traffic on your WordPress install.

Example queries

• “How many bot hits did we get in the last 7 days, and which bots were the top 5?”
• “Show me the last 20 bot requests to /wp-json paths.”
• “Block GPTBot and CCBot but allow ClaudeBot through.”
• “Give me yesterday’s bot-hit rollup with per-bot subtotals.”
• “Turn on the master AI-bot block for the next hour while we test the site.”

ForgeCache integration

When ForgeCache is active, Royal MCP registers 3 additional tools for page cache management. Useful when an AI agent just published or updated content and needs the cache to reflect it, or when troubleshooting stale-content reports.

Example queries

• “I just updated the /pricing page. Purge its cache so visitors see the new copy.”
• “How much disk is ForgeCache using and how old is the oldest entry?”
• “Clear the entire cache. I just imported 200 posts and want everything fresh.”

Royal Links integration

When Royal Links (affiliate-link, URL-shortener, and cloaker plugin) is active, Royal MCP registers 3 additional tools for creating short URLs, listing existing links, and pulling click stats.

Use it for spinning up a branded short URL on the fly (yoursite.com/deal instead of a long UTM-tagged affiliate URL), asking Claude to pull click stats before a campaign wrap-up, or bulk-creating short URLs from a campaign spreadsheet.

Example queries

• “Create a short URL /deal that redirects to my affiliate URL for WPForms Pro.”
• “Show me my top 10 short URLs by click count this month.”
• “How many clicks did the /summer-sale link get in the last 30 days?”
• “List every short URL in the ‘affiliate’ category.”

Royal Ledger integration

When Royal Ledger (cost-tracker and license-vault plugin) is active, Royal MCP registers 4 additional tools for adding tracked costs, listing them, checking upcoming renewals, and listing stored license keys.

Use it for asking Claude to log a new subscription you just bought, getting a rundown of renewals in the next 30 days, categorizing costs (plugins, themes, hosting, domains, SaaS), or discovering which license keys are stored for a specific product.

Example queries

• “What subscriptions renew in the next 30 days?”
• “Add WPForms Pro at $199/year renewing on 2026-11-15 to my plugin costs.”
• “How much am I spending per year on hosting across all my tracked items?”
• “List every license key I have stored for ‘Elementor Pro’.”
• “Show me all expired SaaS subscriptions I’m still tracking.”

Related deep dives

Extracted references for the plugin integrations and protocol topics that have their own pages: