Fix: mcp_token_exchange_failed on Apache Shared Hosts

Is this your issue?

This pattern fits a specific signature. The more of these that match, the more likely it’s the right diagnosis:

• Your site is on Apache shared hosting (no Cloudflare in front, no Nginx-only setup, no LiteSpeed Web Server). Run any curl probe and you’ll see server: Apache in the response headers
• OAuth flow completes the consent screen in your browser — you click Authorize, the page redirects normally
• Right after redirect, Claude shows mcp_token_exchange_failed, “Authorization with the MCP server failed,” or “Couldn’t reach the MCP server”
• Royal MCP Activity Log shows oauth:token → ERROR rows after reproducing the failure — OR the log stays empty entirely (depending on how aggressively the host blocks)
• Royal MCP discovery (the /.well-known/ endpoint) works fine in a browser — the failure is specifically at /token, not at discovery

Confirm the block with a dual-UA curl probe

The diagnostic test: hit your OAuth discovery endpoint twice from your local machine — once with a python-httpx User-Agent (which Anthropic’s backend uses), once with a browser User-Agent. If python-httpx returns 429 while browser returns 200, this gotcha applies.

Test with python-httpx UA

Mac Terminal, Linux, Windows Command Prompt, Git Bash:

curl -sS -i -A "python-httpx/0.27.0" https://example.com/.well-known/oauth-authorization-server | head -10

Windows PowerShell:

curl.exe -sS -i -A "python-httpx/0.27.0" https://example.com/.well-known/oauth-authorization-server | Select-Object -First 10

Test with browser UA

Mac Terminal, Linux, Windows Command Prompt, Git Bash:

curl -sS -i -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0" https://example.com/.well-known/oauth-authorization-server | head -10

Windows PowerShell:

curl.exe -sS -i -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0" https://example.com/.well-known/oauth-authorization-server | Select-Object -First 10

Interpret the results

The 429 response body looks like this

Plain text body, ISO-8859-1 encoding, no JSON. The minimal “Too Many Requests” response is the signature of Apache’s default 429 handler when the managed security layer issues the block.

HTTP/1.1 429 Too Many Requests
Server: Apache
Content-Type: text/html; charset=iso-8859-1

Too Many Requests

Persistence check — rules out burst rate limiting

One 429 might just mean “you sent too many requests too fast.” A persistent 429 specifically on python-httpx, while browser UA returns 200, is a different thing entirely — it’s a UA-targeted rule that fires regardless of request rate.

To confirm it’s UA-targeted (not rate-based):

1. Run the python-httpx probe above. Note the result (likely 429)
2. Wait 60+ seconds (give any burst rate limiter time to reset)
3. Run the python-httpx probe again
4. If it’s still 429 on the second attempt while the browser UA still returns 200 on a fresh run, the block is UA-targeted and persistent

Why this breaks the OAuth /token exchange

Royal MCP’s OAuth flow uses different participants at different stages. Specifically, Anthropic’s OAuth backend uses the python-httpx HTTP client for the server-to-server /register and /token POSTs. When the host blocks that User-Agent, the OAuth flow dies at the final step:

1. Claude initiates OAuth. The user’s browser handles the redirect to /authorize — this is a browser request with a browser UA, so it passes through the host’s filter without issue
2. The user sees Royal MCP’s consent screen, clicks Authorize. Browser stuff still works. The browser redirects back to Claude with an authorization code
3. Now Claude’s backend takes over. It POSTs to /token using python-httpx to exchange the authorization code for an access token
4. Your Apache host’s managed security stack sees the python-httpx UA and returns 429 Too Many Requests — the request never reaches WordPress, never reaches Royal MCP’s /token handler
5. Claude receives 429, surfaces it to you as mcp_token_exchange_failed or “Authorization with the MCP server failed”

From your perspective, the OAuth flow looked like it was working — the consent screen rendered correctly, you clicked Authorize, the page redirected — right up until the very last step where Claude needed to actually obtain the token. That mismatch (browser stuff works, backend stuff fails) is the diagnostic fingerprint of UA-targeted blocking.

Which security stack is your host running?

You don’t need to know this to open the hosting ticket — the ticket text below works regardless. But if you want to give the host more context, here’s how the three most common Apache-shared-host security stacks identify themselves:

Don’t spend time trying to identify the exact stack yourself. The ticket text below describes the symptom in vendor-neutral language, and your host’s support team will know which specific tool they use. They’ll apply the right kind of allow rule.

Paste-ready hosting support ticket

Copy this and submit it to your hosting provider’s support team. Replace example.com with your actual domain.

Subject: User-Agent "python-httpx" receiving 429 Too Many Requests on
my domain — need allowlist or path exclusion

Hi support,

My WordPress site at example.com runs a plugin (Royal MCP) that needs
to accept OAuth requests from Anthropic's backend service. Anthropic's
OAuth client identifies itself with User-Agent "python-httpx".

Your managed security stack is currently returning 429 Too Many Requests
for any request with that User-Agent, even single, non-bursty requests
made 60+ seconds apart. Browser User-Agents pass through normally.

This is reproducible from any external IP:

    curl -A "python-httpx/0.27.0" \
        https://example.com/.well-known/oauth-authorization-server

returns 429 Too Many Requests, while

    curl -A "Mozilla/5.0" \
        https://example.com/.well-known/oauth-authorization-server

returns 200 OK with the expected JSON.

The 429 persists across multiple requests minutes apart, so this is
NOT a burst rate limit — it's a User-Agent-targeted block (likely
an Imunify360 rule, a mod_security UA rule, or a similar managed
bot-defense rule).

Could you please either:

1. Whitelist User-Agent matching python-httpx/* on this domain, OR

2. Exclude these specific paths from User-Agent-based filtering:
   - /register
   - /authorize
   - /token
   - /.well-known/oauth-authorization-server
   - /.well-known/oauth-protected-resource
   - /wp-json/royal-mcp/v1/mcp

Option 1 is preferable as it allows the plugin's authentication to
work site-wide. Option 2 is an acceptable fallback if a domain-wide
UA allowlist isn't available.

After you apply the change, I'll re-run the curl test to confirm
the block is cleared. Happy to provide any additional logs or
diagnostic info you need.

Thanks!

Verify the fix worked

After your host confirms the change has been applied, re-run the dual-UA probe:

curl -sS -i -A "python-httpx/0.27.0" https://example.com/.well-known/oauth-authorization-server | head -5

Expected output:

HTTP/1.1 200 OK
Server: Apache
Content-Type: application/json; charset=utf-8

If you now see 200 OK on both browser UA and python-httpx UA, the block is cleared. Continue to the reconnection step below.

If the python-httpx probe still returns 429:

• Wait 15–30 minutes — some managed security platforms cache rules at the edge and take time to propagate
• If still failing after 30 minutes, reply to your hosting ticket. The host’s support team may have applied the allow rule at the wrong scope (account-wide instead of domain-specific, or vice versa) — common when the rule UI is confusing
• Share the failing curl output with the host as proof the change didn’t take effect

Reconnect Claude with fresh OAuth state

Once curl confirms python-httpx now returns 200, Claude still has stale connection state from the failed attempts. Wipe and reconnect:

1. In Claude (web or Desktop), delete the existing Royal MCP connector entirely
2. In WordPress, go to Royal MCP → Settings and click Reset OAuth State (button available in Royal MCP 1.4.17+)
3. Wait 30 seconds for any caching layers to settle
4. Re-add the connector in Claude with only the server URL (e.g. https://example.com/wp-json/royal-mcp/v1/mcp). Leave Advanced Settings completely empty
5. Complete the OAuth flow when prompted — should succeed this time

Still Stuck? Two Support Paths

If you’ve worked through the steps above and your connection still fails:

Community Support (free) — wp.org Plugin Forum

Post a new thread at wordpress.org/support/plugin/royal-mcp/. The Royal Plugins team monitors the forum regularly and community members often help disambiguate issues faster than email could. Include the diagnostic info listed below in your post.

Premium Support (paid) — direct one-on-one help

For priority response (24-hour SLA) and hands-on diagnostic help, our Premium Support tier is $149/year. Includes a 30-day “if it breaks again” follow-up window on every resolved ticket.

This is part of a family of UA-targeted blocks

The Apache 429 block is one of three closely related patterns. All three break Royal MCP OAuth in the same way (UA-discrimination at the edge, OAuth dies at /token) but on different host families with different status codes. Worth knowing in case you migrate hosts and hit a sibling pattern later, or in case your initial diagnosis is wrong:

All three resolve the same way: open a hosting support ticket asking for a UA whitelist or path-based exclusion for the OAuth endpoints. Only the status code, host family, and which support team you contact differ.

Related host-side OAuth failures

If the curl probe shows browser UA returning 200 but python-httpx returning something other than 429, try these adjacent failure modes: