MCP Server ​

The module OOCS_LynxMcp runs a Model Context Protocol server, so AI assistants such as Claude or ChatGPT can read and build PageBuilder layouts. Tools call Magento code directly, not REST or GraphQL. What an assistant may do is decided by the Magento admin role of the person who connected it.

This page covers running the server, connecting assistants and adding your own tools. For what merchants can do with it, see Build with AI.

Running the server ​

php -d opcache.enable_cli=1 bin/magento lynx:mcp:serve --host=127.0.0.1 --port=7361

Requirements: the PHP extensions pcntl and posix (the command stops at once if one is missing).

The server is built on Workerman. The master process boots Magento once, then forks workers from that booted state. Each worker serves exactly one connection and exits, and the master forks a fresh one to replace it. A request therefore never sees state left by a previous one, a slow tool only occupies its own worker, and starting a worker takes a few milliseconds. The master closes its database connection before forking, so each worker opens its own; cache connections such as Redis or Valkey are re-created after the fork as well.

Enable OPcache for the CLI (-d opcache.enable_cli=1). The first worker compiles the code into shared memory and every later worker reuses it, which makes requests several times faster and workers much smaller.

The server speaks Streamable HTTP without sessions: one JSON response per POST /mcp, no server-sent events, no Mcp-Session-Id. Several server processes can therefore run behind one upstream. Each request is limited to 16 KB of headers and 1 MB of body.

bin/magento lynx:mcp:tools lists the registered tools with their ACL resource and whether they change data. Add --details for the full description and input schema, or --json for everything as JSON.

systemd ​

[Unit]
Description=Lynx MCP server
After=network.target mysql.service

[Service]
User=www-data
WorkingDirectory=/var/www/magento
ExecStart=/usr/bin/php -d opcache.enable_cli=1 bin/magento lynx:mcp:serve --host=127.0.0.1 --port=7361
Restart=always
KillSignal=SIGTERM
TimeoutStopSec=150

[Install]
WantedBy=multi-user.target

On SIGTERM, workers finish the request they are serving and exit; a worker still busy after --timeout seconds is killed. Keep TimeoutStopSec above --timeout. Workerman writes its PID and status files to var/lynx_mcp/ and its log to var/log/lynx_mcp_server.log. Tool errors go to the Magento logs in var/log/.

nginx ​

Serve the MCP server on its own subdomain. OAuth metadata must be found under /.well-known/ of the same origin, which is simplest when the server owns the whole host.

server {
    listen 443 ssl http2;
    server_name mcp.example.com;
    # ssl_certificate ...;
    # ssl_certificate_key ...;

    location / {
        proxy_pass http://127.0.0.1:7361;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_read_timeout 130s;
        proxy_request_buffering on;
    }
}

Set proxy_read_timeout above --timeout. The server's own log shows nginx as the client; real client addresses are in the nginx access log. The server does not rate-limit requests, so use limit_req in nginx if you need it.

Configuration ​

Stores › Configuration › Lynx › MCP Server, default scope only (there is one server process).

The Public URL is never derived from the Host header: clients store tokens per issuer, and the resource a token is checked against must not be chosen by the client.

Connecting an assistant ​

Give the assistant the endpoint https://mcp.example.com/mcp. For example, in Claude Code:

claude mcp add --transport http shop https://mcp.example.com/mcp

In Claude or ChatGPT, add it as a custom connector with the same URL. For scripts and CI, skip OAuth and pass a static token:

claude mcp add --transport http shop https://mcp.example.com/mcp \
  --header "Authorization: Bearer <integration access token>"

OAuth 2.1 with a pairing code ​

The authorization page has to be published in public metadata, so it cannot be an admin page without revealing the admin path. Lynx uses a pairing code instead:

1. The client calls /mcp, gets 401 with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource/mcp, and reads the server metadata.
2. The client identifies itself (see Clients) and opens the browser at /authorize with a PKCE challenge.
3. The page shows an 8-character code, valid for 10 minutes.
4. An admin opens Lynx › MCP › Authorize Client and enters the code. The review screen shows the client, its redirect URI and the tools the admin's role allows, with tools that change data marked. The admin approves or denies. After 5 wrong codes, the admin session is locked out for 15 minutes.
5. The browser page receives the redirect once, and the client exchanges the code at /token (PKCE S256 required, code valid for 5 minutes) for an access token and a refresh token.

Redirect URIs must use https, or http to a loopback address (any port).

Tokens are opaque and stored only as SHA-256 hashes. Magento's REST API does not accept them, so a leaked token exposes only the MCP tools of the role. Refreshing rotates the refresh token; if an old refresh token or code is used again, every token from that approval is revoked.

Clients ​

Lynx › MCP › Clients lists the clients the server knows. A client comes from one of three sources:

Deleting a client deletes its pending requests and tokens.

Connections and revocation ​

• Lynx › MCP › Connections lists every approved connection. Revoking one deletes all tokens from that approval at once; the client must ask for a new pairing code.
• Clients can revoke their own tokens with POST /revoke (RFC 7009).
• The cron job lynx_mcp_oauth_cleanup runs daily at 03:00 and removes expired requests, expired tokens and unused dynamically registered clients.

Admin permissions for the MCP screens ​

The first three sit under Lynx › MCP in the role resource tree; the last under Stores › Settings › Configuration.

Permissions model ​

Access is decided by the Magento ACL only. Every Bearer token is resolved to an admin role:

• an OAuth token acts with the role of the admin who approved it; that admin must still be active and not locked,
• an admin token acts with that admin's role,
• an integration token acts with the integration's resources.

Each tool has its own ACL resource under Lynx › MCP › Tools. tools/list returns only the tools the role holds, and calling any other tool fails as if it did not exist. The role is checked on every request, so granting or removing a resource, or locking the admin, takes effect on the next call without reconnecting. OAuth scopes are not used: a scope sent by the client is ignored, and every client an admin approves can call every tool of that admin's role. A role with All resources gets every tool, including tools from modules installed later.

Store scope ​

Each request starts in the admin store (All Store Views). Tools that work on one store view take a store argument: a store view code, or a domain or URL the store view serves (the longest matching base URL wins; if several store views share a base URL, use the code).

Built-in tools ​

Run bin/magento lynx:mcp:tools --details for each tool's full description and input schema.

CMS page and category layouts ​

A CMS page or a category can keep its own layout, which replaces the content zone of its storefront page where Render with Lynx is on. The tools reach these layouts through the pool OOCS\LynxPageBuilder\Model\LayoutSources, which maps a type to an OOCS\LynxPageBuilder\Api\LayoutSourceInterface implementation:

A layout shows only in store views that run a Lynx theme, carry the entity (assigned and active) and have the switch on. pagebuilder_read_layout reports all three per store view.

Extending ​

Add tools and routes from your own module. Declare a dependency on OOCS_LynxMcp in etc/module.xml:

<module name="Vendor_Module">
    <sequence>
        <module name="OOCS_LynxMcp"/>
    </sequence>
</module>

The server runs in the global area and loads only global DI. Register everything in etc/di.xml, never in etc/adminhtml/di.xml or another area file: area files are not loaded by the server, and an area declaration of the same array argument would replace the whole list. The same applies to any pool your tool reads.

Adding a tool ​

A tool is a class implementing OOCS\LynxMcp\Api\ToolInterface:

Conventions:

• Put the class in Tool/<Object>/<VerbObject>.php, for example Tool/Blocks/ReadBlock.php.
• Name the tool <group>_<verb>_<object>, such as cms_read_block. Names must match ^[a-zA-Z0-9_-]{1,64}$ and be unique: a later module registering the same name replaces the tool.
• Name the ACL resource <Module>::tool_<tool name> and place it under OOCS_LynxMcp::tools.
• The server does not validate arguments against the schema. Check them in execute().
• Throw Magento\Framework\Exception\LocalizedException for errors the assistant should read; its message is returned as a tool error. Any other exception is logged and reported as "The tool failed".
• The request starts in the admin store. Take a store argument when the tool works per store view.
• A request running longer than --timeout is killed. Wrap writes in a database transaction.

Example: a tool that reads a CMS block.

Tool/Blocks/ReadBlock.php

<?php
declare(strict_types=1);

namespace Vendor\Module\Tool\Blocks;

use Magento\Cms\Api\GetBlockByIdentifierInterface;
use Magento\Framework\Exception\LocalizedException;
use Magento\Framework\Exception\NoSuchEntityException;
use Magento\Store\Model\Store;
use Magento\Store\Model\StoreManagerInterface;
use OOCS\LynxMcp\Api\ToolInterface;

class ReadBlock implements ToolInterface
{
    /**
     * @param GetBlockByIdentifierInterface $getBlockByIdentifier
     * @param StoreManagerInterface $storeManager
     */
    public function __construct(
        private readonly GetBlockByIdentifierInterface $getBlockByIdentifier,
        private readonly StoreManagerInterface $storeManager,
    ) {
    }

    public function getDescription(): string
    {
        return 'Read a CMS block by identifier: id, title, whether it is active, and its HTML content.';
    }

    public function getInputSchema(): array
    {
        return [
            'type'       => 'object',
            'properties' => [
                'identifier' => ['type' => 'string', 'description' => 'Block identifier'],
                'store'      => ['type' => 'string', 'description' => 'Store view code; default all store views'],
            ],
            'required'   => ['identifier'],
        ];
    }

    public function getAclResource(): string
    {
        return 'Vendor_Module::tool_cms_read_block';
    }

    public function isReadOnly(): bool
    {
        return true;
    }

    public function execute(array $arguments): array
    {
        $identifier = trim((string) ($arguments['identifier'] ?? ''));
        if ($identifier === '') {
            throw new LocalizedException(__('identifier must not be empty.'));
        }

        try {
            $storeId = isset($arguments['store'])
                ? (int) $this->storeManager->getStore((string) $arguments['store'])->getId()
                : Store::DEFAULT_STORE_ID;
            $block = $this->getBlockByIdentifier->execute($identifier, $storeId);
        } catch (NoSuchEntityException) {
            throw new LocalizedException(__('No block or store view matches.'));
        }

        return [
            'id'        => (int) $block->getId(),
            'title'     => (string) $block->getTitle(),
            'is_active' => (bool) $block->isActive(),
            'content'   => (string) $block->getContent(),
        ];
    }
}

etc/acl.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="OOCS_LynxPageBuilder::manage">
                    <resource id="OOCS_LynxMcp::mcp">
                        <resource id="OOCS_LynxMcp::tools">
                            <resource id="Vendor_Module::tool_cms_read_block" title="Read CMS Block" translate="title"/>
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

etc/di.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="OOCS\LynxMcp\Model\ToolList">
        <arguments>
            <argument name="tools" xsi:type="array">
                <item name="cms_read_block" xsi:type="object">Vendor\Module\Tool\Blocks\ReadBlock\Proxy</item>
            </argument>
        </arguments>
    </type>
</config>

The item name is the tool name. Register the class through its Proxy, so listing tools does not build every tool's dependencies. ToolList checks names and classes when the server starts and stops with an error if one is invalid.

Then:

1. Run bin/magento setup:upgrade (and setup:di:compile in production).
2. Grant the new resource to the admin roles that should use it (System › Permissions › User Roles › Role Resources). Roles with All have it already.
3. Restart the MCP server.
4. Check it with bin/magento lynx:mcp:tools. Connected assistants see the tool the next time they list tools.

Adding an HTTP route ​

A route is a class implementing OOCS\LynxMcp\Api\RouteInterface:

• getMethods() returns the HTTP methods it answers; other methods get 405 with an Allow header.
• handle(array $request) receives method, path, query, headers (lower-case names) and body, and returns [status, headers, body]. An array body is sent as JSON.

Routes are not authenticated by the server. A route that exposes data must check the Authorization header itself.

<?php
declare(strict_types=1);

namespace Vendor\Module\Service\Route;

use OOCS\LynxMcp\Api\RouteInterface;

class Health implements RouteInterface
{
    public function getMethods(): array
    {
        return ['GET'];
    }

    public function handle(array $request): array
    {
        return [200, [], ['status' => 'ok']];
    }
}

Register it in etc/di.xml. The item name is the path, matched exactly (no parameters) and starting with /:

<type name="OOCS\LynxMcp\Model\RouteList">
    <arguments>
        <argument name="routes" xsi:type="array">
            <item name="/health" xsi:type="object">Vendor\Module\Service\Route\Health</item>
        </argument>
    </arguments>
</type>

Built-in paths are /mcp, /.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server, /authorize, /authorize/status, /token, /revoke and /register. Registering one of these names replaces the built-in route.

Providing a layout source ​

The cms_page and category arguments of the layout tools read and write through the LayoutSources pool. A module that stores CMS page or category layouts differently can register its own implementation of OOCS\LynxPageBuilder\Api\LayoutSourceInterface under the same type:

All methods taking an id throw NoSuchEntityException when the entity does not exist.

<!-- etc/di.xml -->
<type name="OOCS\LynxPageBuilder\Model\LayoutSources">
    <arguments>
        <argument name="sources" xsi:type="array">
            <item name="cms_page" xsi:type="object">Vendor\Module\Model\PageLayout</item>
        </argument>
    </arguments>
</type>

Make your module load after the module that registers the type you replace (OOCS_LynxCms for cms_page, OOCS_LynxCatalog for category). The built-in tools accept only the cms_page and category types. A source registered under another type can be read from your own tools with LayoutSources::get('<type>').

Limits ​

• Arguments are not validated against the input schema; each tool checks its own.
• The server sends no CORS headers. MCP clients running in a browser must go through their own proxy.
• Access cannot be narrowed per client: every client an admin approves can use every tool of that admin's role. Create a dedicated admin with a restricted role for assistants that should do less.