Skip to main content

Headless and PWA stores

On a headless or PWA store, the store's base URL (for example https://www.example.com/) is served by a separate frontend application, and Magento itself answers on another domain (for example https://api.example.com/).

By default, the AI Agent Connector extension publishes the MCP endpoint, the OAuth endpoints and the discovery documents on the store's base URL. On a headless store these addresses point to the frontend application, which does not know them, so AI clients cannot complete the connection. To fix this, set the Public Base URL to the domain where Magento answers.

1. Find the Magento domain​

  • Use the domain where Magento itself answers, usually the one your frontend uses for the Magento REST or GraphQL API.
  • Open https://api.example.com/.well-known/oauth-protected-resource (with your domain). It should return JSON, not a page of your frontend.

2. Set the Public Base URL​

  • Go to Stores -> Configuration -> Mirasvit Extensions -> MCP Server -> General Settings.
  • In Public Base URL, enter the Magento domain without /mcp, for example https://api.example.com/.
  • Click Save Config and clear the Magento cache.

There is no need to change the server configuration of the frontend domain.

3. Check the discovery documents​

Run these requests from your local computer, not from the server:

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

Every address in both responses (resource, authorization_servers, issuer, authorization_endpoint, token_endpoint, registration_endpoint) must start with https://api.example.com/.

note

If the responses still show the frontend domain after you saved the setting, a CDN may be serving an older copy. Purge the CDN cache for these two URLs. See Protected stores.

4. Connect the AI client​

  • Use the MCP Server URL from the MCP Info tab, for example https://api.example.com/mcp.
  • During sign-in, the AI client opens the Magento admin login in the browser, so the admin panel must be reachable from the browser of the admin who authorizes the connection.

If the store is behind Cloudflare, another CDN or HTTP basic authentication, also allow the MCP paths on the Magento domain. See Protected stores.