MCP for PrestaShop: Connect Your Store to AI Agents

Imagine for a moment: you ask Claude “Find me the top 10 best-selling products this month and generate a promotional report”. A few seconds later, you receive a complete document with statistics, recommendations, and merchandising suggestions. Science fiction? No, this is exactly what ps_mcp_server enables—the PrestaShop module that connects your store to AI agents via the Model Context Protocol (MCP).

In my 15 years of e-commerce development practice, I’ve rarely seen a technology as promising for intelligent automation. MCP transforms your PrestaShop into a true conversational API, where AI agents become genuine business assistants capable of executing complex tasks.

Introduction

The Model Context Protocol is not just another API. It’s a stateful protocol designed specifically for AI-system interactions. Unlike classic REST APIs where each request is isolated, MCP maintains a conversational context: your AI agent “remembers” language preferences, viewed products, and previous searches.

ps_mcp_server is the bridge between this revolutionary protocol and the PrestaShop ecosystem. Developed for PHP 8.1+ and PrestaShop 8+, this module exposes your business logic as tools that LLMs (Large Language Models) can discover and use automatically.

The advantage? You define your business tools once, and all MCP-compatible AI agents (Claude, ChatGPT, Gemini, Dust) can use them. No need to develop specific integrations for each AI platform.

Why MCP is a Game-Changer for PrestaShop

A Protocol Designed for AI

MCP solves a fundamental problem: how to enable AIs to interact with complex business systems reliably? Traditional approaches (scraping, generic APIs) fail because they don’t provide the structured context that LLMs need.

With MCP, each exposed tool has intrinsic documentation that the AI agent reads and understands. Think of it as a self-documented API optimized for intelligent machines. The agent knows precisely which parameters to send, what responses to expect, and how to combine multiple tools for complex workflows.

Architecture of the ps_mcp_server Module

The module integrates three essential components:

The embedded MCP server that listens to AI agent requests, automatically discovers available tools via PHP attributes, and maintains session state.

The integrated MCP client necessary for STDIO (Standard Input/Output) communication, particularly useful for development and standalone modules.

The automatic discovery system that scans your modules for classes annotated with #[McpTool], eliminating tedious manual configuration.

This architecture ensures your MCP server stays synchronized with your business code without additional maintenance.

Installation and Initial Configuration

Technical Prerequisites

Before starting, ensure you have a compatible environment:

• PrestaShop 8.x minimum - The module leverages modern PrestaShop features and requires this version to ensure stability.
• PHP 8.1 or higher - PHP attributes (modern annotations) are at the core of the tool discovery system. PHP 8.1 also introduces crucial performance improvements for resource-intensive AI operations.
• An MCP-compatible client - To test and use your server: Claude Desktop, Dust, Gemini CLI, or MCP Inspector (debugging tool without AI).

File Structure

The module automatically creates a .mcp folder at his own root containing:

• .cache - Tool discovery cache to optimize performance. Delete it to force a new scan.
• .logs - Detailed log files (when “Enable logs” is activated in configuration). Essential for debugging AI interactions.

This organization maintains a clear separation between MCP configuration and your standard PrestaShop code.

Declaring Your Module MCP-Compatible

The isMcpCompliant() Method

Before exposing tools, you must tell ps_mcp_server that your module supports MCP. This explicit declaration avoids unnecessary scans and allows fine-grained management of AI-ready modules.

Simply add this method to your module’s main class:

<?php

class Ps_MySuperModule extends Module
{
    /**
     * Declares this module as MCP-compatible
     *
     * This method allows ps_mcp_server to automatically
     * discover tools defined in this module
     * via PHP attributes #[McpTool]
     */
    public function isMcpCompliant()
    {
        return true;
    }
}

That’s it! Once this method is present, the ps_mcp_server module will automatically scan your src/Mcp/Tools folder for classes containing MCP tools.

Why This Approach?

This opt-in method has several advantages: it avoids scanning all installed modules (performance), allows progressive activation (you choose when to make a module MCP-ready), and facilitates debugging (clear logs on scanned modules).

In the module logs (.mcp/.logs), you’ll see your module appear in the list of discovered MCP-compliant modules, with the number of tools found.

Creating Your First MCP Tool

Anatomy of an MCP Tool

An MCP tool is a PHP method enriched with attributes that describe its behavior for AI agents. Let’s create a concrete example: a product search tool by name.

Create a src/Mcp/Tools/ProductSearchTool.php file in your module:

<?php

namespace PrestaShop\Module\MySuperModule\Mcp\Tools;

use PhpMcp\Server\Attributes\McpTool;
use PhpMcp\Server\Attributes\Schema;
use Product;

class ProductSearchTool
{
    /**
     * Search products by name with fuzzy matching
     *
     * @param string $searchTerms Search terms separated by semicolons
     * @param int $langId Language ID (default: preferred language)
     * @param int $limit Maximum number of results (default: 10)
     * @return array List of found products with details
     */
    #[McpTool(
        name: 'search_product_by_name',
        description: 'Search products in store by name only. Uses fuzzy matching. Results sorted by relevance.'
    )]
    #[Schema(
        properties: [
            'searchTerms' => [
                'type' => 'string',
                'description' => 'Search terms. Multiple terms possible separated by semicolons.'
            ],
            'langId' => [
                'type' => 'integer',
                'description' => 'Search language. Default: preferred context language.',
                'default' => 1
            ],
            'limit' => [
                'type' => 'integer',
                'description' => 'Maximum number of results to return.',
                'default' => 10
            ]
        ],
        required: ['searchTerms']
    )]
    public function searchProducts(string $searchTerms, int $langId = 1, int $limit = 10): array
    {
        // Split multiple terms
        $terms = explode(';', $searchTerms);

        // PrestaShop fuzzy search logic
        $results = Product::searchByName($langId, $terms[0]);

        // Limit results
        return array_slice($results, 0, $limit);
    }
}

Dissecting the Attributes

#[McpTool] defines your tool’s identity:

• The name must be unique, descriptive, and in snake_case. This is the name the AI agent will use to call your tool.
• The description is crucial: it guides the agent on when and how to use the tool. Be explicit about use cases, limitations, and result sorting.

#[Schema] specifies accepted parameters:

• properties lists each parameter with its type, detailed description, and optionally a default value.
• required indicates which parameters are mandatory. The AI agent will receive a clear error if it forgets a required parameter.

Input Validation

MCP automatically validates types through the Schema, but always add sanity checks in your code:

public function searchProducts(string $searchTerms, int $langId = 1, int $limit = 10): array
{
    // Basic validation
    if (empty(trim($searchTerms))) {
        throw new \InvalidArgumentException('Search terms cannot be empty');
    }

    // Reasonable limit to avoid overload
    if ($limit > 100) {
        $limit = 100;
    }

    // Check existing language
    if (!Language::getLanguage($langId)) {
        throw new \InvalidArgumentException("Invalid language ID {$langId}");
    }

    // Your business logic...
}

AI agents are known to “hallucinate” values. These validations protect your system against erratic behavior.

Principles of Effective Tool Design

Explicit and Concise Wording

Your tool descriptions make all the difference. An AI agent reads these descriptions to decide which tool to use and how to use it. Here’s an example transformation:

❌ Vague description:

description: 'Retrieves products'

✅ Optimized description:

description: 'Search products by name only. Fuzzy matching enabled. Results sorted by relevance. For search by category or price, use search_product_advanced.'

The optimized version specifies the search type, behavior (fuzzy matching), result sorting, and even guides toward an alternative tool for other needs.

Consistent Vocabulary

Use the same terminology across all your tools. If you call a parameter langId in one tool, don’t call it languageId in another. This consistency helps agents make connections between tools and plan complex workflows.

Example of unified vocabulary:

// ✅ Consistent across all tools
'langId' => 'Language ID'
'limit' => 'Maximum number of results'
'offset' => 'Starting point for pagination'

// ❌ Inconsistent
Tool 1: 'langId', 'maxResults', 'start'
Tool 2: 'languageId', 'limit', 'offset'

Limiting Query Complexity

Protect your server against overly demanding queries. A poorly configured AI agent could request 10,000 products at once, overloading your database.

#[Schema(
    properties: [
        'limit' => [
            'type' => 'integer',
            'description' => 'Maximum number of results (max: 100)',
            'default' => 10,
            'maximum' => 100  // Technical limit
        ]
    ]
)]
public function searchProducts(string $searchTerms, int $limit = 10): array
{
    // Double-check just in case
    $limit = min($limit, 100);

    // Search logic with applied limit...
}

This defensive approach ensures stable performance even with poorly optimized AI agents.

State Management with MCP

Stateful Protocol: The MCP Advantage

Unlike traditional REST APIs, MCP is stateful: the server maintains context for each connected client. This characteristic transforms the user experience.

Imagine an AI agent helping a French-speaking customer. Instead of specifying langId: 2 on every tool call, the agent can store this preference in session state:

// First call: agent detects preferred language
$context->setState('preferred_lang', 2);

// Subsequent calls: automatic use
$langId = $context->getState('preferred_lang', 1);

State Use Cases

• Personalization: preferred language, currency, shipping country.
• Search history: remember viewed products to refine recommendations.
• Multi-step workflow: an agent can progressively build a cart by memorizing previous choices.
• Query optimization: cache frequently accessed data in session.

State isn’t mandatory, but it makes interaction much smoother and more natural for the end user.

HTTP Connection for Production

HTTP Transport Advantages

In production, HTTP becomes the preferred transport for several reasons:

• Universal compatibility: all MCP clients (Claude, ChatGPT, Dust, Gemini) support HTTP.
• Scalability: an HTTP server can handle hundreds of simultaneous connections.
• Security: token authentication, HTTPS encryption, fine-grained permission management.
• Monitoring: centralized logs, performance metrics, anomaly detection.

Configuration for Different Clients

Claude Desktop requires a local JSON configuration pointing to your server with the token:

{
  "mcpServers": {
    "prestashop-shop": {
      "url": "https://your-store.com/modules/ps_mcp_server/endpoint",
      "token": "your-secure-token"
    }
  }
}

Dust and Gemini CLI currently offer the simplest connection: simple token without OAuth. Recommended for your first production tests.

ChatGPT and other clients will require OAuth2 in future module versions (V1). For now, favor Dust or Gemini for production.

Security Considerations

In HTTP, security is paramount:

• Always use HTTPS in production, never plain HTTP.
• Renew tokens regularly (recommended: every 30 days).
• Enable logs to monitor suspicious tool calls.
• Implement rate limits to prevent abuse (next module version).

Debug and Monitoring

Log Files

The .mcp/.logs folder contains valuable information for debugging:

• mcp-server.log: all received requests, called tools, encountered errors.
• tool-discovery.log: module scan results, discovered tools, annotation errors.
• session.log: session creation/destruction, state management per client.

Enable logs in module configuration during development, disable them in production for performance reasons (unless diagnosing an issue).

MCP Inspector: Your Best Ally

MCP Inspector is a graphical debugging tool that connects to your server without involving AI. Perfect for:

• Verifying your tools are correctly discovered.
• Testing tool calls with different parameters.
• Observing responses without the unpredictability of an AI agent.
• Validating your JSON schema before connecting a real AI client.

Install it via npm and point it to your MCP server. You’ll instantly see all your tools listed with complete documentation.

Common Errors and Solutions

“No tools discovered”: verify that isMcpCompliant() returns true, that your classes are in src/Mcp/Tools, and that #[McpTool] attributes are correctly imported.

“Invalid token”: regenerate a token in module configuration, copy it exactly without extra spaces.

“Connection timeout”: in STDIO mode, verify the PHP process has execution rights. In HTTP, check your web server configuration and firewall rules.

Best Practices for AI Agent Tools

Intrinsic Documentation

Your tool descriptions are read by machines, not humans. Optimize them for LLM understanding:

• Be precise about formats: “Date in YYYY-MM-DD format” rather than “Date”.
• Indicate limitations: “Maximum 100 results” in both description AND schema.
• Guide toward alternatives: “For advanced search, use search_product_advanced”.
• Explain sorting: “Results sorted by decreasing relevance”.

Permission Management

Even though MCP handles authentication, implement permission checks in your tools:

public function updateProduct(int $productId, array $data): array
{
    // Check rights of user associated with session
    if (!$this->context->employee->hasAccess('AdminProducts', 'edit')) {
        throw new \PrestaShopException('Insufficient permissions to modify products');
    }

    // Data validation
    $this->validateProductData($data);

    // Secure update
    $product = new Product($productId);
    $product->hydrate($data);
    $product->save();

    return ['success' => true, 'id' => $productId];
}

This defense-in-depth approach: even if a token is compromised, standard PrestaShop permissions remain enforced.

Infinite Loop Prevention

AI agents can sometimes fall into loops: calling the same tool again and again with similar parameters. Detect these behaviors:

private function detectLoop(string $toolName, array $params): void
{
    $sessionHistory = $this->context->getState('tool_history', []);

    // Add current call
    $sessionHistory[] = [
        'tool' => $toolName,
        'params' => $params,
        'timestamp' => time()
    ];

    // Keep last 10 calls
    $sessionHistory = array_slice($sessionHistory, -10);

    // Detect 5 identical calls
    $similarCalls = array_filter($sessionHistory, function($call) use ($toolName, $params) {
        return $call['tool'] === $toolName &&
               json_encode($call['params']) === json_encode($params);
    });

    if (count($similarCalls) >= 5) {
        throw new \RuntimeException("Loop behavior detected: tool {$toolName} called 5 times with identical parameters");
    }

    $this->context->setState('tool_history', $sessionHistory);
}

This simple protection avoids catastrophic scenarios where a faulty agent overloads your server.

Complete Example: Boilerplate Module

Recommended Structure

To get started quickly, use the ps_mcp_boilerplate repository that provides a complete structure:

ps_my_mcp_module/
├── ps_my_mcp_module.php          # Main class with isMcpCompliant()
├── src/
│   └── Mcp/
│       └── Tools/
│           ├── ProductSearchTool.php
│           ├── OrderManagementTool.php
│           └── CustomerAnalyticsTool.php
├── config/
│   └── services.yml               # Symfony configuration for DI
└── README.md

Complete Tool Implementation

Here’s a real example of an order management tool:

<?php

namespace PrestaShop\Module\MyMcpModule\Mcp\Tools;

use PhpMcp\Server\Attributes\McpTool;
use PhpMcp\Server\Attributes\Schema;
use Order;
use Context;

class OrderManagementTool
{
    private Context $context;

    public function __construct(Context $context)
    {
        $this->context = $context;
    }

    #[McpTool(
        name: 'get_recent_orders',
        description: 'Retrieves recent orders with optional filters. Returns ID, customer, amount, status. Sorted by descending date.'
    )]
    #[Schema(
        properties: [
            'limit' => [
                'type' => 'integer',
                'description' => 'Number of orders to return (max: 50)',
                'default' => 10
            ],
            'status' => [
                'type' => 'string',
                'description' => 'Filter by status: pending, paid, shipped, delivered, cancelled',
                'default' => null
            ],
            'days' => [
                'type' => 'integer',
                'description' => 'Orders from last N days (max: 90)',
                'default' => 7
            ]
        ]
    )]
    public function getRecentOrders(
        int $limit = 10,
        ?string $status = null,
        int $days = 7
    ): array {
        // Validations
        $limit = min($limit, 50);
        $days = min($days, 90);

        // Query construction
        $dateFrom = date('Y-m-d', strtotime("-{$days} days"));

        $orders = Order::getOrdersWithInformations(
            $limit,
            0, // offset
            ['date_add', 'DESC']
        );

        // Filter by status if specified
        if ($status) {
            $orders = array_filter($orders, function($order) use ($status) {
                return strtolower($order['order_state']) === strtolower($status);
            });
        }

        // Format results
        return array_map(function($order) {
            return [
                'id' => $order['id_order'],
                'reference' => $order['reference'],
                'customer' => [
                    'id' => $order['id_customer'],
                    'name' => $order['customer_name'],
                    'email' => $order['customer_email']
                ],
                'total' => (float) $order['total_paid'],
                'currency' => $order['currency'],
                'status' => $order['order_state'],
                'date' => $order['date_add']
            ];
        }, $orders);
    }
}

This tool illustrates all best practices: strict validation, clear description, strong typing, structured result formatting.

References and Resources

Official Documentation

Model Context Protocol: The complete protocol specification is available at modelcontextprotocol.io. Consult it to understand advanced concepts like resources, prompts, and sampling.

PHP-MCP: Server and client libraries are documented at github.com/php-mcp. You’ll find examples of advanced attributes and development patterns.

Conclusion

MCP represents a revolution in how our PrestaShop stores interact with artificial intelligence. By exposing your business logic through well-defined tools, you create an ecosystem where AI agents become true assistants capable of automating complex tasks.

ps_mcp_server makes this integration accessible to any PHP developer familiar with PrestaShop. The attribute-based approach significantly simplifies development: define your tools, annotate them, and the system handles exposing them to AI agents.

Use cases are infinite: automated product management, predictive sales analysis, intelligent customer support, on-demand report generation, dynamic price optimization. Imagination is the only limit.

Start with a simple tool (like product search), test it with MCP Inspector, then connect Claude or Gemini to experiment with intelligent automation. You’ll quickly discover MCP’s transformative potential for your e-commerce.