Royal MCP Troubleshooting — Read First

Plugin Support rpteam
(@rpteam)

3 weeks, 4 days ago
Hi Everyone!

Welcome to the Royal MCP plugin support forum. This pinned post is here to give you a head start on troubleshooting. Read once, save yourself hours.

================================================================
FIRST, THE GOOD NEWS
================================================================

Royal MCP works out of the box for most users. The plugin is stable, the OAuth flow is RFC-compliant, and the standard install-and-connect path works on the vast majority of WordPress sites.

But there’s an entire class of connection issues that ISN’T the plugin’s fault. About 30% of the support reports we see trace back to security configurations sitting in FRONT of WordPress — Cloudflare settings, host-level WAFs, security plugins, or cache layers blocking traffic before WordPress sees it. Those layers exist for good reasons (they protect your site), but most of them block AI-backend traffic by default. The plugin can’t fix a request that never arrives.

This post explains what’s actually happening, why MCP connections are uniquely vulnerable to security-layer blocking, and where to look first.

================================================================
WHAT IS MCP, AND WHY IS IT GETTING BLOCKED?
================================================================

MCP — the Model Context Protocol is the new standard for AI assistants like Claude, ChatGPT, and others to talk to applications such as WordPress.

When you install Royal MCP, your WordPress site becomes an MCP server that exposes 40+ tools (read posts, create pages, update meta, run WooCommerce queries, manage Elementor pages, etc.) to AI clients. The AI agent connects via OAuth, gets an access token, and then makes authenticated API calls to your site.

That’s the simple version. The catch is HOW the AI agent connects.

When Claude.ai (or any modern AI client) connects to your WordPress site, the OAuth flow happens in TWO halves:
```
1. THE BROWSER HALF - Your browser opens a consent page. You click "Authorize". This whole step uses a normal browser
```
User-Agent and looks like normal web traffic. No security tool blocks it.
```
2. THE SERVER-TO-SERVER HALF - Now the AI client's BACKEND (not your browser) makes a server-to-server POST to your
```
site to exchange the authorization code for an access token. This request:
– Identifies itself with a non-browser User-Agent (Anthropic’s backend uses “python-httpx”)
– Comes from a datacenter IP, not a residential one
– Has fewer headers than a typical browser request

If your site has security tools running, they often fingerprint this kind of request as “bot traffic” and block it BEFORE WordPress even sees it.

This is the key insight: the OAuth flow has TWO HALVES. The browser half works for almost everyone. The server-to-server half is where the vast majority of connection failures happen and those failures live in security tools, not in WordPress. From your perspective, the symptom looks like “the plugin failed mysteriously.” From the protocol’s perspective, the request was rejected at a layer the plugin can’t see or control.

The fix is almost always a config change at the edge -telling Cloudflare, your host WAF, or your security plugin to allow legitimate AI-backend traffic through. We’ve documented the specific change for each major host and stack.

================================================================
THE MOST COMMON BLOCKERS (ROUGHLY IN ORDER OF FREQUENCY)
================================================================
```
1. Cloudflare "Block AI Bots" / "Bot Fight Mode" / "AI Crawl Control"
   — Cloudflare has THREE separate panels that can block AI traffic, and
     turning one off doesn't disable the others. This is the single most
     common cause of "OAuth consent works, then Claude can't reach the server."

2. Cloudflare Zero Trust Access / MCP Portal
   — If you (or your IT team) ever set up CF Zero Trust Access, or followed
     Cloudflare's own AI assistant suggesting an "MCP Portal," it can intercept
     your /.well-known/ discovery and redirect OAuth to a competing service.

3. cPanel ModSecurity
   — On shared hosting (InMotion, A2 Hosting, Bluehost, HostGator, GreenGeeks,
     Namecheap), ModSecurity is bundled by default. It returns 406 with
     "Mod Security" in the response body for traffic it fingerprints as
     non-browser.

4. Apache + Imunify360 / mod_security with UA rules
   — Apache shared hosts running managed bot defense often return 429 Too
     Many Requests specifically for the python-httpx User-Agent, which is
     what Anthropic's OAuth backend uses.

5. Membership plugins (MemberPress, Restrict Content Pro, Paid Memberships
   Pro, etc.)
   — These hook early in WordPress and can intercept
     /.well-known/oauth-authorization-server, returning a login page instead
     of the JSON metadata clients expect.

6. SiteGround nginx /.well-known/ block
   — SiteGround's nginx (and some Hostinger / o2switch configurations)
     reserve the .well-known/ path prefix for ACME certificate validation
     and return 404 for everything else.

7. Managed host edge caches
   — SiteGround Dynamic Cache, o2switch PowerBoost, LiteSpeed Cache, and
     similar layers can serve stale OAuth responses that break the
     auth-code-to-token exchange.

8. Web server trailing-slash canonicalization
   — nginx mod_dir and Apache .htaccess sometimes add a trailing slash to
     /register, /authorize, /token URLs. OAuth clients don't follow redirects
     on POST requests, so registration silently breaks.
```
Each of these has a specific documented fix, linked below.

================================================================
STEP 0 – THE 30-SECOND DIAGNOSTIC PROBE
================================================================

The fastest way to figure out which pattern you’ve hit is to run a single curl command from your local machine (not your WordPress server):
```
  curl -sS https://YOUR-SITE.com/.well-known/oauth-authorization-server
```
(Windows PowerShell users: use curl.exe instead of curl.)

Match the response to the patterns documented in our start-here guide:
https://royalplugins.com/support/royal-mcp/troubleshooting-start-here.html

The response shape tells you whether the problem is at your edge (Cloudflare / ModSec / host firewall) or inside WordPress, which determines which fix applies.

================================================================
JUMP DIRECTLY TO THE FIX BY SYMPTOM
================================================================

★ OAuth completes, then Claude says “Couldn’t reach the MCP server” + ofid_* code
→ Cloudflare blocking AI bots
→ https://royalplugins.com/blog/cloudflare-block-ai-bots-breaks-mcp/

★ Token exchange fails with “mcp_token_exchange_failed” on Apache shared host
→ Apache + Imunify360 / mod_security blocking python-httpx UA
→ https://royalplugins.com/support/royal-mcp/apache-python-httpx-429-token-exchange.html

★ Activity Log empty + curl returns 406 with “Mod Security” in the body
→ cPanel ModSecurity 406 fix (InMotion, A2 Hosting, Bluehost, HostGator class)
→ https://royalplugins.com/support/royal-mcp/modsecurity-406-bot-fingerprint.html

★ Discovery returns JSON but “issuer” points to auth.
→ Cloudflare Zero Trust hijacking /.well-known/ discovery
→ https://royalplugins.com/support/royal-mcp/cloudflare-zero-trust-shadows-mcp-discovery.html

★ Discovery returns HTML instead of JSON (login page, access-denied screen)
→ OAuth discovery HTML hijack (membership plugin / theme template)
→ https://royalplugins.com/support/royal-mcp/well-known-served-as-html.html

★ /.well-known/ returns 404 on SiteGround / Hostinger / o2switch
→ SiteGround /.well-known/ 404 fix (nginx path-prefix block)
→ https://royalplugins.com/support/royal-mcp/siteground-well-known-404.html

★ POST to /register gets a 301 redirect with trailing slash
→ Trailing-slash 301 fix (nginx mod_dir / Apache canonicalization)
→ https://royalplugins.com/support/royal-mcp/oauth-register-trailing-slash-301.html

★ Managed host edge cache serving stale OAuth responses
→ Managed host edge cache fix (SiteGround Dynamic Cache, o2switch PowerBoost, LiteSpeed)
→ https://royalplugins.com/support/royal-mcp/oauth-fails-on-managed-host.html

★ Just want to skip OAuth on Claude Desktop (two-line config change)
→ API key bypass — no /.well-known/ discovery required
→ https://royalplugins.com/support/royal-mcp/connect-claude-desktop-api-key.html

================================================================
DEEPER GUIDES
================================================================

Full troubleshooting checklist (symptom-based router):
https://royalplugins.com/support/royal-mcp/troubleshooting-start-here.html

Diagnose Royal MCP with curl (deep protocol-level walkthrough, includes paste-ready bash + PowerShell diagnostic script):
https://royalplugins.com/support/royal-mcp/diagnose-mcp-with-curl.html

Royal MCP Support Hub (full docs, integrations, reference):
https://royalplugins.com/support/royal-mcp/

================================================================
AFTER READING THE DOCS, STILL STUCK?
================================================================

Post a new thread here with:
– The output of the Step 0 curl probe
– Your hosting provider
– Royal MCP version
– The exact error message you’re seeing
– Whether Cloudflare is in front of your site, and if yes which security panels are enabled

We monitor this forum regularly. Community members are also welcome to chime in – many have hit the same patterns and may have stack-specific tips.

You must be logged in to reply to this topic.