Symptoms

You’re hitting this specific issue if all of the following are true:

The Telltale Signs

Your Royal MCP endpoint URL (shown in WP Admin → Royal MCP → Settings) contains ?rest_route=/royal-mcp/v1/mcp — the ?rest_route= query-string format is the fallback WordPress uses when Plain permalinks are set
Claude fails to connect (shows “Couldn’t reach the MCP server” or similar with an ofid_… reference code), and the OAuth consent screen never appears
WP Admin shows a Royal MCP admin notice about needing pretty permalinks (Royal MCP 1.4.36 and later auto-detect this and surface the notice)
Direct browser test of https://yoursite.com/.well-known/oauth-authorization-server returns a 404 or your theme’s homepage instead of a JSON response

Why ?rest_route= URLs are a red flag for MCP

Legacy WordPress REST API URLs use the query-string format ?rest_route=/wp/v2/posts when rewrite rules are disabled (Plain permalinks). That works fine for the REST API in general — but it does NOT work for OAuth discovery endpoints like /.well-known/oauth-authorization-server, which MUST be reachable at the domain root per RFC 8414. Since rewrite rules power that domain-root routing, no rewrite rules means no OAuth discovery.

The Fix — 30 Seconds in Settings

Open WordPress admin → Settings → Permalinks

The direct URL is https://yoursite.com/wp-admin/options-permalink.php. You need manage_options capability (Administrator role by default) to change this setting.

Select any option EXCEPT “Plain”

Recommended: Post name — the WordPress-community default and the most SEO-friendly option. Your URLs will look like https://yoursite.com/sample-post/.

Other options that also work (all non-Plain settings restore rewrite rules): Day and name, Month and name, Numeric, Custom Structure.

Click Save Changes

WordPress will regenerate rewrite rules automatically. No .htaccess edit or server-restart needed on most standard hosting setups. If you’re on nginx and get a warning about needing to update nginx rules manually, ask your hosting provider — but this is uncommon; most nginx-hosted WordPress installs work correctly after the settings change alone.

Verify Royal MCP’s endpoint URL updated

Go back to WP Admin → Royal MCP → Settings and confirm the MCP endpoint URL now shows the clean format:

https://yoursite.com/wp-json/royal-mcp/v1/mcp

Not the old query-string format:

https://yoursite.com/?rest_route=/royal-mcp/v1/mcp

Retry the Claude connection

In Claude, delete the existing Royal MCP connector if present (it may have cached the old URL), wait 30 seconds, then re-add it fresh with the new clean URL. Complete the OAuth consent screen. The connection should complete normally.

Sanity-check: your OAuth discovery URL should now return JSON

Before retrying Claude, test the discovery URL directly in your browser or with curl:

curl https://yoursite.com/.well-known/oauth-authorization-server

You should see a JSON response with fields like issuer, authorization_endpoint, token_endpoint. If instead you see a 404, your theme’s homepage, or any HTML page, permalinks may still be Plain (double-check Step 2) — or something else (Imunify360, SiteGround’s nginx, etc.) is also blocking the URL. See “Related issues” below.

Why Does This Happen?

WordPress ships with five permalink options: Plain, Day and name, Month and name, Numeric, Post name, and Custom Structure. Every option except “Plain” instructs WordPress to generate URL rewrite rules that map clean URLs (like /sample-post/) to internal WordPress query variables.

Royal MCP’s OAuth 2.0 endpoints depend on these rewrite rules:

/.well-known/oauth-authorization-server — RFC 8414 OAuth server metadata, required for MCP client discovery
/.well-known/oauth-protected-resource — RFC 9728 protected resource metadata
/authorize — OAuth authorization endpoint
/token — OAuth token exchange endpoint
/register — RFC 7591 dynamic client registration endpoint

All five must be served at the domain root (not under /wp-json/) because that’s where OAuth clients look for them per the RFC specifications. Royal MCP registers rewrite rules that map these clean paths to internal WordPress handlers — but on Plain permalinks, those rewrite rules don’t fire, and the URLs return 404 (or fall through to your theme’s homepage, depending on your web server).

The Royal MCP REST endpoint itself works fine on Plain permalinks — it’s reachable at ?rest_route=/royal-mcp/v1/mcp via the WordPress REST API’s legacy query-string fallback. But that’s not enough by itself; OAuth handshake requires the domain-root URLs, and Claude gives up when it can’t find them.

Going FROM Plain won’t break any existing URLs

If your permalinks are currently set to Plain, every internal WordPress URL on your site is already in the query-string format — there are no existing pretty URLs that could break. Changing to Post name (or any non-Plain option) instructs WordPress to start generating clean URLs going forward, activates rewrite rules, and Royal MCP’s OAuth endpoints immediately become reachable. (Note: switching between two different pretty structures — e.g. Post name to Numeric — is a different scenario and may affect existing links; not relevant here.)

What Doesn’t Work

Manually using the ?rest_route=/royal-mcp/v1/mcp URL as your MCP endpoint alone. Yes, the endpoint works — but OAuth discovery is a SEPARATE URL (/.well-known/oauth-authorization-server), and that one still requires rewrite rules. Fixing only the MCP endpoint URL doesn’t fix the OAuth handshake.
Adding custom .htaccess rules. If your permalinks are Plain, WordPress isn’t generating any rewrite rules at all — adding your own manual rules won’t help because WordPress won’t interpret them. The permalink setting change is what triggers WordPress to write and honor the rules.
Uninstalling & reinstalling Royal MCP. The plugin is fine — the rewrite-rules infrastructure it needs simply isn’t present on Plain permalinks.
Any Cloudflare, cache, or security-plugin change. Those layers are downstream of WordPress URL routing. They can’t help if WordPress itself isn’t routing the URLs.

What Royal MCP 1.4.36 Already Does for You

Royal MCP 1.4.36 detects this configuration automatically. When the plugin’s Well_Known_Notice check runs (during admin page loads) and sees the permalink_structure WordPress option is set to Plain (empty string), Royal MCP surfaces a dismissible admin notice on the Plugins screen and Royal MCP settings linking directly to WP Admin → Settings → Permalinks and to this article.

So future customers on Plain permalinks land here from inside their own WordPress admin instead of having to search for “Royal MCP OAuth discovery 404” and stumble across the diagnosis. The plugin can’t auto-change the permalink setting for you — changing that setting has broader implications (URL structure across the whole site) that require a customer’s explicit decision — but the notice makes the fix a two-click operation from the admin.

Related Issues You Might Also Be Hitting

If you changed permalinks to Post name (or another non-Plain option) and OAuth discovery STILL fails, an additional layer is likely blocking the URLs. Check these:

Imunify360 blocking /wp-json/* and /.well-known/*

Curl returns HTTP 200 with a JSON body containing “Access denied by Imunify360 bot-protection.” Common on shared cPanel + CloudLinux hosts.

See: Imunify360 Blocks Royal MCP →

SiteGround nginx 404 on /.well-known/

Curl returns a tiny nginx 404 (no X-Httpd header). SiteGround’s nginx layer serves 404 for anything under /.well-known/ that doesn’t physically exist, without falling through to WordPress.

See: SiteGround well-known 404 fix →

OAuth discovery returns HTML instead of JSON

A membership plugin or theme template intercepts the request and serves a login page or homepage at HTTP 200.

See: OAuth discovery HTML fix →

Still Stuck? Two Support Paths

If you’ve changed permalinks and Claude still can’t connect:

Community Support (free) — wp.org Plugin Forum

Post a new thread at wordpress.org/support/plugin/royal-mcp/. Include the diagnostic info listed below.

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

For priority response (24-hour SLA), our Premium Support tier is $149/year.

Information to include in your post or ticket

Current permalink setting (screenshot of Settings → Permalinks confirming you selected a non-Plain option)
Your Royal MCP endpoint URL from WP Admin → Royal MCP → Settings (should be the clean /wp-json/royal-mcp/v1/mcp format, not ?rest_route=)
Curl output for curl -i https://yoursite.com/.well-known/oauth-authorization-server (should return JSON; if it returns 404 or HTML, that’s the additional layer blocking the URL)
Your hosting provider — helps cross-reference against known-good configurations
Royal MCP version from WP Admin → Plugins

Plain Permalinks Break Royal MCP OAuth Discovery