This documentation always describes the latest published version.
Each server instance serves exactly one Sylius environment. The configuration comes from one .env file per environment; apart from choosing the environment there are no settings in the Claude Code manifest.
These variables live in the .env file of the respective environment. Always copy the shipped .env.example as a template instead of writing a file from scratch (see the note below).
| Variable | Required | Default | Description |
|---|---|---|---|
SYLIUS_ENVIRONMENT |
Yes | - | stage or prod. Any other value prevents startup. The template contains stage. |
SYLIUS_BASE_URL |
Yes | - | Base URL of the shop. A trailing slash is removed. |
SYLIUS_ADMIN_EMAIL |
Yes | - | Email address of the admin user for the API. |
SYLIUS_ADMIN_PASSWORD |
Yes | - | Password of that user. |
SYLIUS_API_KEY |
No | empty | Additional shared secret sent as the X-Stage-Api-Key header on every request, including login. Stage only; leave empty on prod. |
SYLIUS_IMAGE_UPLOAD_BASE_DIR |
No | empty | Absolute, existing path. add_product_image and add_taxon_image may only upload files inside this directory. Empty means file upload is disabled (cdn_url still works). |
A variable that is missing entirely from a hand-written
.env(instead of being empty) inherits whatever value happens to be set in the process. So always copy from.env.example, which contains both optional keys explicitly empty.
At startup run.py decides which file to load, in this order:
| Variable (process) | Effect |
|---|---|
SYLIUS_ENV_FILE |
Absolute path to an existing file. Wins if both variables are set. A relative path or a missing file aborts startup. |
SYLIUS_ENV_NAME |
stage or prod. Loads ~/.claude-plugin-syliusadmin/<name>/.env. The plugin sets this variable for its two servers in .mcp.json. Another value or a missing file aborts startup. |
| neither | The .env right next to run.py (behavior of the manual installation). |
The file takes precedence: values from the file overwrite SYLIUS_* variables already set in the process.
If
SYLIUS_ENV_NAMEandSYLIUS_ENVIRONMENTin the file do not match, the server refuses to start. That way aprodregistration can never report itself asstagewhile actually writing to the live shop.
# ~/.claude-plugin-syliusadmin/stage/.env
SYLIUS_ENVIRONMENT=stage
SYLIUS_BASE_URL=https://stage.example.com
SYLIUS_ADMIN_EMAIL=api@example.com
SYLIUS_ADMIN_PASSWORD=...
SYLIUS_API_KEY=...
SYLIUS_IMAGE_UPLOAD_BASE_DIR=/home/your-user/shop-images
# ~/.claude-plugin-syliusadmin/prod/.env
SYLIUS_ENVIRONMENT=prod
SYLIUS_BASE_URL=https://shop.example.com
SYLIUS_ADMIN_EMAIL=api@example.com
SYLIUS_ADMIN_PASSWORD=...
SYLIUS_API_KEY=
SYLIUS_IMAGE_UPLOAD_BASE_DIR=
The server logs in via POST /api/v2/admin/administrators/token with email and password and receives a JWT. For that it needs a dedicated admin user.
php bin/console sylius:create-admin-user
The user additionally needs the role ROLE_API_ACCESS. ROLE_ADMINISTRATION_ACCESS (admin panel access) alone is not enough for the Admin API: login then works, but every tool call fails with HTTP 403. The Community Edition has no UI for this; you add the role in the roles field of the sylius_admin_user table.
Granular admin roles exist in Sylius only in the paid Plus edition. In the Community Edition every admin user is technically a full admin. The restriction to catalog and shop configuration comes solely from the server having no order, customer or promotion tools and checking every request against its own path allowlist.
On production systems you should remove the default demo admin and use a dedicated API user instead.
If the stage instance is protected by Basic Auth, it collides with the JWT because both need the Authorization header. In the setup this server was built for, /api/v2/admin/ is therefore excluded from Basic Auth and secured with a shared secret in the X-Stage-Api-Key header instead. Enter that secret in SYLIUS_API_KEY. It must match exactly the value the stage instance expects.
The server sends the header on every request as soon as SYLIUS_API_KEY is set, regardless of SYLIUS_ENVIRONMENT. On prod, leave the variable empty.
SYLIUS_IMAGE_UPLOAD_BASE_DIR must be an absolute path to an existing directory. Relative paths in a tool call are resolved against this directory, and every path must lie inside it after resolution (including symlinks). Allowed are .jpg, .jpeg, .png, .gif and .webp up to 10,000,000 bytes.
The directory lives on the machine where the MCP server runs, not on the shop server. Details and limits are on the page Security and privacy.
Some tools talk to endpoints of Sylius plugins. They only work if the respective plugin is installed in the shop:
| Plugin in the shop | Affected feature |
|---|---|
sylius-seo-suite-pro |
SEO fields metaTitle, canonicalPathOverride, robotsIndex, robotsFollow in the translations of products and categories |
sylius-cdn-product-images |
Parameter cdn_url on add_product_image and add_taxon_image |
sylius-marketplace-redirect |
The five marketplace link tools |
sylius-product-custom-inputs |
The two tools for input field definitions |
Without the respective plugin Sylius answers with an error (for the SEO fields the key is silently ignored, see Tools).