Skip to main content

Hypernode hosting

Hypernode is a Magento-specific managed hosting platform whose default nginx configuration intercepts /.well-known/* paths before they reach Magento. This page covers the Hypernode-specific configuration required to make the MCP module's OAuth discovery and /mcp/* endpoints reachable.

The general background on why .well-known endpoints return 404 is covered in Troubleshooting → .well-known endpoints return 404. The endpoints that must be reachable are listed in Protected stores → Required endpoints.

Configuration​

The required configuration depends on whether the environment has Varnish enabled (typical for production) or not.

With Varnish​

Two files are needed because the same .well-known interception happens at both the public-facing nginx layer and the backend nginx layer behind Varnish.

File 1 — /data/web/nginx/server.wellknown (public-facing layer, forwards to Varnish without rewriting the URL):

location ^~ /.well-known/ {
    proxy_pass            http://127.0.0.1:6081;
    proxy_set_header      Host $host;
    proxy_set_header      X-Real-IP $remote_addr;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $scheme;
    proxy_set_header      X-Forwarded-Port $server_port;
}

location ^~ /mcp {
    proxy_pass            http://127.0.0.1:6081;
    proxy_set_header      Host $host;
    proxy_set_header      X-Real-IP $remote_addr;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $scheme;
    proxy_set_header      X-Forwarded-Port $server_port;
}

File 2 — /data/web/nginx/varnish.wellknown.conf (backend layer behind Varnish, routes to Magento via fastcgi):

location ^~ /.well-known/ {
    try_files $uri /index.php?$args;
}

location ^~ /mcp {
    try_files $uri /index.php?$args;
}
Why proxy_pass and not try_files at the public-facing layer

Using try_files /index.php$is_args$args; at the public-facing layer rewrites the URL to /index.php before Varnish receives it. Magento then sees a request to /index.php and 301-redirects to the homepage. The proxy_pass form forwards the original URL to Varnish unchanged, and the rewrite happens at the backend layer where it ends at fastcgi_pass (which preserves REQUEST_URI).

Without Varnish​

Only the public-facing layer needs the override. Create /data/web/nginx/server.wellknown with:

location ^~ /.well-known/ {
    try_files /index.php$is_args$args;
}

location ^~ /mcp {
    try_files /index.php$is_args$args;
}

varnish.wellknown.conf is not required.

Apply and verify​

Hypernode's nginx_config_reloader watches /data/web/nginx/ and automatically reloads nginx after the files are saved — no manual restart is needed. Syntax errors are written to /data/web/nginx/nginx_error_output.

To force a reload manually:

hypernode-servicectl restart nginx

Verify the OAuth discovery endpoints return JSON:

curl -skI https://your-store.com/.well-known/oauth-authorization-server
curl -skI https://your-store.com/.well-known/oauth-protected-resource

Both should return HTTP/2 200 with content-type: application/json.

OAuth discovery fails with HTTP 429​

Hypernode's built-in rate limiting and bot protection can block requests from AI clients based on the user agent. When blocked, the server returns HTTP 429 (Too Many Requests) and OAuth discovery fails.

Symptoms:

  • The MCP client cannot connect.
  • Server access logs show requests to incorrect OAuth endpoints (e.g., /register instead of /mcp/oauth/register).
  • No requests to /.well-known/ paths appear in the application logs.

Diagnose:

grep '.well-known' /var/log/nginx/access.log

Look for entries with status 429 and note the user_agent value.

Solution: whitelist the blocked user agent in Hypernode's bot protection settings via the Hypernode control panel. For Claude clients, the relevant user agents are typically Claude-User, python-httpx/*, and claude-code/*.

Alternatively, disable rate limiting for the affected paths by adding limit_req off; to the location blocks shown above.

Multi-store note​

On a multi-store Magento install, OAuth discovery returns endpoint URLs (issuer, authorization_endpoint, token_endpoint, etc.) pointing to the default store's base URL, regardless of which domain the client connects to. The OAuth flow and MCP traffic complete successfully because both terminate at the same backend — the redirect is by design and does not affect functionality.