PHPackages                             sylius/admin-mcp-server-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. sylius/admin-mcp-server-plugin

ActiveSylius-plugin

sylius/admin-mcp-server-plugin
==============================

Sylius Admin MCP Server Plugin — exposes Sylius Admin API as an MCP server with OAuth 2.0 PKCE authentication.

v0.1.0(today)01↑2900%1[1 PRs](https://github.com/Sylius/AdminMcpServerPlugin/pulls)MITPHPPHP ^8.2CI passing

Since Jul 23Pushed todayCompare

[ Source](https://github.com/Sylius/AdminMcpServerPlugin)[ Packagist](https://packagist.org/packages/sylius/admin-mcp-server-plugin)[ GitHub Sponsors](https://github.com/sylius)[ RSS](/packages/sylius-admin-mcp-server-plugin/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (33)Versions (2)Used By (0)

 [    ![Sylius Logo.](https://camo.githubusercontent.com/ea9dddc934264aa7ec01cf3202c500f3d8b04448bce2571bdc74230efddda88f/68747470733a2f2f6d656469612e73796c6975732e636f6d2f73796c6975732d6c6f676f2d3830302e706e67)  ](https://sylius.com)

Sylius Admin MCP Server Plugin
==============================

[](#sylius-admin-mcp-server-plugin)

Exposes Sylius Admin API as a Model Context Protocol (MCP) server with OAuth 2.0 PKCE authentication.

---

This plugin turns your Sylius store into an MCP server, allowing AI assistants (Claude, Cursor, etc.) to manage your store through natural language. It provides 171 tools covering all major Sylius resources - products, orders, customers, promotions, shipping, and more - secured by a full OAuth 2.0 Authorization Code + PKCE flow.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Sylius 2.1 or 2.2
- Symfony 7.4
- MySQL or PostgreSQL
- Node.js 20+ and Yarn (for frontend assets)

Installation
------------

[](#installation)

### Installation with Symfony Flex recipe

[](#installation-with-symfony-flex-recipe)

When Symfony Flex is active, `composer require sylius/admin-mcp-server-plugin` automatically registers the bundles, imports the plugin configuration, and imports the routes. Continue from Step 2 below.

> **Note on `symfony/type-info` patch** (Sylius 2.2.x): A bug in `symfony/type-info v7.4.x` causes a cache warmup error: `Cannot create union with both "object" and class type`. Apply the patch that ships with the plugin:
>
> ```
> patch vendor/symfony/type-info/TypeContext/TypeContextFactory.php \
>   vendor/sylius/admin-mcp-server-plugin/patches/symfony-type-info-union-fix.patch
> ```
>
>
>
> To re-apply this patch automatically after every `composer update`, you can use [cweagans/composer-patches](https://github.com/cweagans/composer-patches):
>
> 1. `composer require --dev cweagans/composer-patches`
> 2. Copy the patch to your project: `mkdir -p patches && cp vendor/sylius/admin-mcp-server-plugin/patches/symfony-type-info-union-fix.patch patches/`
> 3. Add to your `composer.json`: ```
>     "config": { "allow-plugins": { "cweagans/composer-patches": true } },
>     "extra": {
>         "patches": {
>             "symfony/type-info": {
>                 "Fix: Cannot create union with both object and class type": "patches/symfony-type-info-union-fix.patch"
>             }
>         }
>     }
>     ```
> 4. Run `composer install`

#### Step 1 - Add the plugin via Composer

[](#step-1---add-the-plugin-via-composer)

```
composer require sylius/admin-mcp-server-plugin
```

> **Note on `league_oauth2_server.yaml`**: the plugin ships its own `config/packages/league_oauth2_server.yaml` that configures the OAuth2 server using `SYLIUS_ADMIN_MCP_SERVER_OAUTH_*` environment variables. If your application already has a `config/packages/league_oauth2_server.yaml` (e.g. created by the `league/oauth2-server-bundle` Flex recipe), the plugin's configuration takes precedence and overrides it.

#### Step 2 - Generate OAuth keypair

[](#step-2---generate-oauth-keypair)

The plugin uses a dedicated RSA keypair (separate from Lexik JWT) for signing OAuth tokens:

```
mkdir -p config/jwt
openssl genrsa -out config/jwt/mcp_private.pem 4096
openssl rsa -in config/jwt/mcp_private.pem -pubout -out config/jwt/mcp_public.pem
```

The keys default to `config/jwt/mcp_private.pem` and `config/jwt/mcp_public.pem`. Override via env vars if you want a different location.

#### Step 3 - Configure environment variables

[](#step-3---configure-environment-variables)

Add to your `.env` (or `.env.local`):

```
###> sylius/admin-mcp-server-plugin ###
# URL of this application's Admin API (used by MCP tools to call the API)
SYLIUS_ADMIN_MCP_SERVER_API_URL=https://your-domain.com/api/v2/admin/
# Admin API user credentials - only required if you use the credentials-based token provider.
# By default the plugin reuses the OAuth Bearer token of the logged-in admin user.
# To switch to credential-based login, alias the service in your config/services.php:
#   ->alias('sylius_admin_mcp_server.provider.token', 'sylius_admin_mcp_server.provider.token.credentials');
SYLIUS_ADMIN_MCP_SERVER_API_EMAIL=api@example.com
SYLIUS_ADMIN_MCP_SERVER_API_PASSWORD=your-api-password
# Set to false to disable SSL verification (useful for local HTTPS)
SYLIUS_ADMIN_MCP_SERVER_VERIFY_SSL=true
# OAuth RSA keypair generated in Step 2 (separate from Lexik JWT keys)
SYLIUS_ADMIN_MCP_SERVER_OAUTH_PRIVATE_KEY=%kernel.project_dir%/config/jwt/mcp_private.pem
SYLIUS_ADMIN_MCP_SERVER_OAUTH_PUBLIC_KEY=%kernel.project_dir%/config/jwt/mcp_public.pem
SYLIUS_ADMIN_MCP_SERVER_OAUTH_PASSPHRASE=
# Random hex string for OAuth token encryption - generate with: openssl rand -hex 32
SYLIUS_ADMIN_MCP_SERVER_OAUTH_ENCRYPTION_KEY=your-32-byte-hex-key-here
###< sylius/admin-mcp-server-plugin ###
```

Generate the encryption key:

```
openssl rand -hex 32
```

#### Step 4 - Run database migrations

[](#step-4---run-database-migrations)

```
php bin/console doctrine:migrations:migrate -n
```

This creates three OAuth tables: `sylius_admin_mcp_oauth_clients`, `sylius_admin_mcp_oauth_authorization_codes`, `sylius_admin_mcp_oauth_refresh_tokens`.

#### Step 5 - Clear cache

[](#step-5---clear-cache)

```
php bin/console cache:clear
php bin/console cache:warmup
```

#### Step 6 - Build frontend assets

[](#step-6---build-frontend-assets)

The admin authorization page requires Sylius admin panel assets. If you haven't already:

```
yarn install
yarn build
php bin/console assets:install
```

#### Step 7 - Grant API access to an admin user

[](#step-7---grant-api-access-to-an-admin-user)

Only admin users with `ROLE_API_ACCESS` can authorize via the OAuth consent page. Grant it to an existing user via SQL:

```
UPDATE sylius_admin_user
SET roles = JSON_ARRAY_APPEND(roles, '$', 'ROLE_API_ACCESS')
WHERE email = 'your@admin.com';
```

Or create a dedicated API user in your fixtures.

---

### Manual Installation (without Symfony Flex)

[](#manual-installation-without-symfony-flex)

If your project does not use Symfony Flex, the bundles, configuration, and routes are not registered automatically. See [docs/manual-installation.md](docs/manual-installation.md) for step-by-step instructions.

---

Verification
------------

[](#verification)

After installation, verify everything is working:

```
# 1. Check services registered
php bin/console debug:container --tag=mcp.tool | grep "Sylius"

# 2. Check routes registered
php bin/console debug:router | grep mcp

# 3. Check OAuth discovery endpoint
curl -sk https://your-domain.com/.well-known/oauth-authorization-server | python3 -m json.tool
```

Expected routes: `/.well-known/oauth-authorization-server`, `/_mcp/oauth/register`, `/admin/mcp/oauth/authorize`, `/_mcp/oauth/token`, `/_mcp`.

---

Connecting MCP Clients
----------------------

[](#connecting-mcp-clients)

Once the plugin is installed and running, connect an AI assistant using one of the options below.

### Option A - Claude Desktop (local or remote)

[](#option-a---claude-desktop-local-or-remote)

Claude Desktop supports both local and remote MCP servers and works out of the box with any HTTPS URL - including `localhost` with a self-signed certificate.

Edit your Claude Desktop configuration file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```
{
  "mcpServers": {
    "sylius-admin": {
      "type": "http",
      "url": "https://your-domain.com/_mcp"
    }
  }
}
```

Claude Desktop reads the OAuth discovery endpoint (`/.well-known/oauth-authorization-server`) automatically and opens the consent page in your default browser when you first use the server. No manual token management is required.

> **Local development**: Use `"url": "https://127.0.0.1:8003/_mcp"`. Claude Desktop accepts self-signed certificates, so no tunnelling is needed.

### Option B - Claude.ai in the browser (Custom Connectors)

[](#option-b---claudeai-in-the-browser-custom-connectors)

> **Requirements**: Claude.ai **Pro or Max** plan. The server must be publicly accessible over HTTPS with a **valid (non-self-signed) SSL certificate**. `localhost` does not work - Anthropic's servers call your endpoint from their own IP ranges.

1. Open [claude.ai](https://claude.ai) → click your avatar → **Customize Claude** → **Connectors** → **+** → **Add custom connector**
2. Paste your server URL: `https://your-domain.com/_mcp`
3. Click **Connect**. Claude.ai reads the `/.well-known/oauth-authorization-server` discovery document automatically and redirects you to your Sylius admin consent page.
4. Log in as an admin user with `ROLE_API_ACCESS` and click **Allow**.

Claude.ai uses `https://claude.ai/api/mcp/auth_callback` as its redirect URI, which the plugin's dynamic client registration endpoint accepts automatically.

> **Local development without a public server**: Tunnel your local server through a public HTTPS URL using [ngrok](https://ngrok.com), [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), or [LocalCan](https://www.localcan.com/):
>
> ```
> # Example with ngrok:
> ngrok http https://127.0.0.1:8003
> # Then use the generated https://xxxx.ngrok-free.app/_mcp URL in claude.ai
> ```

### Option C - Claude Code (CLI)

[](#option-c---claude-code-cli)

```
claude mcp add --transport http sylius-admin https://your-domain.com/_mcp
```

Claude Code handles the full OAuth PKCE flow automatically on first use (opens a browser window for the consent step).

### Option D - Cursor

[](#option-d---cursor)

In Cursor settings → **MCP** → **Add server**:

```
{
  "sylius-admin": {
    "url": "https://your-domain.com/_mcp",
    "type": "http"
  }
}
```

---

Security
--------

[](#security)

- All `/_mcp` requests require a valid OAuth 2.0 Bearer token (returns `401` otherwise)
- Authorization is limited to admin users with `ROLE_API_ACCESS`
- Tokens expire after 1 hour; refresh tokens are valid for 30 days
- PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks

---

Documentation
-------------

[](#documentation)

- [Authentication Flow (OAuth 2.0 PKCE)](docs/authentication.md)
- [Available MCP Tools](docs/tools.md) - 171 tools across 34 resource groups
- [Configuration Reference](docs/configuration.md) - selectively disabling tool groups
- [Manual Installation](docs/manual-installation.md) - step-by-step guide for projects without Symfony Flex
- [Troubleshooting](docs/troubleshooting.md)

---

License
-------

[](#license)

This plugin is released under the [MIT License](LICENSE).

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance100

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 81.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/719423?v=4)[Sylius eCommerce](/maintainers/sylius)[@Sylius](https://github.com/Sylius)

![](https://www.gravatar.com/avatar/4b4a5a1a9293502aa8573551fab020963a9050c5cca4524433b6d94214d3b480?d=identicon)[GSadee](/maintainers/GSadee)

---

Top Contributors

[![Cholin2000](https://avatars.githubusercontent.com/u/85901846?v=4)](https://github.com/Cholin2000 "Cholin2000 (98 commits)")[![Wojdylak](https://avatars.githubusercontent.com/u/33687392?v=4)](https://github.com/Wojdylak "Wojdylak (20 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

---

Tags

mcpaisyliusoauth2sylius-pluginModel Context Protocol

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sylius-admin-mcp-server-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/sylius-admin-mcp-server-plugin/health.svg)](https://phpackages.com/packages/sylius-admin-mcp-server-plugin)
```

###  Alternatives

[wordpress/mcp-adapter

Adapter for Abilities API, letting WordPress abilities to be used as MCP tools, resources or prompts

887184.7k8](/packages/wordpress-mcp-adapter)[php-mcp/laravel

Laravel SDK for building Model Context Protocol (MCP) servers - Seamlessly integrate MCP tools, resources, and prompts into Laravel applications

473153.0k4](/packages/php-mcp-laravel)[sylius/refund-plugin

Plugin provides basic refunds functionality for Sylius application.

701.8M21](/packages/sylius-refund-plugin)[sylius/invoicing-plugin

Invoicing plugin for Sylius.

891.1M2](/packages/sylius-invoicing-plugin)[sylius/paypal-plugin

PayPal plugin for Sylius.

461.5M7](/packages/sylius-paypal-plugin)[vizra/vizra-adk

Vizra Agent Development Kit - A comprehensive Laravel package for building intelligent AI agents.

29434.2k](/packages/vizra-vizra-adk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)