Troubleshooting — Start Here

Something isn't working on your Royal MCP Pro install. This page is the master triage — find the row that matches your symptom and follow the link to the detailed doc. Most Pro-tier failures actually resolve at the Free troubleshooting layer first because the underlying MCP-connection surface is shared. Start there before assuming it's a Pro-specific bug.

The 80/20: start with the Free troubleshooting guide

Roughly 80% of tickets we receive on Royal MCP Pro turn out to be host-layer or MCP-connection issues that would fire the same way on Free tier. Cloudflare / Imunify360 / BitNinja / StackCDN intercepting the OAuth handshake. Host WAF blocking outbound POSTs to my.royalplugins.com. Claude Desktop connector dropping tool calls before they reach WordPress. None of that is Pro-specific — and it's all covered end-to-end in the Free guide.

If your symptom is "Claude can't connect," "OAuth failed," "ofid_… error," "tool call timed out," or "connector says reconnect" — go there first. Come back to Pro-specific docs only if the Free guide rules that layer out.

Open Free Troubleshooting — Start Here →

Pro-specific symptom triage

The four situations below are Pro-only. If your symptom matches one of these, the Free guide won't help — jump straight to the linked doc.

License won't activate

You entered your Purchase Email + License Key on the License page and clicked Activate, but got an error notice. The license itself is fine on My Account, but activation on this site refuses to complete.

Common variants

"License activation failed" (server rejected the key — wrong plugin, wrong email, expired, at limit)
"License server error" (host WAF blocking outbound HTTPS to my.royalplugins.com)
"Invalid response from license server" (CDN interstitial mangling the response body)
"Please enter a license key" (form submitted with a blank field)

Open License Activation Issues →

Pro tool returns upgrade prompt with valid license

The License page shows the key as active, the activation-count moved up by one on My Account, but when you call a Pro tool from your MCP client, the response comes back as an upgrade prompt (🔒 {tool_name} is a Royal MCP Pro feature.) anyway.

Almost always caused by

A sibling Royal Plugin Pro (ForgeCache, FormForge, GuardPress, Royal Affiliate Pro) loading its older SDK copy first — via the WordPress alphabetical plugin-load order — and shadowing Royal MCP Pro's newer SDK
Object cache holding a stale "invalid" license transient
SDK bootstrap failure (rare — opcache serving stale bytecode, corrupt install)

Open Upgrade Prompt with Valid License →

Undo tool returned an error

You called royal_mcp_undo_last_operation with the token from a prior Pro tool response, but it returned an error instead of reversing the operation. Every possible error code has a specific fix.

The 6 possible codes

token_not_found — empty arg, wrong string, or purged row (past 30-day retention)
token_consumed — already used once (tokens are one-shot)
token_expired — past its TTL (72h default, 168h for SEO / Widget / Redirection bulk)
undo_handler_missing — tool's undo handler not loaded (plugin deactivated after write, or upgrade broke mapping)
undo_handler_failed — data state changed since original write, handler threw
insufficient_caps — you're not the original actor and lack override caps

Open Undo Token Errors →

Pro tool refused with "builder session detected"

You called a Divi or Elementor Pro write tool and it came back with builder_session_active instead of the change you asked for. The tool detected an active editor session on the target post and refused to write — not a bug, a deliberate guard against silently clobbering someone's in-progress editor work.

Three resolutions

Close the editor tab and retry (safest — guaranteed no auto-save collision)
Wait ~150 seconds for the WordPress edit lock to go stale, then retry
Pass force=true to the tool call to explicitly acknowledge the risk and proceed anyway

Open Builder Session Detected →

Combined symptoms — hybrid patterns

Sometimes a ticket looks Pro-specific but is really two problems stacked. A few common combinations:

"Pro tools work fine, but every tool call takes 20+ seconds"

Almost never a Royal MCP Pro issue. Usually the licensing server call is timing out on your host's outbound path and the SDK is retrying. Check outbound HTTPS to my.royalplugins.com from your server. Fix: host allowlist for that domain, or (if you've verified the license state locally) reduce the SDK's check-in frequency via the wpgenius_license_check_interval filter.

"Everything works from Claude Desktop but fails from Claude.ai web"

Free-tier surface issue, not Pro. Claude.ai's web connector uses OAuth for auth; Claude Desktop typically uses API keys. If OAuth is broken (host WAF, CDN interstitial, ChatGPT DCR mismatch) then only the OAuth-based client fails. Free troubleshooting guide covers this.

"Pro tool call succeeds but the change didn't take"

Almost always a page cache. Royal MCP Pro writes to the DB successfully, but the visitor-facing page is served from ForgeCache / LiteSpeed Cache / WP Rocket / edge CDN's cache. Clear the page cache and reload. This is why the wp_publish_and_promote_pro composer includes a ForgeCache purge step — use it whenever you write and want the change immediately visible.

"Pro tool call succeeded, but Divi/Elementor front-end still shows old content"

Same class as the above — but specifically, Divi and Elementor both maintain their own CSS caches (Divi's static CSS, Elementor's inline-CSS storage). A content write via MCP triggers post-content dirty state, but the builder's CSS file cache may not regenerate until the next admin visit to the page in the editor. Fix: visit the page once in the editor to trigger regeneration, or clear the builder's CSS cache from its settings.

Before you email support — 4-line diagnostic

Regardless of which symptom matches, gathering these four data points before you email speeds up a support ticket dramatically:

Which Royal Pros are active on the site + what versions (Plugins page). This surfaces the sibling-SDK-shadow case at a glance.
Which MCP client + which tool + the exact response text. Paste the full response, not a paraphrase. Error codes are load-bearing.
Does the same call work from a different client? (e.g. from Claude Desktop if Claude.ai web fails, or vice versa). Isolates client-side vs. server-side.
Screenshot of the Pro tool row in Audit Log with View Details expanded (WP admin → Royal MCP Pro → Audit Log). Shows what the plugin actually did vs. what you thought it did.

Having all four in the initial email cuts a typical ticket resolution from 2-3 round-trips down to one.

Still Stuck? Two-Step Support Path

If your symptom doesn't match any of the above, and the Free troubleshooting guide didn't help either, contact us directly.

Step 1: Try the Free Troubleshooting Guide first (if you haven't yet)

Royal MCP Troubleshooting — Start Here covers the MCP-layer diagnostic tree in depth. If you skipped it, run through it once now — the majority of "unexplained Pro issues" resolve there.

Step 2: Email priority support

If the Free guide + one of the Pro-specific docs above still doesn't get you unstuck, email priority support from your purchase email address at support@royalplugins.com. Priority email support is included with your license — typical response within 24 hours. Never include your license key in email; we look it up from your purchase address.

What to include in your email (the 4-line diagnostic above, plus)

Your hosting provider (SiteGround, Cloudways, Hostinger, Kinsta, WP Engine, self-hosted VPS, etc.)
Royal MCP Pro version from WP Admin → Plugins
WordPress + PHP versions
Active caching plugins (LiteSpeed Cache, WP Rocket, W3 Total Cache, SpeedyCache, Hummingbird, none)
Active security plugins (Wordfence, Defender Pro, Solid Security, NinjaFirewall, none)
Cloudflare or CDN in front of the site? If yes, is "Manage AI Bots" or "Bot Fight Mode" on?
Which steps you tried from this doc + the Free guide and what changed at each