README

MCP Server Plugin

A Sylius plugin that exposes a Model Context Protocol (MCP) server for enabling interaction with your store via Large Language Models (LLMs) like ChatGPT.

Installation

Requirements

We work on stable, supported and up-to-date versions of packages. We recommend you to do the same.

Package	Version
PHP	^8.2
sylius/sylius	^2.1
MySQL	^8.4
NodeJS	^20.x

Beware!

This installation instruction assumes that you're using Symfony Flex.

Require plugin with composer:

  composer require sylius/mcp-server-plugin

Clear application cache by using command:

  bin/console cache:clear

Without Symfony Flex

Require the plugin:

composer require sylius/mcp-server-plugin

Import the plugin configuration in config/packages/sylius_mcp_server.yaml:

imports:
    - { resource: "@SyliusMcpServerPlugin/config/config.yaml" }

Import the routes in config/routes.yaml:

sylius_mcp_server:
    resource: '@SyliusMcpServerPlugin/config/routes.yaml'

Clear application cache:

bin/console cache:clear

Documentation

What is MCP Server?

The Model Context Protocol (MCP) is a standardized way to connect language models (like ChatGPT) with external tools, APIs, and systems. It allows an AI model to make structured tool calls — similar to calling functions — during a conversation.

The MCP Server acts as a bridge between the language model and your application logic. It exposes a list of tools (like “search for a product” or “create an order”) and executes them in response to requests from the AI.

This plugin integrates Sylius with an MCP Server, enabling AI agents to interact with your store (e.g., search products, check prices, start checkout).

We use the official symfony/mcp-bundle to provide the MCP server runtime.

┌────────────────┐                  ┌───────────────┐       ┌────────┐
│  MCP Client    │◄────────────────►│  MCP Server   │◄─────►│ Sylius │
│ (OpenAi, etc.) │  (Stdio/HTTP)    │ (Tools, etc.) │ (API) │        │
└────────────────┘                  └───────────────┘       └────────┘

To learn more, see the official MCP introduction at modelcontextprotocol.io.

Running the MCP Server

Stdio Transport

  bin/console mcp:server

HTTP Transport

The HTTP endpoint is available at /mcp/shop.

MCP Server Configuration

For more options, refer to the symfony/mcp-bundle documentation.

Sylius API

Tools communicate with the Sylius API through pre-configured HTTP clients:

sylius_mcp_server.http_client.api_shop:
    base_uri: '%sylius_mcp_server.api.shop_base_uri%'
    headers:
        - 'Accept: application/ld+json'
        - 'Content-Type: application/ld+json'
sylius_mcp_server.http_client.api_shop_merge_patch:
    base_uri: '%sylius_mcp_server.api.shop_base_uri%'
    headers:
        - 'Accept: application/ld+json'
        - 'Content-Type: application/merge-patch+json'

The default API base URI is https://localhost:8000/api/v2/shop/, and can be overridden using the environment variable SYLIUS_MCP_SERVER_API_SHOP_BASE_URI.

Environment variables

Variable	Default	Description
`SYLIUS_MCP_SERVER_API_SHOP_BASE_URI`	`https://localhost:8000/api/v2/shop/`	Base URI of the Sylius Shop API (with trailing slash). Used by all tools to call the Sylius API.

Set it in your .env.local:

SYLIUS_MCP_SERVER_API_SHOP_BASE_URI=https://myshop.example.com/api/v2/shop/

Tools

The following tools are available out of the box:

Name	Description
add_item_to_order	Adds an item to the order.
complete_checkout	Returns a `checkout_url` for the customer to finish payment in their browser. (Final step)
create_order	Creates a new order.
fetch_channel	Fetches a channel by code.
fetch_currency	Fetches a currency by code.
fetch_order	Fetches an order by its token.
fetch_product	Fetches a product by its code.
fetch_product_variant	Fetches a product variant by its code.
list_payment_methods	Lists all available payment methods.
list_shipping_methods	Lists all available shipping methods.
search_products	Searches for products by name.
search_product_variants	Searches for product variants by name.
select_payment_method	Selects a payment method for the order. (Step 3 of checkout)
select_shipping_method	Selects a shipping method for the order. (Step 2 of checkout)
update_order_address	Updates the order address. (Step 1 of checkout)

These tools currently operate in guest mode only — fetch_order returns data only if the order has no associated customer account.

Checkout flow

The typical checkout sequence driven by an AI agent looks like this:

create_order → add_item_to_order → update_order_address
    → list_shipping_methods → select_shipping_method
    → list_payment_methods  → select_payment_method
    → complete_checkout

complete_checkout does not finalize the order itself — instead it returns a JSON payload containing a checkout_url:

{
  "checkout_url": "https://myshop.example.com/checkout/resume/TOKEN",
  "message": "Share this URL with the customer to complete the purchase in their browser: ..."
}

Opening that URL sets the cart in the customer's browser session and redirects them to the standard checkout summary page, where they can review the order and pay. This design keeps payment handling in the browser (where payment method SDKs and 3DS flows run), while the AI agent handles all the data-entry steps.

Adding custom tools

You can extend the server with your own tools by creating PHP classes annotated with the #[McpTool] attribute.

To learn how to define and structure a tool, see the symfony/mcp-bundle documentation.

services:
    App\Mcp\Tool\:
        resource: '../src/Mcp/Tool/*'
        autoconfigure: true

Returning images

Tools can return images inline as MCP ImageContent blocks, which AI clients like Claude Desktop render visually. The plugin ships a DownloadsImagesTrait to handle downloading URLs and encoding them as base64 image content:

use Mcp\Capability\Attribute\McpTool;
use Mcp\Schema\Content\Content;
use Mcp\Schema\Content\TextContent;
use Sylius\McpServerPlugin\Tool\DownloadsImagesTrait;
use Symfony\Contracts\HttpClient\HttpClientInterface;

#[McpTool(name: 'my_tool', description: '...')]
final readonly class MyTool
{
    use DownloadsImagesTrait;

    public function __construct(private HttpClientInterface $httpClient) {}

    /** @return Content[] */
    public function __invoke(): array
    {
        $json = /* ... fetch JSON ... */;
        $imageUrls = [/* ... extract image URLs from $json ... */];

        return [new TextContent($json), ...$this->downloadImages($imageUrls)];
    }
}

The trait requires a $httpClient property (HttpClientInterface) on the using class. It fetches all URLs concurrently, reads the Content-Type header for the MIME type, and returns an array of ImageContent objects.

Usage Example

You can use the server directly in OpenAI Playground, exposing it via ngrok or similar tunneling tools.

Example with OpenAI Playground

Add a new tool in the OpenAI Playground.
Configure the tool with the following settings:
- URL: http://localhost:8080/mcp/shop (or your ngrok URL)
- Label: Sylius
- Authentication: None

Example with API Call

  curl https://api.openai.com/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
      "model": "gpt-4.1",
  
      "tools": [
        {
          "type": "mcp",
          "server_label": "Sylius",
          "server_url": "$YOUR_MCP_SERVER_URL",
          "require_approval": "never"
        }
      ],
  
      "input": [
        {
          "role": "user",
          "content": [
            {
              "type": "input_text",
              "text": "Find me red shoes"
            }
          ]
        }
      ],
      "max_output_tokens": 1024
    }'

Security issues

If you think that you have found a security issue, please do not use the issue tracker and do not post it publicly. Instead, all security issues must be sent to security@sylius.com

Community

For online communication, we invite you to chat with us & other users on Sylius Slack.

License

This plugin's source code is completely free and released under the terms of the MIT license.

sylius / mcp-server-plugin

Package info

Security

Fund package maintenance!

Statistics