Skip to main content

Troubleshooting

Common issues and solutions for the AI Agent Connector extension.

Authorization issues​

"Authorization session expired" error​

The admin user was not logged in or their session expired during the OAuth flow.

Solution: log in to the Magento admin panel in the same browser and retry the authorization from the AI client.

The AI client opens a browser window, but no consent screen is shown.

Solution: ensure the admin user is logged in to the Magento admin panel in the same browser that the AI client opens for authorization. If you are logged in on a different browser or in an incognito window, the consent screen will not appear.

Need to re-authorize frequently​

The refresh token lifetime may be too short.

Solution: increase the Refresh Token Lifetime in Authentication settings. The default is 30 days (2,592,000 seconds).

Connection issues​

"RFC 7951 ERROR Not supported" (ChatGPT)​

This error appears when ChatGPT receives an HTML page (e.g., a Cloudflare challenge) instead of the expected JSON response from the MCP server.

Solution: your store's firewall or CDN is blocking automated requests. See Protected stores for step-by-step instructions on configuring Cloudflare or other protection layers.

"Error fetching OAuth configuration — does not implement OAuth" (ChatGPT)​

ChatGPT can reach the MCP server URL but cannot access the OAuth discovery endpoints (/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource).

This typically happens when only the /mcp/* paths are whitelisted in the firewall but /.well-known/* paths are still blocked.

Solution: ensure both /mcp/* and /.well-known/* paths are allowed through your firewall or CDN. See Protected stores for detailed instructions.

.well-known endpoints return 404​

The .well-known endpoints return a 404 response. This can manifest in two ways depending on the server type:

  • Nginx: returns a plain nginx 404 HTML page (<center><h1>404 Not Found</h1></center>). Magento is never reached.
  • Apache: returns the correct JSON content but with a 404 status code. Magento processes the request, but the error status is preserved.

Cause: the web server has a configuration rule that handles .well-known paths directly instead of passing them to Magento. When the requested files do not physically exist, the server returns 404.

Nginx​

A common nginx configuration that causes this:

location ^~ /.well-known/ {
    allow all;
}

The ^~ prefix tells nginx to serve files from this path directly without falling through to Magento's location / block.

Solution: either remove this block entirely, or add a try_files fallback:

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

Apache​

.htaccess rewrite rules, server-level configuration, or hosting panel auto-generated rules can bypass Magento routing for .well-known paths.

Solution: check your .htaccess files (both root and pub/) and server configuration for rules that intercept .well-known requests before they reach Magento. Remove or comment out such rules, then clear the Magento cache.

.well-known endpoints return incomplete or wrong content​

The .well-known endpoints return partial JSON, plain text, or missing Content-Type: application/json header.

Cause: static files exist in a physical .well-known directory on the filesystem. Some hosting panels, SSL certificate tools (e.g., Let's Encrypt), or manual configurations create a .well-known directory in the Magento root or pub/ folder. The web server serves these static files directly instead of routing the request to Magento.

Solution: check for and rename any physical .well-known directories that contain conflicting files:

# Check for .well-known directories
ls -la .well-known/ pub/.well-known/

# Rename to stop the web server from serving static files
mv .well-known .well-known.bak
mv pub/.well-known pub/.well-known.bak

After renaming, clear the Magento cache.

note

Renaming the .well-known directory may affect other services that depend on it (e.g., Let's Encrypt certificate renewal via /.well-known/acme-challenge/). If that is a concern, remove only the conflicting files (oauth-authorization-server and oauth-protected-resource) instead of the entire directory.

Client can't connect / connection refused​

Check the following:

  1. MCP Server is enabled: go to Stores -> Configuration -> Mirasvit Extensions -> MCP Server -> General Settings and verify Enable MCP Server is set to Yes.
  2. IP restrictions: if Allowed IP Addresses is configured in Security settings, ensure the AI client's IP is listed.
  3. Store URL: verify the MCP Server URL is correct and accessible from the AI client's network.

Store is behind HTTP basic auth or a firewall / CDN​

AI clients cannot send HTTP basic auth credentials alongside OAuth tokens. Firewalls and CDNs (such as Cloudflare) can also block automated requests.

Solution: see Protected stores for detailed instructions on configuring Cloudflare, other CDN/WAF services, and HTTP basic authentication.

Tool access issues​

"Access denied" for a tool​

The admin user's role does not have permission to use the tool.

Solution: go to System -> Permissions -> User Roles -> [Role] -> Role Resources and enable the MCP tool permissions. See Configure role permissions.

"Access to table X is restricted"​

The table is blocked by the Database Reader's security rules.

Solution: check the Database Reader configuration:

  • Verify the Table Access Mode (blacklist vs whitelist)
  • Check the Table Patterns list
  • If using whitelist mode, ensure the table is included in the patterns
  • Check role-specific patterns on the MCP Info tab of the user's role
note

Tables matching mst_mcp_* (the module's own tables) are always blocked and cannot be unblocked.

Async/bulk operations not available​

The REST API tool reports that async or bulk operations are not supported.

Solution: the Magento_WebapiAsync module must be enabled. Run:

php -f bin/magento module:enable Magento_WebapiAsync
php -f bin/magento setup:upgrade

Performance issues​

Query timeout​

SQL queries are being terminated before completing.

Solution: increase the Query Timeout in Database Reader configuration. The maximum allowed value is 300 seconds.

Token management​

Expired tokens in the grid​

Expired and revoked tokens are automatically cleaned up by a daily cron job that runs at 3:00 AM. Revoked tokens are kept for 7 days for audit purposes before being deleted.

You can also run the cleanup manually:

php -f bin/magento mirasvit:mcp:clean-expired-tokens