Fix: MCP Connection Issues Between AI Assistants and WordPress

So you followed our guides for Claude Desktop, Claude Code, ChatGPT, or OpenClaw, hit Connect, and got “Couldn’t reach the MCP server” almost instantly. 😶 Or you logged in, never saw the consent screen, and landed on “Authorization with the MCP server failed“. The frustrating truth: most of these failures are not in AI Engine. They’re at the host, the WAF, or somewhere upstream of WordPress.

This article maps the most common failure points we’ve seen across real hosting setups (LocalWP, SiteGround, WP Engine, sites behind Wordfence) and gives you the exact checks and fixes for each. Each section starts with a one-screen summary so you can self-diagnose in seconds.

New to MCP? MCP for WordPress is the friendly beginner intro. This article is for when the connection itself is misbehaving.

Symptom Quick Lookup

Don’t know where to start? Match what you’re seeing, then jump to the right Issue. If your symptom isn’t here, the Quick Diagnostic Checklist just below walks you through every layer methodically.

• “Couldn’t reach the MCP server” instantly, no browser popup → Issue 1 (local-only site) or Issue 2 (host blocks /.well-known/)
• 404 on /.well-known/oauth-authorization-server/wp-json/mcp/v1 → Issue 2
• Same MCP URL returns 200 with a normal User-Agent but 403 with -A "python-httpx/0.28.1" → Issue 3
• Browser login succeeds, no consent screen ever loads → Issue 4
• Consent loads, you click Approve, then “Authorization with the MCP server failed” → Issue 5
• 302 redirect to wp-login.php when you curl /oauth/authorize → not a problem, that endpoint is browser-only
• 405 on claude.ai/v1/toolbox/shttp/mcp/[uuid] in Claude Desktop’s dev tools → that’s Claude polling Anthropic, not your server — see Issue 5

What a Successful Connect Actually Looks Like

Knowing the happy path is half the diagnosis. When you click Connect in Claude Desktop or claude.ai, the click is server-side: Anthropic’s backend (User-Agent python-httpx/0.28.1) does the OAuth dance. Your browser only opens for the consent screen. Here’s the full sequence:

1. Discover — Anthropic GETs the protected-resource metadata at the host-root path (/.well-known/oauth-protected-resource/wp-json/mcp/v1/http) and the authorization-server metadata (/.well-known/oauth-authorization-server/wp-json/mcp/v1).
2. Register — POST to /wp-json/mcp/v1/oauth/register for Dynamic Client Registration. Returns a client_id.
3. Consent — your browser opens /wp-json/mcp/v1/oauth/authorize, you sign in if needed, click Approve.
4. Token — Anthropic POSTs to /wp-json/mcp/v1/oauth/token with the PKCE verifier, gets back an access token.
5. MCP call — the first real MCP request hits /wp-json/mcp/v1/http with User-Agent: Claude-User and Authorization: Bearer ….

If you see “Couldn’t reach the MCP server” within a second or two, step 1 or 2 failed — Anthropic’s backend never got past discovery. If you reach the WordPress login screen but the consent never appears, step 3 broke. Different stages, different fixes.

Quick Diagnostic Checklist

Run these from any shell (not from your AI assistant), top to bottom. Each one isolates a different layer.

🪟 On Windows / PowerShell: PowerShell aliases curl to Invoke-WebRequest, which has a completely different syntax. Use the explicit binary: curl.exe -i "https://..." with double quotes around URLs. For POST bodies, save the JSON to body.json and pass --data "@body.json" — inline single-quoted JSON gets mangled.

1. Is the site publicly resolvable?

curl -s "https://dns.google/resolve?name=yoursite.example&type=A" | head -c 300

If you see "Status": 3 (NXDOMAIN), your hostname doesn’t exist on the public internet. Jump to Issue 1.

2. Does the MCP endpoint respond from outside?

curl -i -X POST https://yoursite.example/wp-json/mcp/v1/http 
  -H "Content-Type: application/json" 
  -H "Accept: application/json, text/event-stream" 
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

Expect HTTP/2 401 with a WWW-Authenticate: Bearer realm="MCP", resource_metadata="…" header. Anything else (502, 404, HTML, timeout) means the request never reached AI Engine — your host, proxy, or security layer is interfering.

3. Does OAuth discovery work at both URL shapes?

curl -i https://yoursite.example/wp-json/mcp/v1/.well-known/oauth-protected-resource
curl -i https://yoursite.example/.well-known/oauth-protected-resource/wp-json/mcp/v1/http

Both should return 200 with the same JSON body. If only the first works, your host is short-circuiting /.well-known/*. Jump to Issue 2.

4. Same URL but with Anthropic’s User-Agent

curl -i -A "python-httpx/0.28.1" https://yoursite.example/.well-known/oauth-protected-resource/wp-json/mcp/v1/http

If step 3 returned 200 but this one returns 403, a WAF is filtering on User-Agent. This is the single most common failure on WP Engine. Jump to Issue 3.

5. Tail the PHP error log during a Connect attempt

Enable AI Engine → Settings → Dev Tools → Queries Debug and make sure WP_DEBUG_LOG is set in wp-config.php so PHP errors actually land in a file. Then:

tail -f /path/to/php/error.log | grep "AI Engine MCP OAuth"

On a healthy Connect attempt you should see lines like these, in order:

[AI Engine MCP OAuth] Host-root PRM hit: /.well-known/oauth-protected-resource/wp-json/mcp/v1/http
[AI Engine MCP OAuth] Host-root ASM hit: /.well-known/oauth-authorization-server/wp-json/mcp/v1
[AI Engine MCP OAuth] Registered client: Claude (cid_xxxxxxxxxxxxxxxx)
[AI Engine MCP OAuth] Authorized user 1 for client cid_xxxxxxxxxxxxxxxx

What the gaps tell you:

• Nothing at all during the click → discovery is blocked upstream of PHP. See Issue 2 or Issue 3.
• Only PRM hit, no ASM hit → the authorization-server metadata path is being intercepted. See Issue 2.
• Registered client appears but no Authorized user → the consent flow died in the browser. See Issue 4.
• Authorized user appears but the connector still says failure → Anthropic’s POST to /oauth/token isn’t reaching PHP. The token endpoint itself doesn’t log yet, so confirm by tailing your web server access log for POST /wp-json/mcp/v1/oauth/token. See Issue 5.

On WP Engine, also check User Portal → Logs → Access, filter by oauth, and look for 403s with Log Type: nginx — those are blocked at the edge before PHP runs.

Issue 1: Your Site Is Only Reachable Locally

🔍 Symptoms: “Couldn’t reach the MCP server” instantly; a DNS lookup for your site (dns.google/resolve?name=yoursite.example) returns NXDOMAIN.
💡 Cause: Your hostname only resolves through /etc/hosts on your machine (LocalWP, MAMP, *.test). Anthropic’s servers have no way to see it.
🛠️ Fix: Put the site behind a public URL — Cloudflare Tunnel, ngrok, Tailscale Funnel, or a real staging host.

If you’re running WordPress in LocalWP, MAMP, Laravel Valet, Docker, or any “*.test” / “*.local” setup, your site lives at a hostname that only resolves through /etc/hosts on your own machine. Anthropic’s servers have no idea it exists. The Connect click fails because DNS resolution itself fails. 🛰️

Confirm it:

curl -s "https://dns.google/resolve?name=mysite.test&type=A"
# {"Status":3, ...}  → NXDOMAIN, not on the public internet

Adding entries to /etc/hosts only fixes your laptop, not the internet. You need a public URL.

Fix: the cleanest option for local dev is a Cloudflare Tunnel — free, no inbound ports to open, a real public hostname.

# ~/.cloudflared/config.yml
tunnel: <tunnel-uuid>
credentials-file: /Users/you/.cloudflared/<tunnel-uuid>.json
ingress:
  - hostname: yoursite.example
    service: http://localhost:80
  - service: http_status:404

cloudflared tunnel route dns <tunnel-uuid> yoursite.example
cloudflared tunnel run <tunnel-uuid>

Other options: ngrok, Tailscale Funnel, localtunnel, or simply test on a real staging site with a real A record.

Issue 2: Your Host Blocks /.well-known/*

🔍 Symptoms: A curl against /.well-known/oauth-protected-resource/... returns 404; AI Engine’s debug log stays empty during Connect.
💡 Cause: Your host or CDN intercepts the entire /.well-known/ prefix before WordPress sees it. Common on SiteGround, sometimes Cloudflare.
🛠️ Fix: Two paths — Option A: remove the rewrite exclusion if you control the server. Option B: when your host won’t budge, mask the bad URL with a Cloudflare URL Rewrite at the edge.

AI Engine serves OAuth discovery metadata at the RFC-compliant host-root paths (/.well-known/oauth-protected-resource/… and /.well-known/oauth-authorization-server/…). Some managed hosts ship server-level rewrites that short-circuit /.well-known/ entirely, usually to keep Let’s Encrypt’s acme-challenge direct from the filesystem. The whole prefix never reaches WordPress’s index.php. 🧱

SiteGround is the host we’ve seen this on most often, and they’ve now confirmed (on @paddyv’s AI Engine support thread) that the /.well-known/ interception is a fleet-wide nginx config they will not adjust per-site. So if you’re on SiteGround, skip straight to Option B below. The same pattern shows up on other managed hosts, and it can equally happen at a CDN layer (Cloudflare, especially) sitting in front of the origin.

Confirm it:

curl -i https://yoursite.example/wp-json/mcp/v1/.well-known/oauth-protected-resource
curl -i https://yoursite.example/.well-known/oauth-protected-resource/wp-json/mcp/v1/http

If the first returns 200 and the second returns 404, your hosting layer is the problem — PHP never runs for that URL, so the plugin cannot fix it from inside WordPress.

# A "real" WordPress 404 (has the Link header, has no-cache control)
curl -i https://yoursite.example/this-page-does-not-exist

# Your /.well-known/ 404 (probably doesn't)
curl -i https://yoursite.example/.well-known/oauth-authorization-server/wp-json/mcp/v1

Option A: You Control the Server (Self-Hosted, VPS)

In your .htaccess (Apache) or vhost (nginx), find the rule that looks like:

RewriteCond %{REQUEST_URI} !^/.well-known/

Either remove it entirely, or scope it tightly to just the ACME path:

RewriteCond %{REQUEST_URI} !^/.well-known/acme-challenge/

Option B: Your Host Won’t Budge (Cloudflare URL Rewrite)

On fully-managed hosts you typically can’t touch the server config — and as @paddyv discovered on SiteGround, the support team flat-out refused to adjust the rewrite (it’s their fleet-wide nginx config). The good news: if Cloudflare (or any rewrite-capable CDN) is sitting in front of the host, you can quietly rewrite the failing RFC 8414 URL to the path-suffixed one that already works, at the edge, before the request ever reaches the origin. The free Cloudflare plan is enough. 🐮

In your Cloudflare zone, go to Rules → Transform Rules → Rewrite URL → Create rule and configure:

• Rule name: OAuth AS metadata — RFC 8414 path
• If incoming requests match (Custom filter expression): Hostname equals www.yoursite.example AND URI Path equals /.well-known/oauth-authorization-server/wp-json/mcp/v1
• Then… Rewrite parameters: Path → Rewrite to… Static → wp-json/mcp/v1/.well-known/oauth-authorization-server
• Query: Preserve

Four gotchas worth knowing:

1. Cloudflare must be proxied (orange cloud on the DNS record), not DNS-only. In DNS-only mode the request never traverses Cloudflare, so the Transform Rule never fires.
2. If the visual Custom filter expression builder doesn’t seem to match, switch to Edit expression and paste the expression literally: (http.host eq "yoursite.example" and http.request.uri.path eq "/.well-known/oauth-authorization-server/wp-json/mcp/v1"). The builder can produce subtly different patterns for the same intent.
3. No leading slash in the Static textbox. Cloudflare’s UI shows a fixed / in front of the field and prepends it for you — if you include one, you’ll rewrite to //wp-json/… and the rule silently fails.
4. The URI Path match is exact, so it only catches that one OAuth metadata path. Other /.well-known/ traffic (ACME challenge, security.txt, etc.) is unaffected.

Verify with:

curl -i https://www.yoursite.example/.well-known/oauth-authorization-server/wp-json/mcp/v1

You should see HTTP/2 200, content-type: application/json, and the full AS metadata body. You only need to rewrite the authorization-server path — the protected-resource document is handed to the client by AI Engine via the WWW-Authenticate: resource_metadata="…" hint, which already points at the path-suffixed URL that works. No second rule needed. 🙌

Cloudflare in front of any host is the universal escape hatch for these edge-layer interferences — you’ll see it again as the fix for Issue 3 (WP Engine’s User-Agent WAF). If your host actively fights you on rewrites, the longer-term cure is picking one that doesn’t. We keep a list of WordPress hosts we trust in our hosting recommendations.

Issue 3: WP Engine WAF Blocks the python-httpx User-Agent

🔍 Symptoms: Connect fails on a WP Engine site; the same URL returns 200 with a normal user agent but 403 with -A "python-httpx/0.28.1"; AI Engine debug log stays empty.
💡 Cause: WP Engine’s built-in WAF blocks any User-Agent containing “python” on MCP and OAuth paths — before PHP even runs.
🛠️ Fix: Add a Cloudflare Transform Rule on your zone that rewrites the User-Agent for those paths before the request reaches WPE.

This one is sneaky, because everything else looks fine. The site responds normally from your browser, AI Engine debug logs are completely empty during the Connect click, and there’s no obvious error to grep. The reason: WP Engine’s built-in WAF (their “Global Edge Security” layer at nginx) returns 403 Forbidden to any request whose User-Agent contains python when the path matches /.well-known/oauth-* or /wp-json/mcp/v1/*. Anthropic’s backend uses User-Agent: python-httpx/0.28.1, so every discovery probe gets blocked at the edge before PHP even runs. 🚫

Confirm it:

# Normal UA → 200
curl -i https://yoursite.example/.well-known/oauth-protected-resource/wp-json/mcp/v1/http

# Anthropic's UA → 403 (blocked at WPE nginx)
curl -i -A "python-httpx/0.28.1" https://yoursite.example/.well-known/oauth-protected-resource/wp-json/mcp/v1/http

In the WP Engine portal under Advanced → Logs → Access, filter by oauth: the blocked requests show up as Log Type: nginx, Status: 403, User agent: python-httpx/0.28.1, and Remote address: 160.79.x.x (Anthropic’s outbound range).

Fix (the one we use): add a Cloudflare Transform Rule on the site’s Cloudflare zone that rewrites the User-Agent for the affected paths before the request reaches WP Engine’s origin.

1. Open your site’s Cloudflare zone → Rules → Transform Rules → Modify Request Header → Create rule
2. Name: MCP — strip python UA before WP Engine
3. Custom filter expression:

   (starts_with(http.request.uri.path, "/.well-known/oauth-")
     or starts_with(http.request.uri.path, "/wp-json/mcp/v1/"))
     and lower(http.user_agent) contains "python"

4. Modify request header → Set static → header name User-Agent → value AnthropicMCP/1.0 (any non-“python” string works)
5. Deploy.

WPE’s WAF now sees AnthropicMCP/1.0 instead of python-httpx/0.28.1 and lets the request through. Verify with the same curl as before — the second one should now return 200. After deploying, delete and recreate the connector in Claude or ChatGPT to clear its server-side “broken” cache.

If you can’t use Cloudflare:

• Ask WP Engine support to whitelist 160.79.104.0/22 for /wp-json/mcp/v1/* and /.well-known/oauth-* paths. Slower but works.
• Move the site to a host without an aggressive UA-based WAF. Most VPS and self-hosted setups don’t have this problem.

Things that look like fixes but aren’t: WPE wp-admin “Web rules” (those are customer rules and can’t override the built-in WAF), Cloudflare Bot Fight Mode toggles, or clearing WPE caches. The 403 is generated fresh at nginx, upstream of all of those.

A note on per-IP flags: if you tested heavily with curl -A python-httpx/… from your laptop while diagnosing, WPE’s WAF accumulates a per-IP reputation and starts 403-ing everything on these paths from your IP, regardless of UA. Wait it out, or test from another network. Anthropic’s range is not flagged because it doesn’t normally hit these paths in bursts.

Issue 4: Consent Screen Never Appears

🔍 Symptoms: WP login succeeds, but the OAuth consent screen never loads; you bounce back to the AI assistant with “Authorization with the MCP server failed”.
💡 Cause: A 2FA plugin (often Wordfence), an aggressive cache, or a login-renamer drops the post-login redirect on the way back to /oauth/authorize.
🛠️ Fix: Add /wp-json/mcp/v1/oauth/* to the interfering plugin’s URL allow-list, then retry from a fresh incognito window.

Connector created. Click Connect. WordPress login appears. You sign in successfully… and then instead of the AI Engine consent screen, you bounce back to the AI assistant with “Authorization with the MCP server failed“. The flow died between the login and the consent step. 🐉

Most likely culprits:

• Wordfence Login Security 2FA. The user authenticates against WordPress, then Wordfence intercepts with its own 2FA challenge. In several configurations the original redirect_to parameter is dropped at the 2FA step, so after the second factor the user lands on /wp-admin/ instead of bouncing back to /wp-json/mcp/v1/oauth/authorize?.... The consent screen is never reached.
• Aggressive page caching (WP Fastest Cache, some CDN config) that ignores nocache_headers() on the authorize endpoint and serves a stale or empty response in place of the consent page.
• Login-page renamers / hide-login plugins (iThemes Security, WPS Hide Login, Wordfence’s “Login Page URL”) that interfere with the post-login redirect chain.

Diagnostic steps:

1. Enable AI Engine → Settings → Dev Tools → Queries Debug. The MCP OAuth flow already logs each stage (Host-root PRM hit, /oauth/register hit, /oauth/authorize hit, etc.).
2. Tail the PHP error log while reproducing the Connect click. If no /oauth/authorize hit line appears after you log in, the post-login redirect is being intercepted — disable 2FA / cache / login-renamer plugins one at a time to isolate.
3. Try the flow from a brand-new incognito window. Half-finished session state from a previous attempt can keep the browser in a bad state.

Once you’ve confirmed which plugin is in the way, exclude /wp-json/mcp/v1/oauth/* from its interception list (most security plugins offer a URL allow-list) and the consent screen comes back.

Issue 5: You Approved, But It Still Failed

🔍 Symptoms: WP login, consent screen, and Approve all succeed in the browser, then immediately “Authorization with the MCP server failed“. The AI Engine debug log shows Authorized user ... but no POST /wp-json/mcp/v1/oauth/token entry appears in your web server access log. Claude Desktop dev tools show a 405 on claude.ai/v1/toolbox/shttp/mcp/[uuid].
💡 Cause: The user-facing consent step worked, but Anthropic’s backend POST to /oauth/token is being blocked before it reaches PHP — typically by Cloudflare’s bot defaults, a host-level WAF (ModSec on shared hosts like InMotion), or a page cache that swallowed the redirect from /authorize.
🛠️ Fix: Bypass Cloudflare’s bot challenge on /wp-json/mcp/v1/*, exclude those paths from any page cache, and ask the host to whitelist them from ModSec.

This case is the most confusing because everything visible to you works perfectly: login, consent, click Approve, all fine. The flow dies entirely server-to-server after Approve. The 405 some people see in Claude Desktop’s dev tools on claude.ai/v1/toolbox/shttp/mcp/[uuid] is Claude Desktop polling Anthropic’s own backend for connector status, not a request to your server — it’s a symptom of the upstream OAuth round-trip failing, not the cause. ☁️

You’re at step 4 of the happy-path flow: after consent, Anthropic POSTs the auth code + PKCE verifier to /wp-json/mcp/v1/oauth/token to exchange it for an access token. If that POST is dropped before reaching PHP, Anthropic never gets a token and reports failure.

Locate the blocker:

1. Tail your web server access log while reproducing the Connect click. Look for POST /wp-json/mcp/v1/oauth/token shortly after Approve. If the entry is present with a 4xx/5xx, it reached PHP and failed (PKCE mismatch, expired code, etc.). If it’s present with a 403 from the web server itself, the host’s WAF blocked it at nginx/Apache level. If it’s absent entirely, the request was dropped above the web server — almost always Cloudflare.
2. In Cloudflare, go to Security → Events and filter by URI Path containing oauth/token for your attempt window. Any “blocked” or “challenged” entries confirm Cloudflare is the layer dropping it.
3. On Apache/LiteSpeed shared hosts (InMotion, HostGator, A2, etc.), the in-WP “ModSecurity off” toggle only disables the customer-facing layer. The host’s outer ruleset is still active. Open a ticket and ask the host to pull the ModSecurity event log for /wp-json/mcp/v1/oauth/token in the same window.

Fix (in order of likelihood):

• Cloudflare bot defaults. Two separate features to check under Security → Bots:
  • Bot Fight Mode. Turn it off temporarily and retry. If that fixes it, leave it on and add a WAF Skip rule: If http.request.uri.path contains "/wp-json/mcp/v1/" then Skip → All managed rules. Anthropic’s backend identifies as an httpx-based user agent that Cloudflare often classifies as a bot.
  • Manage AI bots (newer Cloudflare feature, separate from Bot Fight Mode). This one specifically blocks AI assistant user-agents like Claude-User and GPTBot. Sneaky detail: it silently overrides custom Allow rules, so even if you’ve whitelisted Anthropic’s IP range or the MCP path, this managed rule still blocks at a higher priority. If it’s set to Block on all pages, that’s almost certainly your problem. Change it to Block on hostnames with ads (if applicable) or scope it explicitly off your MCP-serving hostname. Confirmed root cause on this support thread by @rahulmantri, 2026-05-27.
• Page cache exclusion. Even with object cache disabled, page caches can serve a stale redirect from /authorize and break the round-trip (and slow down post-auth MCP calls too). Add /wp-json/mcp/* to the “do not cache” list in every layer you have:
  • LiteSpeed Cache / WP Fastest Cache / W3 Total Cache: add to Do Not Cache URIs in plugin settings.
  • SiteGround (SG Optimizer): Caching tab → add /wp-json/mcp/* to dynamic-cache URL exclusions.
  • Cloudflare: Caching → Cache Rules → Create rule, match URI Path starts with /wp-json/mcp/, set Cache eligibility → Bypass cache.
• Host-level ModSec / WAF. Open a support ticket asking the host to whitelist /wp-json/mcp/v1/* for your domain. Be specific: the rule lives upstream of WordPress, and the in-cPanel toggle doesn’t reach it.

While you’re sorting this out, you can sidestep OAuth entirely with a Bearer Token from Claude Code or any developer tool — the Bearer flow doesn’t depend on the /oauth/token endpoint at all, and works fine even while OAuth is broken. See the next section. 🍃

Don’t Need OAuth? Use a Bearer Token Instead.

If you’re connecting from a developer tool — Claude Code, a script, n8n, Zapier, Make — you can skip OAuth entirely. No discovery, no consent, no redirects. Generate a Bearer Token in AI Engine → Settings → MCP, choose an Access Level, and pass it as a standard Authorization: Bearer header. None of the OAuth-flow issues above apply.

See our Claude Code guide for a concrete claude mcp add example, or our OpenClaw guide for the agent-side setup.

It’s Not the Plugin

If you’ve gotten this far and your MCP connection still won’t go through, take a breath: the issue is almost certainly somewhere between the public internet and the line where AI Engine’s PHP code starts running. We see the same plugin code connect first try on a clean VPS, on a Cloudflare Tunnel, on a basic shared host — and then choke on a WAF that filters by User-Agent or a managed host that swallows /.well-known/. The plugin doesn’t know any of that is happening.

The diagnostic checklist near the top of this article is the fastest way to find out which layer is interfering. If you’re still stuck after that, drop into our Discord with the output of those curls and we’ll help you trace the rest. 😺