Skip to Main
schemawp
Back to docs

MCP Connection Fails: /.well-known/ URL Returns 404

When an MCP client (like Claude) connects to your site, it first fetches two discovery documents at standardized paths to learn how to authenticate:

  • https://yoursite.com/.well-known/oauth-authorization-server
  • https://yoursite.com/.well-known/oauth-protected-resource

These paths are defined by internet standards (RFC 8414 and RFC 9728) and are not configurable. SchemaWP Pro serves them through WordPress, but some server or hosting environments block requests to /.well-known/ paths before WordPress ever sees them, resulting in a 404.

Step 1 — Confirm where the 404 is coming from

Open this URL in your browser (replace yoursite.com with your actual domain):

https://yoursite.com/wp-json/scwp-acss-mcp/v1/.well-known/oauth-authorization-server
  • Returns JSON — WordPress and the plugin are working correctly. The problem is at your web server, host, or CDN layer (continue to Step 2).
  • Also 404s or returns an error — WordPress itself is not routing correctly (continue to Step 3).

Step 2 — Web server / hosting / CDN fixes

This is the most common cause. The server intercepts /.well-known/ paths before handing the request to WordPress.

Apache (self-hosted)

Ensure your .htaccess file in the WordPress root contains the standard WordPress rewrite block. Also verify your Apache virtual host has AllowOverride All (or at minimum AllowOverride FileInfo) set for your document root, otherwise .htaccess rules are ignored.

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

Nginx (self-hosted)

Many Nginx configs include a rule that denies all dotfile paths (location ~ /.). Add explicit location blocks before that deny rule:

location = /.well-known/oauth-authorization-server {
    try_files $uri /index.php?$args;
}
location = /.well-known/oauth-protected-resource {
    try_files $uri /index.php?$args;
}

Also check that your main location / block uses try_files $uri $uri/ /index.php?$args; — without this, WordPress cannot receive requests for non-existent files.

Nginx with ACME / Let’s Encrypt

If you have a block for SSL certificate renewals (location ^~ /.well-known/acme-challenge/ { ... }), it should not interfere — but verify no broader location ^~ /.well-known/ rule is present that would shadow the OAuth paths.

Cloudflare or other CDN

A “Cache Everything” page rule or WAF rule applied to /.well-known/* can cache a 404 or block the request entirely. Create a bypass rule in your Cloudflare dashboard:

  • If URI path contains /.well-known/oauth- → Cache Level: Bypass
  • Disable any WAF rules that block /.well-known/ on your domain.

Managed WordPress hosts

Many managed hosts (WP Engine, Kinsta, Pantheon, Cloudways, SiteGround, etc.) have edge-layer rules that intercept /.well-known/ paths. Contact your host’s support and ask them to allow /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource to pass through to PHP/WordPress.

Step 3 — WordPress-level fixes

If the /wp-json/ URL in Step 1 also failed, the issue is within WordPress itself.

Check your permalink structure

Go to Settings → Permalinks. If it is set to “Plain”, WordPress URL routing is disabled and no custom paths will work. Switch to any other option (e.g. “Post name”) and click Save Changes — this regenerates your .htaccess or Nginx config.

Check if the REST API is disabled

Some security plugins (Wordfence, iThemes Security, Perfmatters) have an option to disable the WordPress REST API for logged-out users or entirely. The MCP endpoints require REST API access. Check your security plugin settings and whitelist the scwp-acss-mcp/v1 namespace if needed.

Check if SchemaWP Pro is active

Confirm the plugin is active under Plugins → Installed Plugins. If it was recently updated or deactivated, reactivate it and try again.

Step 4 — Still stuck?

Collect the following and send it to our support team:

  1. The response from: https://yoursite.com/wp-json/scwp-acss-mcp/v1/.well-known/oauth-authorization-server
  2. Your hosting provider and server type (Apache / Nginx / LiteSpeed)
  3. Whether a CDN (Cloudflare, etc.) is in front of your site
  4. A list of active security plugins

Read also