🛠 Troubleshooting
Connector failing, "couldn't reach the MCP server," OAuth stuck, tools missing? Start with the playbook, then the fixes real customers land on most.
30-second edge probe followed by four plugin-layer steps. Tells you in under a minute whether Cloudflare, ModSecurity, or your host is blocking before WordPress ever sees the request.
SiteGround, o2switch, LiteSpeed — managed hosts intercept the /.well-known/ URL.
SiteGroundNginx rule blocks OAuth discovery on SG. Fix via SG Site Tools or .htaccess.
WAFModSecurity's bot fingerprinting rejects legitimate MCP connections with 406.
WAFHost WAF strips code_challenge from /authorize. Common on SiteGround.
Apachepython-httpx (Claude Desktop) triggers Apache's mod_evasive on token exchange.
CloudflareZero Trust access rules shadow the OAuth discovery endpoint. Bypass without disabling protection.
SiteGroundSG + Cloudflare combo serves JSON with the wrong MIME type. Transform Rule fix.
WAFImunify360's default ruleset blocks /.well-known/ probes. Whitelist path.
OAuthRegistration didn't persist. Two-command fix, no re-install needed.
DiscoveryA membership plugin or theme is intercepting OAuth discovery. Filter fix.
WAFBitNinja aggressively blocks OAuth probes. Whitelist + reload fix.
WAFCloudProxy's edge WAF returns 403 on OAuth discovery. Fix via allowlist.
PluginPerfmatters' REST API kill switch also kills MCP. Selective un-check fix.
CDNStackCDN caches OAuth discovery responses. Purge + bypass rule.
OAuthIntermediary WAF returns non-standard 4xx on /register. Diagnostic + fix.
OAuthSome servers auto-add trailing slash, breaking dynamic client registration.
OAuthA second MCP or OAuth plugin takes over sign-in. Deactivate it and reconnect.
OAuthAn existing WP page at /register or /authorize shadows the OAuth endpoint.
OAuthActivation didn't create the OAuth tables. Re-run installer.
Claude"Authorization with [site] failed" / mcp_token_exchange_failed.
DiscoveryWP's plain permalink setting breaks pretty URLs for /.well-known/.
DiscoveryCertificate renewal daemon takes over the /.well-known/ path.
DiscoveryOld /.well-known/ files from a previous MCP plugin shadowing the current handler.
🚀 Setup & Connect
First-time setup and connecting each AI client. Claude Desktop, Web, and Terminal — ChatGPT — API-key mode when OAuth won't cooperate.
Web, Desktop, and Terminal — three OAuth flows explained side by side.
Claude Code · CodexOne command each, on the Claude or ChatGPT plan you already have. No AI API key, no per-token billing.
Guide · PopularThe end-to-end setup walkthrough — from plugin install to first tool call. The most-read Royal MCP guide on the site.
ChatGPTCustom GPT MCP setup + the two known compatibility footguns.
API KeySkip OAuth entirely. Faster on stubborn hosts. Trade-offs explained.
Claude DesktopPrompts and workflows that actually work in Claude Desktop.
OAuthThe Generate button + Save Settings step for static-client mode.
HostComplete setup playbook for SiteGround — the one host that needs its own guide.
AuthWhere to find your WordPress API key, how to send it, when to use it instead of OAuth, and how to rotate safely.
🧩 Features & Integration References
What each integration does, which tools it exposes, and how to unlock the features that require a bit more setup. Includes the Claude Skills for common builders.
Drop-in Claude Skill that teaches Claude to edit Elementor pages the right way.
Guide · PopularFour ways to hand Elementor edits to Claude, ranked by robustness. The most-read tutorial on the site.
Integration · SupportNine free Divi tools for AI-driven page editing on Divi 4 shortcodes and Divi 5 blocks, plus the Pro toolkit and deep-dive guides.
Integration · Support29 free tools across products, variations, attributes, orders, coupons, customers, and store stats.
Integration · SupportRead and write Advanced Custom Fields via Royal MCP. Type-aware writes, hydrated return values, field-group discovery.
CompatibilityConfig patterns for Cursor, VS Code, Windsurf, Zed, JetBrains, LM Studio, Ollama, and every other MCP-compliant IDE and CLI.
ProtocolHow Royal MCP implements MCP. Supported spec revisions, per-client compatibility matrix, WP Abilities API integration.
Integration · SupportEvery Elementor tool Royal MCP exposes to Claude, with parameters and example prompts.
SkillDivi-flavored Skill for Claude — knows Divi builder shortcodes and section patterns.
SkillStore-management workflows encoded as a Claude Skill.
SkillBackup + restore workflows encoded as a Claude Skill.
Feature · SupportCloudflare's WebMCP bridge lets browser agents call your Royal MCP tools using the visitor's WordPress login.
Feature · SupportLet AI scanners discover which pages are agent-ready. Opt-in schema + JSON endpoint.
Perf · SupportCut Agent Readiness scan latency ~5× with one Cloudflare Cache Rule.
Feature · ProductWhat "agent-ready" means at the site level, and how Royal MCP signals it.
Feature · ProductThe connect flow at a product level — how OAuth works across the four AI clients.
OverviewThe architecture at a glance — OAuth flow, tool registry, request handling.
🔒 Security & Diagnostics
Understand what your AI client is and isn't allowed to do, and run the diagnostic commands that pinpoint exactly where a connection is failing.
Read-only mode, drafts, undo in Free and Pro, revisions, and what removing the plugin leaves behind.
AuthWhat makes Royal MCP different: full OAuth 2.0 server as the primary connect path. Setup, security properties, every known failure mode.
ReferenceInstallation, configuration, 7 additional plugin integrations, composers, undo tokens, activity log, REST API endpoints.
WP-CLIconnection-health, list-clients and rotate-api-key. Flags, output formats, exit codes, and loops for agencies running many sites. Requires 1.5.7+.
Threat ModelWhat an AI client can and cannot do with a Royal MCP connection. Read before granting Pro undo tokens.
DiagnosticSix-line curl checklist that isolates the failure layer without touching the plugin.
PlaybookThe complete 30-second edge probe + 4-step plugin-layer decision tree.
BlogRecent security disclosures on the MCP surface + how they were addressed.
BlogCloudflare's default AI-bot signature also fingerprints legit MCP traffic. What to disable.
BlogWhat changed in CF's AI-bot defaults + which MCP paths need attention.
📰 Deeper Reading
Longer-form on why AI-in-WordPress works the way it does. Not a support ticket — a curious human.
Four ways to hand Elementor edits to Claude, ranked by robustness.
SetupThe end-to-end setup walkthrough — from plugin install to first tool call.
ComparisonWhere each fits, where they don't overlap, and how to pick.
GuideThe buyer's checklist — what to look for, what red flags to avoid.
Deep DiveWhy so much of MCP support is really about hosting quirks — and what we learned.
Big PictureWhy MCP changes what WordPress can be — and what that means for site owners.
ConceptWhat "agent-ready" means, how to test for it, and how to publish signals.
SkillsWhy Claude Skills matter for WP workflows and which skills we ship.
WorkflowScrape with Apify, ingest into WordPress via Royal MCP tools.
WorkflowChain multiple MCP servers — Claude drives DeepL and Royal MCP together.
❓ Frequently Asked Questions
The 9 questions customers ask most often about Royal MCP.
I installed Royal MCP but Claude keeps saying “couldn’t reach the MCP server” — what’s wrong?
In most cases the plugin is fine and your host or CDN is intercepting the OAuth discovery URL before WordPress sees it. First check: visit /wp-admin/admin.php?page=royal-mcp and look for an orange admin notice. Royal MCP self-checks the /.well-known/oauth-authorization-server discovery endpoint and will name the specific host or WAF product (SiteGround, Cloudflare Zero Trust, Sucuri, Imunify360, BitNinja, LiteSpeed) blocking it, with a copy-paste fix for that product. If the notice is clear but Claude still fails, run curl -i https://YOURSITE.com/.well-known/oauth-authorization-server — a healthy response is JSON with issuer, authorization_endpoint, token_endpoint, and registration_endpoint fields. See Troubleshooting — Start Here and Diagnose with curl for the full flow.
Do I need Elementor Pro, WooCommerce Pro, or Divi Pro for the AI tools to work?
No. Royal MCP’s Elementor tools work with the free Elementor plugin. Its WooCommerce tools work with free WooCommerce. Its Divi tools work with the free Divi Builder plugin or the paid Divi theme. Tools only appear when the underlying plugin is active — install WooCommerce and its wc_* tools auto-register, install Elementor and its elementor_* tools auto-register. No premium tier of any host plugin is required.
Can I use ChatGPT with WordPress through Royal MCP, or is it Claude-only?
Royal MCP works with any MCP-compliant client. Claude Desktop uses the native “Add Connector” OAuth flow. ChatGPT connects via Custom GPTs pointed at your /wp-json/royal-mcp/v1/messages endpoint. Cursor, Windsurf, Claude Code, and VS Code with GitHub Copilot’s MCP support all work. See the AI Platforms section for the full compatibility list and per-client setup patterns.
What happens if I let Claude modify my WordPress site and something breaks?
Every Royal MCP tool call is written to the Activity Log with timestamp, tool name, parameters (sensitive values redacted), and response status. WordPress’s own revision system captures every post and page edit, so post-level rollback is one click in the editor. Destructive operations move items to Trash first, so restoration is one click from the Trash view. Royal MCP Pro adds a dedicated undo layer on top: one-click undo tokens on destructive tools valid for 72 to 168 hours depending on the operation, plus a Recent Operations dashboard widget that surfaces every pending undo in one place with batch rollback support.
I’m on shared hosting — is Royal MCP going to slow down my site?
No. Royal MCP only runs when an AI client makes a request to /wp-json/royal-mcp/v1/*. It does not add any frontend code, does not hook into page rendering, and does not run on non-AI page loads. Regular visitors and Core Web Vitals scores are completely unaffected — the plugin only executes when an authenticated tool call arrives.
What’s the difference between Royal MCP (free) and Royal MCP Pro?
Free ships 200+ tools with unlimited use for as many AI clients as you connect, Drafts only and per-client access levels, 72-hour undo with a Recent Changes screen, WordPress native revisions plus Trash-based recovery, and Activity Logs that persist until you clear them. Pro adds an agency-scale governance layer on top: undo extended to 7 days, a Recent Operations dashboard widget with batch undo, extended audit retention (90 days by default, filterable), per-tool endpoint profiles that scope which tools any client can see, and priority email support. Pro is $79/site/year at founding-member pricing (regular $149/year) with the founder rate locked at renewal.
Does Royal MCP work on WordPress multisite networks?
Yes, on a per-site basis. Each site in a multisite network has its own API key, its own Activity Log, and its own settings. AI clients connect to a specific site’s MCP endpoint — Royal MCP does not bridge requests between sites in the network.
Does Royal MCP work with WPML, Polylang, or TranslatePress for multilingual content?
Yes. Translated posts appear as separate WordPress posts (each with its own ID and language meta) and are readable or writable via the standard wp_get_posts, wp_create_post, and wp_update_post tools. AI agents can list posts in a specific language by filtering on the language meta key, or translate a post and write the corresponding translation by ID.
Can I limit which posts, pages, or post types AI can access?
Yes. The wp_get_posts and wp_create_post tools accept a post_type parameter and validate it against registered public post types, so private or internal post types are not exposed. Plugin authors can disable specific tools entirely with the royal_mcp_disabled_tools filter, or scope the option-write allowlist with royal_mcp_writable_options. WordPress’s standard capability checks also apply to every tool call.
📺 Video Library
Walkthroughs, tutorials, and release notes from the Royal Plugins team plus community creators. Making your own Royal MCP video? Tag it #royalmcp in the title or description and we’ll find you and add it here.
