Royal MCP Troubleshooting — Start Here

Update Royal MCP to the latest version

In wp-admin go to Plugins → Installed Plugins, locate “Royal MCP”, and click Update if a newer version is available. Why first: every recent release has shipped meaningful OAuth diagnostics and edge-case fixes that change what you’ll see in later steps.

• 1.4.13+ — OAuth endpoints send no-cache headers so edge caches stop poisoning them with stale responses
• 1.4.14+ — OAuth discovery (claude.ai web / ChatGPT) probes get the correct 401 + WWW-Authenticate response instead of a 405
• 1.4.15+ — API key Regenerate button actually works; MCP sessions use a 24-hour sliding TTL instead of expiring at exactly 1 hour
• 1.4.16+ — every OAuth failure writes a structured row to the Activity Log, which is what Step 4 below relies on

Most pre-1.4.16 issues that look like host problems are actually fixed by the update alone.

Run a conflict test (plugin / theme / cache)

This single step resolves the majority of remaining tickets. Don’t skip it — even if you’re certain it isn’t a conflict. We see “I already tried that” very often, and “tried similar” isn’t the same as “ran these exact steps in order.”

(a) Deactivate ALL other plugins except Royal MCP. WordPress → Plugins → check the box at the top of the list, choose Deactivate from the bulk action menu, but uncheck Royal MCP first.

(b) Switch to a default theme. Appearance → Themes → activate Twenty Twenty-Five (or any unmodified default theme). Custom themes sometimes register their own URL rewrites or rewrite filters that interfere with our OAuth endpoints.

(c) Purge every cache. Three layers, all of them:

• WordPress-side — if you use a cache plugin (LiteSpeed Cache, WP Rocket, W3 Total Cache, SpeedyCache, Hummingbird, etc.), purge it. If LiteSpeed is active, also flush the object cache.
• Server-level — SiteGround Optimizer, Kinsta cache, WP Engine cache, Liquid Web cache, Cloudways Varnish — purge in your hosting control panel. Many managed hosts have their own cache layer separate from any plugin.
• Cloudflare / CDN — if you use Cloudflare, purge everything. While you’re there, check whether “Block AI Bots” is enabled in Security → Settings — if it is, turn it off (this single setting breaks MCP for many users; see Step 5 below if disabling it isn’t enough). Also check “Bot Fight Mode” — same issue.
• Browser cache — Cmd/Ctrl+Shift+R to hard-reload the relevant Claude page.

(d) Retry the connection. If it now works, the conflict was one of the deactivated plugins or the theme. Reactivate plugins one at a time, retrying after each, until it breaks — that’s your culprit. The most common offenders we see, in rough order:

• Security plugins — Wordfence, Defender Pro, Solid Security (formerly iThemes Security), All In One WP Security & Firewall, NinjaFirewall. These intercept and sometimes block POST requests to the MCP endpoint and OAuth paths. Allowlist /wp-json/royal-mcp/*, /register, /token, and /authorize in the plugin’s firewall rules to unblock.
• Caching plugins — LiteSpeed Cache and SpeedyCache running together is a confirmed reproducer of OAuth auth-code eviction. Add cache exclusions for the same paths.
• Login/registration plugins — MemberPress, Paid Memberships Pro, Restrict Content Pro, Ultimate Member, Profile Builder. These can register a page with slug register that wins URL routing over our OAuth endpoint.
• Custom theme functions — rare, but custom themes that filter rewrite_rules_array can deregister our endpoints.

Wipe stale OAuth state

Prior connection attempts leave behind client registrations, tokens, and authorization codes that can interfere with a fresh test. Wipe them.

On Royal MCP 1.4.17 or newer (one click):

Go to Royal MCP → Settings and click the Reset OAuth State button near the bottom of the page. Confirm in the modal. Done.

On Royal MCP 1.4.16 or older (database queries):

The Reset OAuth State button doesn’t exist yet. Run these queries via phpMyAdmin, your host’s database manager, or SSH (wp db query if you have WP-CLI):

DELETE FROM wp_royal_mcp_oauth_clients;
DELETE FROM wp_royal_mcp_oauth_tokens;
DELETE FROM wp_options WHERE option_name LIKE '_transient_royal_mcp_authcode_%';
DELETE FROM wp_options WHERE option_name LIKE '_transient_timeout_royal_mcp_authcode_%';

Then on the Claude side:

• In Claude (web or Desktop), delete the existing Royal MCP connector.
• Wait 30 seconds. Claude.ai caches its own discovery state for a short window.
• Re-add the connector from scratch. This forces a full OAuth flow rather than reusing the cached (and now invalid) client credentials Claude was holding.

If the connection works after this step, the issue was stale OAuth state. You’re done.

Check the Activity Log

If steps 1–3 didn’t resolve it, this step tells us (and you) exactly which validation rule is firing — or whether the request is reaching your WordPress install at all.

In wp-admin go to Royal MCP → Activity Logs. Reproduce the failed connection attempt — click Connect in Claude, watch it fail, then come back to the Activity Log page and refresh.

If there’s a recent row whose action starts with oauth:

Click View Details. The panel shows the OAuth error code and error_description — for example:

• invalid_grant: Authorization code is invalid, expired, or already used. — usually means object cache (LiteSpeed + SpeedyCache) is evicting the auth code between /authorize and /token. Fix in Royal MCP 1.4.17.
• invalid_grant: PKCE verification failed. — usually means a security plugin is URL-decoding the POST body. Disable security plugins per Step 2.
• invalid_grant: redirect_uri mismatch. — Claude’s stored redirect URI doesn’t match what was registered. Wipe OAuth state per Step 3 and try again.
• invalid_client — client_id Claude is sending isn’t in our database. Wipe OAuth state per Step 3.
• invalid_request: Missing required parameters — something is stripping POST fields between Claude and your WordPress. Almost always a security plugin or WAF.

If the Activity Log is empty after a reproduced failure

That’s diagnostic on its own. It means the request never reached your WordPress PHP code — the failure is happening at the host edge, in a cache layer, or inside a security plugin’s firewall (before our code runs). Step 5 below lists the most common stack-specific culprits.