Skip to main content

Troubleshooting

Common issues and solutions for the AI Integration 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​

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​

AI clients cannot send HTTP basic auth credentials alongside OAuth tokens.

Solution: exclude MCP endpoints from HTTP basic auth. See Stores behind HTTP basic auth for detailed instructions.

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