This documentation always describes the latest published version.
Symptom: In /mcp, syliusadmin-stage-mcp or syliusadmin-prod-mcp shows failed and no tools are available.
Check:
prod/.env does not contain credentials yet.SYLIUS_ENVIRONMENT, SYLIUS_BASE_URL, SYLIUS_ADMIN_EMAIL and SYLIUS_ADMIN_PASSWORD set in the environment's .env? If one is missing, startup aborts with a message naming the variable and the file that was read.~/.claude-plugin-syliusadmin/<stage or prod>/.env exist? If not, startup aborts; /syliusadmin:setup creates it.SYLIUS_ENVIRONMENT in the file match the folder (stage in the folder stage, prod in the folder prod)? Otherwise the server refuses to start.Solution for 5: bin/run-server starts the interpreter from ~/.claude-mcp-syliusadmin/venv (Windows: %USERPROFILE%\.claude-mcp-syliusadmin\venv), but the setup skill creates the venv under ~/.claude-plugin-syliusadmin/venv. Create it at the expected path:
python3 -m venv ~/.claude-mcp-syliusadmin/venv
~/.claude-mcp-syliusadmin/venv/bin/pip install -r <plugin-directory>/requirements.txt
Then restart Claude Code.
Symptom: Tool calls fail with "Sylius-Login fehlgeschlagen" and an HTTP status.
Check:
SYLIUS_ADMIN_EMAIL and SYLIUS_ADMIN_PASSWORD correct? The message contains only the status, never the data.SYLIUS_API_KEY match exactly the value the stage instance expects? The header is sent during login as well.SYLIUS_BASE_URL (certificate, firewall, VPN)?Symptom: Login works, but every call ends with HTTP 403.
Solution: The admin user lacks the role ROLE_API_ACCESS. ROLE_ADMINISTRATION_ACCESS alone is not enough. Add the role in the roles field of the sylius_admin_user table, see Configuration.
Symptom: A tool fails with "außerhalb des erlaubten Scopes", "kein DELETE" or "read-only".
Explanation: This is intended. The server blocks orders, customers, promotions and admin users as well as every delete except for marketplace links. Channels and input field definitions are read-only. See Security.
Symptom: add_product_image or add_taxon_image with image_path fails immediately with a note about SYLIUS_IMAGE_UPLOAD_BASE_DIR.
Solution: Set the variable in the .env to an absolute, existing path and restart. The image path must lie inside this directory and exist on the machine of the MCP server. If the image is already on the CDN, use cdn_url, which works without this setting.
Symptom: add_product_image with cdn_url returns a Sylius error.
Check: Is the plugin sylius-cdn-product-images installed in the shop? Without it, this route does not exist. variant_codes are not allowed together with cdn_url.
Symptom: set_product_active or update_product with enabled=true is rejected with a note about missing variants.
Solution: First create at least one variant with add_variant. Without a variant the product page in the shop would have no price and crash with HTTP 500.
Symptom: Message about missing channel prices or option values.
Solution:
channel_pricings needs a price for every channel the product is assigned to (get_product shows them).option_value_codes needs exactly one value per option of the product.Symptom: create_shipping_method or update_shipping_method fails on the configuration.
Solution: For flat_rate and per_unit_rate, configuration needs an entry for every channel of the shop (list_channels), not only those named in channel_codes. If you update configuration, rules or channel_codes, that replaces the complete data.
Symptom: metaTitle, canonicalPathOverride, robotsIndex or robotsFollow are accepted but missing when read back.
Explanation: The fields only exist where the shop's translation classes use the traits of the sylius-seo-suite-pro plugin. Otherwise the API ignores them without an error. Always read the translation back.
Symptom: option_codes is accepted, but the product's option list stays the same.
Explanation: Sylius only applies the change as long as no variant of the product has option values, and does not report that as an error. Remove the variants first (in the Sylius admin).
What is MCP? The Model Context Protocol is an open standard that lets Claude talk to external services through tools. This server is the bridge to the Sylius Admin API and runs locally over stdio.
Can Claude process orders? No. There are neither tools for it nor access through the allowlist.
Why can't I delete anything? That is intentional: deleting stays in the Sylius admin. Marketplace links are the exception. Shipping methods can be archived.
Can I use stage and prod at the same time? Yes, the plugin starts both servers at the same time. Each server serves exactly one environment.
Does the server run on Windows? The setup skill and the launcher scripts (bin/run-server.cmd) account for Windows, including the Python lookup via py -3.