How to create my own MCP elements?

Module developers can create their own MCP elements to expose their module's functionality to AI applications, or to expose native PrestaShop features beyond what the default tools offer.

To create your own MCP elements for PrestaShop MCP Server, declare your module as MCP-compatible and define your custom elements using PHP attributes.

Tables of contents

1. Declare your module as MCP-compatible

To let PrestaShop MCP Server know your module includes MCP elements, declare it as MCP-compatible by adding the isMcpCompliant() method to your main module class:

<?php

class Ps_MySuperModule extends Module
{
    // This method allows ps_mcp_server to discover your MCP elements
    public function isMcpCompliant()
    {
        return true;
    }
}

?>

2. Implement your MCP Tools

Warning

MCP elements must be created exclusively in the src directory and its subdirectories. Any code located in other directories will be ignored.

Tools are actions that an AI agent can invoke to interact with your store (e.g. search products, update orders). To create MCP tools in your module, use PHP attributes from the PrestaShop MCP Server module:

<?php

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpTool;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpSchema;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpIcon;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpToolAnnotations;

class MySuperTool
{
    #[PsMcpTool(
        name: 'say_hello',
        title: 'Hello User',
        description: 'Say hello to a user',
        annotations: new PsMcpToolAnnotations(
            title: 'Hello User',
            readOnlyHint: true,
            destructiveHint: false,
            idempotentHint: true,
            openWorldHint: false,
        ),
        icons: [
            new PsMcpIcon(
                src: 'https://picsum.photos/100/100',
                mimeType: 'image/png',
                sizes: ['100x100']
            )
        ],
        meta: ['category' => 'greeting']
    )]
    #[PsMcpSchema(
        properties: [
            'username' => ['type' => 'string', 'description' => 'Username'],
        ],
        required: ['username']
    )]
    public function sayHello(string $username): string
    {
        try {
            return "Hello, $username! Welcome to your PrestaShop store.";
        } catch (\Exception $e) {
            throw new PsMcpToolCallException($e->getMessage(), $e->getCode());
        }
    }
}

?>

PsMcpToolAnnotations is exclusive to Tools. It provides hints to the AI client about the tool's behavior:

Property	Type	Description
`title`	string	Human-readable title for the tool
`readOnlyHint`	bool	The tool does not modify the environment
`destructiveHint`	bool	The tool may perform destructive updates
`idempotentHint`	bool	The tool can be called repeatedly without side effects
`openWorldHint`	bool	The tool interacts with external systems

PsMcpSchema defines the tool's input parameters via JSON Schema. It applies only to Tools.

Check the ps_mcp_boilerplate project for a full implementation example.

Security note: For development only, you can disable authentication by adding this constant to your PrestaShop configuration:

define('_PS_MCP_SERVER_ALLOW_INSECURE_MODE_', true);

Warning

Never enable insecure mode in production environments.

3. Implement your MCP Resources

Resources expose read-only data that an AI agent can access (e.g. store configuration, product catalog). Each resource is identified by a fixed URI.

<?php

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpResource;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpIcon;

class MyStoreResources
{
    #[PsMcpResource(
        uri: 'store://configuration',
        name: 'store_configuration',
        description: 'Returns the current store configuration (currency, language, timezone...)',
        mimeType: 'application/json',
        size: 18,
        icons: [
            new PsMcpIcon(
                src: 'https://picsum.photos/100/100',
                mimeType: 'image/png',
                sizes: ['100x100']
            )
        ],
        meta: ['category' => 'store_management']
    )]
    public function getStoreConfiguration(): array
    {
        try {
            return [
                'currency' => Configuration::get('PS_CURRENCY_DEFAULT'),
                'language' => Configuration::get('PS_LANG_DEFAULT'),
            ];
        } catch (\Exception $e) {
            throw new PsMcpResourceReadException($e->getMessage(), $e->getCode());
        }
    }
}

?>

Tips

Resources do not use PsMcpToolAnnotations or PsMcpSchema. These attributes are reserved for Tools.

4. Implement your MCP Resource Templates

Resource Templates define URI patterns (RFC 6570) that allow an AI agent to dynamically request resources by filling in variables (e.g. products://{id}). They are useful when the set of possible resources is large or unknown in advance.

<?php

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpResourceTemplate;

class MyResourceTemplates
{
    #[PsMcpResourceTemplate(
        uriTemplate: 'products://{id}',
        name: 'product_by_id',
        description: 'Returns the full details of a product identified by its numeric ID',
        mimeType: 'application/json',
        meta: ['category' => 'product_management']
    )]
    public function getProductById(int $id): array
    {
        try {
            $product = new Product($id, true);
            return $product->getFields();
        } catch (\Exception $e) {
            throw new PsMcpResourceReadException($e->getMessage(), $e->getCode());
        }
    }
}

?>

Tips

Like Resources, Resource Templates do not use PsMcpToolAnnotations or PsMcpSchema.

5. Implement your MCP Prompts

Prompts are reusable conversation templates that help an AI agent start an exchange with pre-filled context. They are surfaced in the client UI so users can trigger them with a single click.

A prompt returns a message array (role + content), representing a conversation exchange:

<?php

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpPrompt;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpIcon;

class MyStorePrompts
{
    #[PsMcpPrompt(
        name: 'image_generation',
        title: 'Image Generation',
        description: 'Generate images for products',
        icons: [
            new PsMcpIcon(
                src: 'https://picsum.photos/100/100',
                mimeType: 'image/png',
                sizes: ['100x100']
            )
        ],
        meta: ['category' => 'image_generation']
    )]
    public function generateImage(string $color, string $size): array
    {
        try {
            return [
                ['role' => 'assistant', 'content' => 'You are an image generation tool for a PrestaShop store.'],
                ['role' => 'user', 'content' => "Generate an image with color: $color, size: $size."],
                ['role' => 'assistant', 'content' => 'Here is your generated image: https://example.com/image?color=' . urlencode($color) . '&size=' . urlencode($size)],
            ];
        } catch (\Exception $e) {
            throw new PsMcpPromptGetException($e->getMessage(), $e->getCode());
        }
    }
}

?>

Tips

Prompts do not use PsMcpToolAnnotations, PsMcpSchema, or annotations. Only name, title, description, icons and meta are available.

Attribute summary by element type

Attribute	Tools	Resources	Resource Templates	Prompts
`PsMcpSchema`	yes	-	-	-
`PsMcpToolAnnotations`	yes	-	-	-
`PsMcpIcon`	yes	yes	-	yes
`meta`	yes	yes	yes	yes
`title`	yes	-	-	yes
`name`	yes	yes	yes	yes
`description`	yes	yes	yes	yes

Error handling

PrestaShop MCP Server provides dedicated exception classes to handle errors in tools, resources and prompts. Each exception wraps the corresponding MCP SDK exception and ensures that the error is properly communicated to the AI agent through the MCP protocol.

Exception class	Wraps (SDK)	Use in
`PsMcpToolCallException`	`ToolCallException`	Tools
`PsMcpResourceReadException`	`ResourceReadException`	Resources / Resource Templates
`PsMcpPromptGetException`	`PromptGetException`	Prompts

All constructors take the same two parameters:

message (string): A human-readable error description that will be sent to the AI agent.
exitCode (int): A numeric exit code indicating the type of error.

Error handling in Tools

<?php

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpTool;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpSchema;
use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpToolCallException;

class MySuperTool
{
    #[PsMcpTool(
        name: 'get_order_by_id',
        description: 'Retrieve an order by its ID'
    )]
    #[PsMcpSchema(
        properties: [
            'orderId' => ['type' => 'integer', 'description' => 'The order ID'],
        ],
        required: ['orderId']
    )]
    public function getOrderById(int $orderId): array
    {
        try {
            $order = new Order($orderId);

            if (!Validate::isLoadedObject($order)) {
                throw new \Exception('Order not found');
            }

            return $order->getFields();
        } catch (\Exception $e) {
            throw new PsMcpToolCallException(
                'Failed to retrieve order: ' . $e->getMessage(),
                1
            );
        }
    }
}

?>

Error handling in Resources

<?php

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpResource;
use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpResourceReadException;

class MyStoreResources
{
    #[PsMcpResource(
        uri: 'store://configuration',
        name: 'store_configuration',
        description: 'Returns the current store configuration',
        mimeType: 'application/json',
    )]
    public function getStoreConfiguration(): array
    {
        try {
            $currency = Configuration::get('PS_CURRENCY_DEFAULT');

            if (!$currency) {
                throw new \Exception('Currency configuration not found');
            }

            return ['currency' => $currency];
        } catch (\Exception $e) {
            throw new PsMcpResourceReadException(
                'Failed to read store configuration: ' . $e->getMessage(),
                1
            );
        }
    }
}

?>

Error handling in Prompts

<?php

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpPrompt;
use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpPromptGetException;

class MyStorePrompts
{
    #[PsMcpPrompt(
        name: 'low_stock_analysis',
        description: 'Analyze products with low stock and suggest restocking actions',
    )]
    public function lowStockAnalysis(): array
    {
        try {
            $threshold = Configuration::get('PS_LOW_STOCK_THRESHOLD');

            if ($threshold === false) {
                throw new \Exception('Low stock threshold not configured');
            }

            return [
                ['role' => 'user', 'content' => 'List all products with stock below ' . $threshold],
            ];
        } catch (\Exception $e) {
            throw new PsMcpPromptGetException(
                'Failed to generate prompt: ' . $e->getMessage(),
                1
            );
        }
    }
}

?>

Guidelines for effective Tools

These guidelines will help you design tools that agents can understand and leverage to accomplish complex tasks.

1. Describe your tools clearly and concisely

Define each tool's purpose and behavior clearly and concisely. This helps AI models understand the tool's functionality and use it correctly.

Example:

#[PsMcpTool(
    name: 'search_product_by_name',
    description: 'Search a product in the store by name only. This search uses fuzzy matching. Results are sorted by relevance.'
)]
#[PsMcpSchema(
    properties: [
        'searchTerms' => ['type' => 'string', 'description' => 'Search terms to look up in product names. Several terms can be provided as a semicolon separated list.'],
        'language' => ['type' => 'integer', 'description' => 'Language to run the search in. Defaults to preferred language.']
    ],
    required: ['searchTerms']
)]

In this example, the tool name and description leave no doubt on the use of the tool. The field searchTerms also shows how an agent can be guided to make full use of your tools.

2. Use consistent vocabulary

Use consistent vocabulary throughout your MCP server to help agents connect your tools and plan complex workflows using multiple tools together. This includes parameters, error messages, and other technical terms.