Troubleshooting

This page provides solutions to common issues you may encounter when using PrestaShop MCP Server.

OAuth Error: "OAuth not implemented"

Problem: When connecting your AI application to your MCP Server, you receive an error message stating "OAuth not implemented" or a similar OAuth-related error.

Solution:

This error typically occurs when the OAuth authentication flow cannot be completed. Check the following:

1. Cloudflare Configuration

If you are using Cloudflare , verify that:

• Cloudflare allows access to .well-known/* routes
• These routes are essential for the OAuth discovery process
• Make sure Cloudflare is not blocking or caching these endpoints

2. .htaccess and .htpasswd Configuration

Check your .htaccess file to ensure it allows the Authorization header:

# Allow Authorization header
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

The Authorization header is required for OAuth authentication to work properly.

If you use an .htpasswd, you need to request mcp with basic auth in yur url.

Exemple : https://username:password@your_domain.com/mcp

3. PrestaShop Maintenance Mode

Ensure your PrestaShop store is not in maintenance mode:

• Maintenance mode blocks external access to your store
• This prevents the OAuth authentication flow from completing
• Disable maintenance mode before attempting to connect your AI application

Connection Setup Error: "An error occurred during connection setup"

Problem: When attempting to connect your AI application, you receive an error message stating "Une erreur s'est produite lors de la configuration de la connexion" (An error occurred during connection setup).

Solution:

This error typically occurs when you are not logged in with the correct account authorized to access the MCP Server.

Verify Your Account

1. Go to accounts.distribution.prestashop.net
2. Check the email address you are logged in with
3. Return to PS MCP Server configuration page and navigate to the "Members" tab
4. Verify that you are logged in with the email address authorized to connect to the MCP Server

If You're Using the Wrong Account

If you discover you are logged in with the wrong account:

1. Disconnect from the current account
2. Reconnect with the correct authorized email address
3. Try connecting your AI application again

if you have and error with Accounts

1. Need to reset ps_accounts module
2. Try again the onboarding accounts step

Class Not Found Error: "class psMcpTools/LanguagesTool not found"

Problem: You encounter an error message stating "class psMcpTools/LanguagesTool not found" or similar class-related errors from the ps_mcp_tools module.

Solution:

This error occurs when PrestaShop's cache is out of sync with the module's structure. To resolve this:

Reset the ps_mcp_tools Module

1. Go to your PrestaShop back office
2. Navigate to Modules > Module Manager
3. Search for "ps_mcp_tools"
4. Click the dropdown menu next to the module
5. Select "Reset"
6. Confirm the reset action

This will reinitialize the module and clear PrestaShop's internal cache associated with it.

Connection issues

Problem: Your LLM cannot connect, discover tools, or does not seem to find an authentication server.

Solution:

This issue can occur if your server is blocking requests from LLMs. To resolve this, you need to add the following user-agents to your server's or firewall's allowlist:

• Claude Desktop: "python-httpx/0.28.1" / "Claude-User"
• ChatGPT: "Python/3.12 aiohttp/3.11.18" / "openai-mcp/1.0.0 (ChatGPT)"
• Dust: "node" / "node"
• Gemini CL: "node" / "node"

Make sure your security configuration allows requests with these user-agents.

Error when calling tools

Problem: When the AI agent calls a tool, it receives an error like "Internal error" or an unexpected error message, but you don't know what went wrong.

Solution:

When developing MCP tools, resources, or prompts, you should wrap your business logic in exception handlers to return meaningful error messages to the AI agent. PrestaShop MCP Server provides dedicated exception wrappers for this purpose:

use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpToolCallException;

try {
    // your business logic
} catch (\Exception $e) {
    throw new PsMcpToolCallException(
        'Failed to process: ' . $e->getMessage(),
        1
    );
}

Use the appropriate exception class depending on the MCP item type:

For detailed examples, see the Error handling section in the documentation.

Need help ?

If you encounter problems that are not covered in this troubleshooting guide, you can contact our support service at the following URL:

https://care-center.prestashop.com/gb/contact-us?form=support&subject=ps_mcp_server

Our support team will be happy to assist you with any issues you may be experiencing.