Since Shopware 6.7.11.0, the core has shipped its own MCP server (Shopware Release Notes 6.7.11.0). Through the Model Context Protocol, AI agents can work in the Shopware Administration: search and maintain products, review orders, create reports. A request in a chat window thus becomes write access to the shop, and that is exactly why the scope matters. According to the documentation, every MCP request is validated against Shopware permissions (Shopware documentation), and which permissions those are is up to you. This article shows how to use AI agents through the MCP server in a controlled way: with a separate integration per assistant, an ACL role with minimal permissions, an allowlist, a dry run before writing and a test in staging. If you would rather not set up these workflows yourself, this is part of our AI automation.
What the MCP server in the Shopware core does
The Model Context Protocol is a standardized interface through which AI agents work with Shopware (Shopware documentation). The server provides three kinds of capabilities: tools for actions such as product search, record changes or order state changes, resources with reference data such as sales channels, currencies and state machines, and prompts with guidance on the data model. The Admin endpoint is /api/_mcp, a second one at /store-api/_mcp works in the context of a sales channel. For store operations, the documentation lists tasks such as generating product descriptions, updating product data and reviewing orders.
The demand is there. Just over a quarter of companies with ten or more employees in Germany used artificial intelligence in 2025, namely 26 percent (Destatis). Of these companies, 27 percent used AI to automate workflows or decision-making (Destatis). An agent that changes data in the Administration is exactly this kind of automation, and it needs the same limits as an employee with Administration access. How roles in the back office are cut in general is covered in our article on roles and permissions in the shop back office.
Our article Model Context Protocol: connecting your shop to AI agents covers external shopping agents that use a shop from the outside and a separately connected server. This one is about the server in the core and about assistants that work with Administration permissions.
Three versions, three changes for shop operators
The server has changed considerably within a few months. In 6.7.11.0 of June 16, 2026 (GitHub, shopware/shopware), it was still behind the MCP_SERVER feature flag. Since 6.7.14.0 of September 9, 2026 (GitHub, shopware/shopware), it has been enabled without a switch (Shopware Release Notes 6.7.14.0), but the MCP classes stay marked as experimental until 6.8.0 (Shopware Release Notes 6.7.14.0). 6.7.15.0 of October 1, 2026 (GitHub, shopware/shopware) added toolset selection when connecting and also extends Document v2.
| Version | Released | What changes for shop operators |
|---|---|---|
| 6.7.11.0 | 06/16/2026 | MCP server in the core, only with the MCP_SERVER feature flag; allowlist per integration in the settings |
| 6.7.14.0 | 09/09/2026 | Flag removed, endpoints reachable without a switch; new sessions first see only the discovery tools; reading through associations needs its own read permissions |
| 6.7.15.0 | 10/01/2026 | Toolsets selectable in the connection URL; missing or expired tokens return HTTP 401 instead of HTTP 500 |
From 6.7.14.0, the MCP endpoint runs whether you use it or not. Sign-in uses the Admin API authentication, and integration credentials are passed directly as headers (Shopware Release Notes 6.7.11.0). Without an allowlist of its own, an integration with admin rights may call all registered tools, resources and prompts (Shopware documentation). Review existing integrations before the first agent is connected, for example as described in our article on auditing Shopware apps.
Three layers every call has to pass
The documentation describes three independent security layers that every request to the MCP endpoint passes through before a capability is executed (Shopware documentation). The first is authentication, usually with the access key and secret access key of an integration. The second is the MCP allowlist, which defines which tools, resources and prompts an account may call at all. The third is the ACL role of the integration: even an allowed tool fails if the role lacks the required permission on the affected entity.
Every MCP request is validated against Shopware permissions.
Shopware documentation: MCP Support in Shopware
Authentication
Access key and secret access key of an integration as headers. They remain valid as long as the integration exists (Shopware documentation).
Allowlist
Per integration and per user: which tools, resources and prompts are visible and callable. An empty list blocks the whole type.
ACL role
Permissions per entity and action, such as product:update. They decide whether an allowed tool may actually change the record.
You should know two exceptions, because they bypass the layers. User accounts with admin rights bypass the allowlist regardless of the authentication method (Shopware documentation). An integration created with --admin, on the other hand, bypasses the ACL check but still respects its own allowlist (Shopware documentation). For an assistant, this means: do not sign in with an administrator account and do not use an admin integration, because otherwise only one of the two layers remains.
A token from an administrator signing in to the Administration belongs to that user account and therefore bypasses the allowlist. The documentation advises testing allowlist behavior with integration credentials or with a user without admin rights (Shopware documentation). Otherwise the test looks successful even though it did not touch the allowlist.
Different rules apply to the second endpoint. /store-api/_mcp has neither ACL nor allowlist: every tool registered there is reachable by every client that can authenticate against the sales channel (Shopware documentation). The sales channel context is the only boundary. Anyone who registers custom tools for this endpoint therefore has to validate input in the tool itself. The basics are covered in our article on securing the Store API.
One integration per assistant instead of a master key
The getting started guide creates the integration with bin/console integration:create. The --admin flag grants full Admin API access (Shopware documentation). For production use, the documentation advises omitting it, creating a dedicated ACL role with the required permissions and assigning it to the integration. The Best Practices page goes further: one integration per persona or job, each with its own tool allowlist (Shopware documentation).
In practice, this means the assistant that maintains delivery times and product texts gets a different integration than the assistant that analyzes orders. If the product assistant unexpectedly writes to orders, the attempt fails at the role and not at the hope that the model understands the task correctly. OWASP describes this principle as complete mediation: authorization is enforced in the downstream system instead of letting the language model decide whether an action is allowed (OWASP).
# Create the integration without --admin, then assign the ACL role in the Administration
bin/console integration:create "Assistant product maintenance"
# List the tools from the perspective of exactly this integration (honors its allowlist)
bin/console debug:mcp --integration=SWIA... Two properties of the credentials matter for operations. Integration credentials remain valid as long as the integration exists, with no expiration and no refresh (Shopware documentation). An Admin API bearer token, by contrast, expires after ten minutes by default (Shopware documentation). Precisely because the integration credentials do not expire, every integration needs a responsible person and should be deleted as soon as the assistant is no longer needed. Files containing the credentials do not belong in version control.
- The name of the integration states purpose and assistant, not just the tool
- No integration with
--admin, no user account with admin rights - A dedicated ACL role with only the permissions for this task
- A dedicated allowlist for tools, resources and prompts
- Credentials kept out of version control, storage location documented
- Responsible person and review date recorded, deletion planned for the end of use
The ACL role: what the assistant may write
All MCP tools respect the ACL role assigned to the integration in the Admin API (Shopware documentation). For write tools, Shopware checks the permission per record: an entry without an ID requires the create permission, an entry with an ID the update permission (Shopware documentation). A role that only contains product:update for products can change existing items but cannot create new ones. For an assistant in product maintenance, that is often exactly the right scope.
Which permissions the core tools require
| Tool | Task | Permissions per documentation |
|---|---|---|
| shopware-entity-search | Search records | Read permission on the entity, such as product:read |
| shopware-entity-upsert | Create or update records | create without ID, update with ID, each per entity |
| shopware-entity-delete | Delete records | delete on the entity |
| shopware-order-state | Change the state of order, payment and delivery | order:read, on commit per action order:update, order_transaction:update or order_delivery:update |
| shopware-system-config-write | Change system settings | system_config:update |
| shopware-media-upload | Load media from a public URL | media:create, with product assignment also product:update |
Since 6.7.14.0, the reading entity tools also check associations: loading an order together with customer data requires order_customer:read in addition to order:read (Shopware Release Notes 6.7.14.0). Integrations that relied on the missing check must add the association read permissions to their role (Shopware Release Notes 6.7.14.0). For shop operators, this is an advantage. Whether an assistant sees customer data is now a separate decision in the role and not a side effect of order access.
If a role is assigned to an MCP integration, its detail page lists the permissions the allowed tools require. One click adds all missing permissions (Shopware documentation). With an allowlist that is too broad, that closes the gap in the wrong direction. If in doubt, shrink the allowlist instead of expanding the role.
Plugins, bundles and apps can register their own tools (Shopware documentation). One detail applies to such tools: the #[McpToolRequires] annotation only fills the notices in the Administration and the output of debug:mcp, it does not enforce anything itself. The actual check has to be called by the tool with requirePrivilege (Shopware documentation). For custom extensions from our Shopware development, this check is therefore part of the code review of every tool.
The allowlist: which tools the assistant sees at all
You set the allowlist in the Administration per integration in the integration settings and per user on the user detail page (Shopware documentation). For each type: an unset value allows all capabilities of that type, a list restricts access to the named entries, and an empty list blocks the type entirely. When a tool is allowed, Shopware automatically includes its declared dependencies (Shopware documentation). Allowing shopware-entity-delete therefore also allows shopware-entity-search and shopware-entity-schema.
The Administration groups tools by toolset, so a whole group can be allowed with one click. The core ships six toolsets: entity, system-config, media, order, theme and store-api (Shopware documentation). The entity toolset contains reading and writing tools at the same time, from schema, search and aggregation to create, update and delete. Clicking the whole group also allows deletion. The Best Practices page names the dilemma itself: a group that mixes read-only inspection with destructive writes forces operators to choose between too much and too little (Shopware documentation). For product maintenance, schema, search, read and create or update are usually enough.
According to the documentation, the system configuration can contain SMTP credentials, payment API keys and other sensitive values (Shopware documentation). The system-config toolset therefore belongs only in the allowlist of an assistant that has exactly this task, and the write tool shopware-system-config-write in most cases in none.
There is also an installation-wide safety switch. The allowed_tools list under shopware.mcp restricts the available tools for all integrations at container compile time (Shopware documentation). An empty list means no restriction. If you fill it, you must include the three discovery tools, otherwise clients can no longer find the remaining tools. On a live system, the switch can, for example, allow only reading tools while the staging environment offers the full set.
shopware:
mcp:
allowed_tools:
- shopware-tool-search
- shopware-toolsets-list
- shopware-toolset-enable
- shopware-entity-schema
- shopware-entity-search
- shopware-entity-read
- shopware-entity-aggregate Toolsets in the connection URL: visibility is not a permission
Since 6.7.14.0, a new MCP session initially shows only three tools: the tool search, the toolset list and enabling a toolset (Shopware Release Notes 6.7.14.0). The agent finds all other tools through the search, or it enables their toolset for the current session. The search only returns tools that the allowlist already permits. Since 6.7.15.0, toolsets can also be named directly in the connection URL, for example /api/_mcp?toolsets=entity. This helps clients that read the tool list only once per connection.
The limit of this parameter is important. According to the release notes, it changes visibility only, and the allowlist and the role still decide what may be called (Shopware Release Notes 6.7.15.0). Likewise, enabling a toolset does not grant permission to call its tools (Shopware documentation). toolsets=all therefore gives the agent no additional permissions, but it fills its context window: each tool schema costs roughly 550 to 1,400 tokens (Shopware documentation), and the tool list is paginated with 50 entries per page (Shopware documentation). The documentation therefore recommends a short list of focused toolsets.
“What does the agent see?” is answered by toolsets and the connection URL. “What may the agent do?” is answered by the allowlist and the ACL role. Anyone who tries to solve a restriction through the URL has not restricted anything. The limit belongs in the allowlist and the role, the URL only keeps the context window tidy.
The dry run: what dryRun checks and what it does not
Write tools run as a dry run by default, so an agent can preview changes before saving them (Shopware documentation). Technically, Shopware opens a database transaction, runs the operation and then rolls the transaction back (Shopware documentation). Flow Builder actions are suppressed during the dry run (Shopware documentation), and only a second call with dryRun=false writes the change. For deletions, the dry run returns a preview of the records deleted along with it, for system settings a comparison of old and new value.
You should know two limits. First, the dry run does not cover all write tools: shopware-media-upload uploads immediately and has no dry-run mode (Shopware documentation). Second, the dry run is not an approval by a human. The agent makes the second call with dryRun=false itself. The Best Practices page justifies the default precisely because agents tend to be overconfident and call write tools on the first attempt without verifying parameters (Shopware documentation). The dry run enforces two steps, but it does not decide who triggers the second one.
The approval therefore has to sit somewhere else. The MCP specification recommends that a human can deny tool invocations and that applications ask for confirmation before sensitive operations (Model Context Protocol). OWASP advises carrying out high-impact actions only after a human has approved them (OWASP). In a Shopware setting, this means: the client the assistant works through asks before every write call, or the assistant gets no write tool at all for the live system and only creates a preview that an employee implements.
- Narrow down the task: which items, which field, which target value
- Request a dry run with
dryRun=trueand have the preview output - Check the preview: number of records, affected fields, conspicuous outliers
- Record the approval by an employee in the client or in the ticket
- Trigger the write call with
dryRun=falseand spot-check the result in the Administration
The dry run executes the operation in a transaction and reads the shop data while doing so. It protects against unwanted changes, not against unwanted access. What the assistant should not read is excluded by the allowlist and the role, not by the dryRun parameter.
Prompt injection through product texts and order notes
An agent reads what is in the shop and may treat what it reads like an instruction. The Shopware documentation explicitly warns that tool results with user-generated content such as order notes, customer names or product descriptions can contain text that attempts to redirect the agent. ACL and allowlist limit the blast radius, but they do not prevent the agent from being misled by data it reads (Shopware documentation). OWASP describes this as indirect prompt injection: the model accepts input from external sources such as websites or files (OWASP).
Comments from checkout
What customers write into the comment field later appears in the order and is read along during review.
Product texts from imports
Texts from supplier data or extracted datasheets do not come from your editorial team.
Names and addresses
Master data is input from outside as well and can be phrased like an instruction.
Reviews
Having reviews summarized brings external text into the agent’s context.
The documentation draws a clear conclusion: for workflows that expose customer-supplied data, read-only integrations are preferable, and an agent should not get write access when the task only requires reading (Shopware documentation). An assistant that analyzes orders does not need shopware-entity-upsert, and one for product texts does not need access to orders. Both tasks in one integration connect the riskiest read channel with the strongest write channel. More on attack paths and countermeasures is in our article Prompt injection: securing AI features in your shop.
Data protection: customer data in the context window
Every tool result ends up in the context of the language model and therefore with the service that runs the model. The GDPR requires that, by default, only personal data which are necessary for each specific purpose of the processing are processed (Art. 25(2) GDPR). The separate read permissions for associations since 6.7.14.0 fit this exactly: an assistant that only adds up revenue per day does not need the association to customer data and therefore does not need the order_customer:read permission.
If the model runs at an external service provider, a data processing agreement is usually required that sets out, among other things, the subject matter, duration, nature and purpose of the processing (Art. 28(3) GDPR). Clarify this before an assistant reads the first order, and document for each integration which entities it may read. The same applies to ERP connections, and we design such integrations according to the same principle.
Staging first, then a narrow scope in the live shop
Shopware currently explicitly labels the MCP server as experimental (Shopware documentation). Interfaces, capabilities and extension points may still change based on feedback. How quickly that happens is shown by 6.7.15.0: internal service IDs were renamed, each of the two servers got its own session store, and existing sessions were not carried over (Shopware documentation). That is why every assistant belongs in a staging environment with anonymized test data first, and every update is a reason to test the workflows there again. How we plan updates is described in our article on preparing for Shopware 6.8.
Shopware sets limits of its own for operations. The /api/_mcp endpoint has its own rate limits: 300 calls per minute and 1,000 calls per ten minutes, keyed on the access token and, as a fallback, on the IP address (Shopware documentation). This slows down brute-force attempts on authentication and agents stuck in a loop. Above the limit, Shopware responds with HTTP 429 and states the remaining wait time in the response body, without a Retry-After header (Shopware documentation). In addition, the scheduler must run in production, because a daily task cleans up abandoned toolset sessions (Shopware documentation). On our Shopware hosting, we configure and monitor the cron jobs this requires.
Logging and regular review
An assistant is an access that needs maintenance. The MCP specification recommends that clients log tool usage for audit purposes (Model Context Protocol). Decide where it is kept and who reads it. On the Shopware side, bin/console debug:mcp --integration=SWIA... helps: the command shows the tools from the perspective of exactly one integration and honors its allowlist (Shopware documentation). This lets you check whether the scope still matches what was decided during setup. Our Shopware maintenance installs updates in a copy of the store first, where the scope can be checked after every update.
- List of all integrations with purpose, responsible person and last use
- Compare the allowlist of each integration with the approved task
- Check the ACL role for permissions that go beyond the task or were added by clicking the button for missing permissions
- User accounts with admin rights: no assistant signs in with them
- Read the release notes of every new Shopware version for changes to the MCP server
- Delete unused integrations so that their credentials become invalid
How we set up AI assistants in the Shopware Administration
We set up AI assistants for Shopware so that every layer does its job and the dry run leads into a real approval workflow. The path usually involves three steps.
Inventory
We record existing integrations, roles and user accounts with admin rights and check which of them could reach the MCP endpoint today.
Scope per assistant
A separate integration for each task, an ACL role with minimal permissions and an allowlist without unnecessary write and delete tools.
Staging and approval
Testing in the staging environment, a dry run with approval by your team and a review plan for every Shopware update. More about our services around artificial intelligence.
Whether an assistant in the Administration makes sense depends on the task. Setting delivery times for a product group, finding missing product descriptions or analyzing one day of orders are good candidates, because the result can be checked before it is saved. Payments, cancellations and system settings are better left with the team. A good starting point is our AI automation.
This article is based on the Shopware documentation for the MCP server, the Shopware release notes 6.7.11.0, 6.7.14.0 and 6.7.15.0, the release dates in the shopware/shopware repository on GitHub, the Model Context Protocol specification (revision 2025-11-25), the OWASP Top 10 for LLM Applications 2025 (LLM01, LLM06), the 2025 ICT survey by Destatis and Art. 25 and Art. 28 GDPR. Retrieved on November 3, 2026. The MCP server is experimental, and tools and behavior may change with every version.
From version 6.7.14.0, it is enabled without a feature flag (Shopware Release Notes 6.7.14.0). In 6.7.11.0 to 6.7.13.x, the MCP_SERVER flag has to be set. What an assistant can do with it depends on the integration credentials, the allowlist and the ACL role.
Usually not. The dry run shows the change, but the agent can make the call that saves it itself. The approval belongs in the client or the workflow. In addition, shopware-media-upload has no dry run and uploads immediately (Shopware documentation).
Only partly. An integration created with --admin bypasses the ACL check but still respects its allowlist. A user account with admin rights, on the other hand, bypasses the allowlist completely (Shopware documentation). For assistants, an integration without admin rights and with a dedicated role is therefore recommended.
Since 6.7.15.0, it determines which tools the client sees on the first request for the tool list. It does not grant permissions, the allowlist and the role still decide (Shopware Release Notes 6.7.15.0).
That is a question of purpose. Under Art. 25(2) GDPR, by default only the data necessary for the purpose should be processed. Since 6.7.14.0, Shopware separates the read permissions for associations, such as order_customer:read. If the model runs at an external service provider, a data processing agreement is usually required (Art. 28(3) GDPR).
Shopware labels the server as experimental, and interfaces and behavior may still change (Shopware documentation). A sensible start is a test in the staging environment, followed by a narrow scope in the live shop with approval before every write. We are happy to discuss a suitable workflow via our contact form.