# Royal MCP Documentation
> Royal MCP setup guide: connect Claude, ChatGPT, or Perplexity to WordPress in 5 minutes with OAuth, plus troubleshooting and 200+ tools for Elementor.
- Canonical:
- Last updated: 2026-10-15
- HTML version:
---
## 🛠 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.
[★
Start Here
The Troubleshooting Playbook
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.](https://royalplugins.com/support/royal-mcp/troubleshooting-start-here/)
[Host
OAuth fails on managed hosts
SiteGround, o2switch, LiteSpeed — managed hosts intercept the /.well-known/ URL.](https://royalplugins.com/support/royal-mcp/oauth-fails-on-managed-host/)
[SiteGround
SiteGround returns 404 for /.well-known/
Nginx rule blocks OAuth discovery on SG. Fix via SG Site Tools or .htaccess.](https://royalplugins.com/support/royal-mcp/siteground-well-known-404/)
[WAF
ModSecurity 406 — bot fingerprint
ModSecurity's bot fingerprinting rejects legitimate MCP connections with 406.](https://royalplugins.com/support/royal-mcp/modsecurity-406-bot-fingerprint/)
[WAF
PKCE params stripped at /authorize
Host WAF strips code\_challenge from /authorize. Common on SiteGround.](https://royalplugins.com/support/royal-mcp/pkce-query-params-stripped-by-host/)
[Apache
Apache 429 on token exchange
python-httpx (Claude Desktop) triggers Apache's mod\_evasive on token exchange.](https://royalplugins.com/support/royal-mcp/apache-python-httpx-429-token-exchange/)
[Cloudflare
Cloudflare Zero Trust hijacks discovery
Zero Trust access rules shadow the OAuth discovery endpoint. Bypass without disabling protection.](https://royalplugins.com/support/royal-mcp/cloudflare-zero-trust-shadows-mcp-discovery/)
[SiteGround
Fix /.well-known/ Content-Type with CF Transform Rules
SG + Cloudflare combo serves JSON with the wrong MIME type. Transform Rule fix.](https://royalplugins.com/support/royal-mcp/siteground-cloudflare-content-type-fix/)
[WAF
Imunify360 blocks OAuth discovery
Imunify360's default ruleset blocks /.well-known/ probes. Whitelist path.](https://royalplugins.com/support/royal-mcp/imunify360-blocks-mcp/)
[OAuth
"Unknown client\_id" error
Registration didn't persist. Two-command fix, no re-install needed.](https://royalplugins.com/support/royal-mcp/unknown-client-id-error/)
[Discovery
/.well-known/ returns HTML instead of JSON
A membership plugin or theme is intercepting OAuth discovery. Filter fix.](https://royalplugins.com/support/royal-mcp/well-known-served-as-html/)
[WAF
BitNinja WebShield blocks discovery
BitNinja aggressively blocks OAuth probes. Whitelist + reload fix.](https://royalplugins.com/support/royal-mcp/bitninja-webshield-blocks-mcp/)
[WAF
Sucuri / CloudProxy blocks discovery
CloudProxy's edge WAF returns 403 on OAuth discovery. Fix via allowlist.](https://royalplugins.com/support/royal-mcp/sucuri-cloudproxy-blocks-mcp/)
[Plugin
Perfmatters "Disable REST API" blocks MCP
Perfmatters' REST API kill switch also kills MCP. Selective un-check fix.](https://royalplugins.com/support/royal-mcp/perfmatters-disable-rest-api-blocks-mcp/)
[CDN
StackCDN interferes with OAuth
StackCDN caches OAuth discovery responses. Purge + bypass rule.](https://royalplugins.com/support/royal-mcp/stackcdn-oauth-interference/)
[OAuth
ChatGPT: HTTP 466 dynamic client registration
Intermediary WAF returns non-standard 4xx on /register. Diagnostic + fix.](https://royalplugins.com/support/royal-mcp/oauth-register-nonstandard-4xx/)
[OAuth
Web server 301s /register to /register/
Some servers auto-add trailing slash, breaking dynamic client registration.](https://royalplugins.com/support/royal-mcp/oauth-register-trailing-slash-301/)
[OAuth
Another plugin is answering OAuth sign-in
A second MCP or OAuth plugin takes over sign-in. Deactivate it and reconnect.](https://royalplugins.com/support/royal-mcp/another-mcp-plugin-answers-oauth-discovery/)
[OAuth
OAuth endpoints overlap existing pages
An existing WP page at /register or /authorize shadows the OAuth endpoint.](https://royalplugins.com/support/royal-mcp/oauth-page-shadow/)
[OAuth
OAuth tables missing — "Session not found"
Activation didn't create the OAuth tables. Re-run installer.](https://royalplugins.com/support/royal-mcp/oauth-tables-missing/)
[Claude
Claude.ai Web: token exchange fails
"Authorization with [site] failed" / mcp\_token\_exchange\_failed.](https://royalplugins.com/support/royal-mcp/claude-ai-web-token-exchange-fails/)
[Discovery
Plain permalinks break OAuth discovery
WP's plain permalink setting breaks pretty URLs for /.well-known/.](https://royalplugins.com/support/royal-mcp/plain-permalinks-blocks-discovery/)
[Discovery
ACME/Let's Encrypt host intercepts /.well-known/
Certificate renewal daemon takes over the /.well-known/ path.](https://royalplugins.com/support/royal-mcp/acme-first-host-well-known-intercepted/)
[Discovery
Stale OAuth static files in webroot
Old /.well-known/ files from a previous MCP plugin shadowing the current handler.](https://royalplugins.com/support/royal-mcp/stale-well-known-static-files/)
### Not finding the answer to your issue?
Open a support ticket on the WordPress.org forum. We’ll help you get connected.
[Open a support ticket](https://wordpress.org/support/plugin/royal-mcp/)
## 🚀 Setup & Connect
First-time setup and connecting each AI client. Claude Desktop, Web, and Terminal — ChatGPT — API-key mode when OAuth won't cooperate.
[Claude
Connecting Royal MCP to Claude
Web, Desktop, and Terminal — three OAuth flows explained side by side.](https://royalplugins.com/support/royal-mcp/connecting-to-claude/)
[Claude Code · Codex
Connect Claude Code and Codex
One command each, on the Claude or ChatGPT plan you already have. No AI API key, no per-token billing.](https://royalplugins.com/support/royal-mcp/claude-code-and-codex/)
[Guide · Popular
Connect Claude to WordPress in 5 Minutes
The end-to-end setup walkthrough — from plugin install to first tool call. The most-read Royal MCP guide on the site.](https://royalplugins.com/blog/connect-claude-to-wordpress-in-5-minutes/)
[ChatGPT
Connecting to ChatGPT
Custom GPT MCP setup + the two known compatibility footguns.](https://royalplugins.com/support/royal-mcp/connecting-to-chatgpt/)
[API Key
Connect Claude Desktop via API Key
Skip OAuth entirely. Faster on stubborn hosts. Trade-offs explained.](https://royalplugins.com/support/royal-mcp/connect-claude-desktop-api-key/)
[Claude Desktop
Using Royal MCP with Claude Desktop
Prompts and workflows that actually work in Claude Desktop.](https://royalplugins.com/support/royal-mcp/using-royal-mcp-with-claude-desktop/)
[OAuth
Static OAuth Client setup
The Generate button + Save Settings step for static-client mode.](https://royalplugins.com/support/royal-mcp/static-oauth-client-setup/)
[Host
Royal MCP on SiteGround
Complete setup playbook for SiteGround — the one host that needs its own guide.](https://royalplugins.com/support/royal-mcp/royal-mcp-on-siteground/)
[Auth
API Keys Universal Reference
Where to find your WordPress API key, how to send it, when to use it instead of OAuth, and how to rotate safely.](https://royalplugins.com/support/royal-mcp/api-keys/)
## 🧩 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.
[Skill · Popular
Elementor Claude Skill
Drop-in Claude Skill that teaches Claude to edit Elementor pages the right way.](https://royalplugins.com/skills/elementor-claude-skill/)
[Guide · Popular
Editing Elementor with Claude — Four Workflows
Four ways to hand Elementor edits to Claude, ranked by robustness. The most-read tutorial on the site.](https://royalplugins.com/blog/editing-elementor-with-claude-four-workflows/)
[Integration · Support
Divi Tools Reference
Nine free Divi tools for AI-driven page editing on Divi 4 shortcodes and Divi 5 blocks, plus the Pro toolkit and deep-dive guides.](https://royalplugins.com/support/royal-mcp/divi-tools/)
[Integration · Support
WooCommerce Tools Reference
29 free tools across products, variations, attributes, orders, coupons, customers, and store stats.](https://royalplugins.com/support/royal-mcp/woocommerce-tools/)
[Integration · Support
ACF Tools Reference
Read and write Advanced Custom Fields via Royal MCP. Type-aware writes, hydrated return values, field-group discovery.](https://royalplugins.com/support/royal-mcp/acf-tools/)
[Compatibility
AI IDE Compatibility
Config patterns for Cursor, VS Code, Windsurf, Zed, JetBrains, LM Studio, Ollama, and every other MCP-compliant IDE and CLI.](https://royalplugins.com/support/royal-mcp/ai-ide-compatibility/)
[Protocol
Protocol Insights
How Royal MCP implements MCP. Supported spec revisions, per-client compatibility matrix, WP Abilities API integration.](https://royalplugins.com/support/royal-mcp/protocol-insights/)
[Integration · Support
Elementor Tools Reference
Every Elementor tool Royal MCP exposes to Claude, with parameters and example prompts.](https://royalplugins.com/support/royal-mcp/elementor-tools/)
[Skill
Divi Claude Skill
Divi-flavored Skill for Claude — knows Divi builder shortcodes and section patterns.](https://royalplugins.com/skills/divi-claude-skill/)
[Skill
WooCommerce Claude Skill
Store-management workflows encoded as a Claude Skill.](https://royalplugins.com/skills/woocommerce-claude-skill/)
[Skill
SiteVault Claude Skill
Backup + restore workflows encoded as a Claude Skill.](https://royalplugins.com/skills/sitevault-claude-skill/)
[Feature · Support
Enable Browser AI Agents (WebMCP)
Cloudflare's WebMCP bridge lets browser agents call your Royal MCP tools using the visitor's WordPress login.](https://royalplugins.com/support/royal-mcp/webmcp/)
[Feature · Support
Publish Agent Readiness Signals
Let AI scanners discover which pages are agent-ready. Opt-in schema + JSON endpoint.](https://royalplugins.com/support/royal-mcp/agent-readiness/)
[Perf · Support
Cloudflare Cache Rule for Agent Readiness
Cut Agent Readiness scan latency ~5× with one Cloudflare Cache Rule.](https://royalplugins.com/support/royal-mcp/cloudflare-cache-rule-for-agent-readiness/)
[Feature · Product
Agent-Ready — Product Overview
What "agent-ready" means at the site level, and how Royal MCP signals it.](https://royalplugins.com/royal-mcp/features/agent-ready/)
[Feature · Product
Connect — Product Overview
The connect flow at a product level — how OAuth works across the four AI clients.](https://royalplugins.com/royal-mcp/features/connect/)
[Overview
How Royal MCP Works
The architecture at a glance — OAuth flow, tool registry, request handling.](https://royalplugins.com/royal-mcp/how-it-works/)
## 🔒 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.
[Safety
Safety and Recovery for AI Edits
Read-only mode, drafts, undo in Free and Pro, revisions, and what removing the plugin leaves behind.](https://royalplugins.com/support/royal-mcp/safety-and-recovery/)
[Auth
OAuth Connector Deep Dive
What makes Royal MCP different: full OAuth 2.0 server as the primary connect path. Setup, security properties, every known failure mode.](https://royalplugins.com/support/royal-mcp/oauth-connector-deep-dive/)
[Reference
Royal MCP Reference
Installation, configuration, 7 additional plugin integrations, composers, undo tokens, activity log, REST API endpoints.](https://royalplugins.com/support/royal-mcp/reference/)
[WP-CLI
WP-CLI Commands
connection-health, list-clients and rotate-api-key. Flags, output formats, exit codes, and loops for agencies running many sites. Requires 1.5.7+.](https://royalplugins.com/support/royal-mcp/wp-cli-commands/)
[Threat Model
Direct-Connect Threat Model
What an AI client can and cannot do with a Royal MCP connection. Read before granting Pro undo tokens.](https://royalplugins.com/support/royal-mcp/direct-connect-threat-model/)
[Diagnostic
Diagnose with curl
Six-line curl checklist that isolates the failure layer without touching the plugin.](https://royalplugins.com/support/royal-mcp/diagnose-mcp-with-curl/)
[Playbook
Full Troubleshooting Playbook
The complete 30-second edge probe + 4-step plugin-layer decision tree.](https://royalplugins.com/support/royal-mcp/troubleshooting-start-here/)
[Blog
Two Vulnerabilities, Two Researchers, Two Fixes
Recent security disclosures on the MCP surface + how they were addressed.](https://royalplugins.com/blog/two-vulnerabilities-two-researchers-two-fixes/)
[Blog
When Cloudflare's AI-Bot Block Breaks MCP
Cloudflare's default AI-bot signature also fingerprints legit MCP traffic. What to disable.](https://royalplugins.com/blog/cloudflare-block-ai-bots-breaks-mcp/)
[Blog
Cloudflare Sept 15 AI-Bot Defaults
What changed in CF's AI-bot defaults + which MCP paths need attention.](https://royalplugins.com/blog/cloudflare-september-15-ai-bot-defaults/)
## 📰 Deeper Reading
Longer-form on why AI-in-WordPress works the way it does. Not a support ticket — a curious human.
[Elementor
Editing Elementor with Claude — Four Workflows
Four ways to hand Elementor edits to Claude, ranked by robustness.](https://royalplugins.com/blog/editing-elementor-with-claude-four-workflows/)
[Setup
Connect Claude to WordPress in 5 Minutes
The end-to-end setup walkthrough — from plugin install to first tool call.](https://royalplugins.com/blog/connect-claude-to-wordpress-in-5-minutes/)
[Comparison
Royal MCP vs AI Engine
Where each fits, where they don't overlap, and how to pick.](https://royalplugins.com/blog/royal-mcp-vs-ai-engine/)
[Guide
How to Evaluate a WordPress MCP Plugin
The buyer's checklist — what to look for, what red flags to avoid.](https://royalplugins.com/blog/how-to-evaluate-wordpress-mcp-plugin/)
[Deep Dive
Hosting Is the Hardest Part of Building an MCP Server
Why so much of MCP support is really about hosting quirks — and what we learned.](https://royalplugins.com/blog/hosting-is-the-hardest-part-of-building-an-mcp-server/)
[Big Picture
The WordPress MCP Era
Why MCP changes what WordPress can be — and what that means for site owners.](https://royalplugins.com/blog/wordpress-mcp-era/)
[Concept
Agent Readiness Guide
What "agent-ready" means, how to test for it, and how to publish signals.](https://royalplugins.com/blog/agent-readiness-guide/)
[Skills
Claude Skills for WordPress
Why Claude Skills matter for WP workflows and which skills we ship.](https://royalplugins.com/blog/claude-skills-for-wordpress/)
[Workflow
Connect Apify to WordPress with Royal MCP
Scrape with Apify, ingest into WordPress via Royal MCP tools.](https://royalplugins.com/blog/connect-apify-to-wordpress-with-royal-mcp/)
[Workflow
Translate WordPress with Claude + DeepL MCP
Chain multiple MCP servers — Claude drives DeepL and Royal MCP together.](https://royalplugins.com/blog/translate-wordpress-with-claude-and-deepl-mcp/)
## ❓ 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](https://royalplugins.com/support/royal-mcp/troubleshooting-start-here/) and [Diagnose with curl](https://royalplugins.com/support/royal-mcp/diagnose-mcp-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](#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.
[
Royal MCP Hits 100,000 Downloads & WebMCP](https://www.youtube.com/watch?v=R2RPdHaAK7M)
[
Connect WordPress to ChatGPT in Minutes](https://www.youtube.com/watch?v=iTZU8h3Tx-s)
[
Troubleshooting Claude & Royal MCP (Common OAuth Issues)](https://www.youtube.com/watch?v=7bsucdD-JFg)
[
Royal MCP: Install & Setup Guide](https://www.youtube.com/watch?v=pf-mdRnXezM)
[
Best Way to Connect WordPress to ChatGPT in 2026](https://www.youtube.com/watch?v=2fYPqEzE0Ak)
[
Connect ChatGPT & Claude to WordPress with MCP: Full Setup Tutorial](https://www.youtube.com/watch?v=rHh6K6yuMsY)
[
Trabajando con Royal MCP: Claude + WordPress para SEO (Español)](https://www.youtube.com/watch?v=zIz4-oQWDag)
[
Royal MCP 1.4.45: 200+ MCP Tools, 20+ Plugins Supported](https://www.youtube.com/watch?v=kpWuqoKzp94)
[
Turn Claude Into an Elementor Assistant](https://www.youtube.com/watch?v=HsEIoDz9WmY)
[
Editing Elementor With Claude (Workflow Tutorial)](https://www.youtube.com/watch?v=6P7TU1Tva3k)
[
Royal MCP & Royal AI Firewall (RAIF) Together](https://www.youtube.com/watch?v=nlpktSx27oA)
[
Royal MCP: Free WordPress MCP Plugin Walkthrough](https://www.youtube.com/watch?v=8Wbr0ReLpok)
[
Royal MCP Pro: Full Walkthrough (Agency-Tier AI Connector)](https://www.youtube.com/watch?v=dT4KACKKlzQ)
[
Royal MCP Pro 1.0.5 Release Notes](https://www.youtube.com/watch?v=Qe8psLh23hw)
[
Royal MCP 1.4.38: Big Updates & Pro Launching](https://www.youtube.com/watch?v=9vxOBhjvYSk)
[
50,000 Downloads & Feature Roadmap](https://www.youtube.com/watch?v=9rQAwaR9hHM)
[
Royal MCP: WordPress & AI Over 10,000 Downloads](https://www.youtube.com/watch?v=jTUMaf4TNII)
[Watch more on the Royal Plugins YouTube channel](https://www.youtube.com/@royalplugins)
### Community Support
Connect with other Royal MCP users, ask questions, and share tips on the WordPress.org support forums.
[Visit WordPress.org Forums](https://wordpress.org/support/plugin/royal-mcp/)