Stale OAuth Discovery Files in Your Webroot

Royal MCP’s admin self-check detected static files at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource that advertise old OAuth endpoint URLs (under /wp-json/royal-mcp/v1/) that no longer exist. Claude.ai reads these files, tries to register against a 404, and the connection silently fails. These files were likely placed by a host-support workaround for an earlier version of Royal MCP. Removing them lets the plugin serve fresh metadata from PHP automatically — with one important exception for SiteGround and similar managed hosts. Read the carve-out below before you delete anything.

🛑 Do NOT delete these files if you’re on SiteGround, Kinsta, or a managed host that reserves /.well-known/

On some managed WordPress hosts, nginx returns a static 404 for any path under /.well-known/ before WordPress can see the request. On those hosts, the static files in this doc are the only reason OAuth discovery works at all. Deleting them will silently break your MCP handshake.

Before deleting, test whether your host has this restriction:

Rename (do not delete) both static files to .bak: oauth-authorization-server → oauth-authorization-server.bak
Save Permalinks (Settings → Permalinks → Save Changes, no structural change) to flush rewrites
From your local terminal, run: curl -i https://your-site.com/.well-known/oauth-authorization-server
If the response is JSON starting with {"issuer":"https://..."} — safe to delete the .bak files. Royal MCP is serving natively.
If the response is 404 from nginx (Server header shows nginx, Sucuri/Cloudproxy, etc.) — rename the files back immediately. Your host is intercepting /.well-known/. Static files must stay. If the Server header specifically shows Sucuri/Cloudproxy, see the dedicated Sucuri / CloudProxy fix — the path allow in your Sucuri dashboard is the permanent solution.

→ See the SiteGround-specific fix →

Confirm What’s Happening

From any terminal on your local machine, run:

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

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

Windows PowerShell: (PowerShell aliases curl to Invoke-WebRequest with different syntax — use curl.exe to bypass the alias)

curl.exe -s https://example.com/.well-known/oauth-authorization-server

You’re hitting this issue (stale static files) if the JSON response looks like:

The Telltale Signature

Status: HTTP/2 200 with Content-Type: application/json
Body: valid JSON with an issuer field pointing to your site
But authorization_endpoint, token_endpoint, or registration_endpoint contain /wp-json/royal-mcp/v1/ in the URL — the old REST-namespace layout

Current Royal MCP versions serve those endpoints at the domain root (https://your-site.com/authorize, /token, /register) — NOT under /wp-json/royal-mcp/v1/. If your JSON advertises the REST-namespace URLs, a stale static file is overriding the dynamic handler and pointing Claude.ai at endpoints that no longer exist.

If your JSON already advertises root paths

If authorization_endpoint is https://your-site.com/authorize (root path, not under /wp-json/) — you’re NOT hitting this issue. Whatever’s wrong is somewhere else. Start with the troubleshooting start-here page.

Why This Happens

In an earlier era of Royal MCP, when host-level dynamic routing to /.well-known/ paths was intermittent, the standard fix was to drop two static JSON files into the webroot:

/.well-known/oauth-authorization-server
/.well-known/oauth-protected-resource

Those files advertised the OAuth endpoints under the WordPress REST namespace (/wp-json/royal-mcp/v1/authorize, /wp-json/royal-mcp/v1/token, etc.) and satisfied Claude.ai’s discovery request even when dynamic routing hiccupped. It was the right fix for that era.

Royal MCP now serves its OAuth endpoints at the domain root (/authorize, /token, /register) so the discovery document, the OAuth client, and standard OAuth 2.0 conventions all agree. But sites that still have the old static files see them shadow the dynamic handler — nginx serves the file directly, WordPress never runs, and Claude.ai reads endpoints that no longer exist.

The plugin’s admin self-check looks for this shape and flags it. This doc is the fix.

Remove the Files

First, verify you’re NOT on a host that reserves /.well-known/ — see the danger banner at the top of this page. If the rename-test came back as JSON (not 404), proceed. If it came back as 404 from nginx, stop and follow the SiteGround-specific doc instead.

Step 1 — Access your webroot via SSH or SFTP

The two files live at:

/path/to/your/webroot/.well-known/oauth-authorization-server
/path/to/your/webroot/.well-known/oauth-protected-resource

Neither has a file extension. Both are typically 500-2000 bytes of JSON. The .well-known/ directory is at the same level as wp-admin/, wp-content/, wp-includes/. Some hosting file managers hide dotfiles by default — enable “Show hidden files” if you don’t see it.

Step 2 — Delete both files (or rename to `.bak` first if you want a rollback path)

SSH:

cd /path/to/your/webroot/.well-known/
rm oauth-authorization-server oauth-protected-resource

Safer — rename first, delete only after Claude.ai reconnects:

cd /path/to/your/webroot/.well-known/
mv oauth-authorization-server oauth-authorization-server.bak
mv oauth-protected-resource oauth-protected-resource.bak

SFTP: use your SFTP client’s delete or rename commands on the same two files.

Step 3 — Re-save Permalinks to flush WordPress rewrite rules

In WP Admin, go to Settings → Permalinks and click Save Changes. You don’t need to change the structure — just clicking Save is enough to rebuild the rewrite rules and pick up Royal MCP’s dynamic OAuth routes.

Step 4 — Re-test the discovery URL

Run the same curl from the top of this page. You should now see:

Status: HTTP/2 200
Content-Type: application/json
authorization_endpoint: https://your-site.com/authorize (root path, not under /wp-json/)
token_endpoint: https://your-site.com/token
registration_endpoint: https://your-site.com/register

If you see any URL still containing /wp-json/royal-mcp/v1/, the files weren’t removed or your CDN is caching the old response — purge your CDN cache (Cloudflare, SG Optimizer, WP Rocket, etc.) and re-test.

Verify the Fix Worked

Run the curl command from the top of this page — endpoints should now be root paths, not /wp-json/ paths
In WordPress admin, go to WP Admin → Royal MCP → Settings and save the form (this invalidates the 12-hour self-check transient so the notice refreshes immediately)
Reload any Royal MCP admin page — the “stale OAuth discovery files detected” notice should no longer appear
Reconnect Claude.ai (or whichever MCP client was failing) — the OAuth handshake should now complete without redirecting to a 404
Once you’ve confirmed Claude.ai is connecting cleanly, delete the .bak files if you renamed them in Step 2

Still Stuck? Two Support Paths

If you’ve removed the files, flushed permalinks, and Claude.ai 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.

Premium Support (paid)

For direct one-on-one help with 24-hour SLA, see Premium Support ($149/year).

Information to include (either path)

The full curl -i output for /.well-known/oauth-authorization-server AFTER removing the files
Confirmation that .well-known/ directory listing no longer contains oauth-authorization-server or oauth-protected-resource (an ls -la output is fine)
Your hosting provider name
Whether you purged CDN caches after removing the files (SG Optimizer, Cloudflare, WP Rocket, LiteSpeed, etc.)
Royal MCP version