Shopware Merchant Agent: What Stops It Breaking Your Shop

A Shopware merchant agent is a different proposition from a shopping agent. One reads your catalog and answers buyer questions. The other holds credentials to your admin and can change what your products cost.

Shopware published a working example of the second on September 4, 2026. What makes it worth reading is the machinery sitting between the model and your database.

I have not run the agent hosts on a client shop, so the guardrail and ledger behaviour below is read from Shopware’s own reference implementation. The Shopware side I did check: the Admin MCP surface, the tool list and the dry-run contract are all verified against a 6.7.13.0 shop, and I have flagged the one claim that did not survive the test.

What a Shopware merchant agent actually does

The repository pairs two agents against one Shopware 6.7 shop, both running Anthropic’s Commerce Agents blueprint. I took the shopping half apart in the UCP setup post. The merchant half talks to the Admin API instead of the storefront.

The loop is plain enough. An operator asks something in prose: what needs attention this morning, which products are low on stock, raise the olive oil by 50 cents. The agent answers from live data, and when the request implies a write it returns a staged change card carrying a before value, an after value, a guardrail note, and two buttons.

The reads come from Shopware’s own aggregation tooling. Revenue and order counts are a shopware-entity-aggregate call over order for the current period and the one before it, with cancelled orders excluded. Slow movers are a terms aggregation over order_line_item.productId with a nested sum of quantity across a 30 day window. Low stock is a threshold file, default 8, overridable per product.

Staging a change writes nothing. That is the part worth understanding.

Shopware’s Admin MCP dry run is the whole trick

Shopware’s Admin MCP server puts a dryRun flag on its write tools and defaults it to true. On a 6.7.13.0 shop that flag sits on exactly five tools: shopware-entity-upsert, shopware-entity-delete, shopware-order-state, shopware-system-config-write and shopware-theme-config, each with default: true in its input schema. shopware-media-upload is the exception worth knowing about. It writes, and it carries no dryRun at all.

The dry run is a real write. Shopware executes it inside a transaction, rolls the transaction back, and reports which rows it would have touched. The before and after values on that card are the server’s verdict rather than something the model worked out.

That is testable, so I tested it. A dry-run upsert setting a product’s stock to 999 came back listing the product and product_translation rows it would have written, and the database still read 50 afterwards. Then I sent one carrying a taxId that does not exist:

{"success": false, "error": "An exception occurred while executing a query:
  SQLSTATE[23000]: Integrity constraint violation: 1452 Cannot add or update
  a child row: a foreign key constraint fails (`db`.`product`, CONSTRAINT
  `fk.product.tax_id` FOREIGN KEY (`tax_id`) REFERENCES `tax` (`id`))"}

That is MySQL refusing the write, surfaced through the dry run. Something that only inspected the payload could not produce it.

Two consequences follow, and both matter more than the chat window does.

A payload Shopware would reject fails at stage time. Malformed write, missing nested row, tripped constraint: the change is refused with Shopware’s own message while the operator is still looking at the screen. The failure lands somewhere a person can read it.

The stored payload is what gets applied. Staging writes the exact payload into a ledger, and apply replays that payload with dryRun=false. The model gets no second turn to regenerate it between preview and write. What you approved is what runs.

Three gates between the model and the database

• Guardrails, checked twice. Price delta, discount depth, restock size, protected fields and items per change are enforced when a change is staged and enforced again when it is applied. A change that sat in the ledger while the underlying product moved gets re-checked instead of trusted.
• Host approval. MERCHANT_REQUIRE_HOST_APPROVAL=1 is the default. Apply is an HTTP route that requires a change the host has already marked approved, and both apply and discard refuse anything that is not in the STAGED state.
• Identity. The host authenticates as a Shopware Integration over client_credentials with its own ACL role. The admin password grant is explicitly not accepted. If the host is compromised, what leaks is a scoped integration.

The permission list is the real boundary

Everything above is application logic, and application logic has bugs. The ACL role is the layer Shopware enforces whatever the application does.

The integration’s Admin MCP tool allowlist is six core tools:

shopware-entity-search
shopware-entity-read
shopware-entity-aggregate
shopware-entity-upsert
shopware-entity-delete
shopware-entity-schema

Underneath sits the privilege list: product:read and product:update, the promotion and rule families needed to build a campaign, and read-only access to order, order_line_item, order_transaction and order_delivery. customer:read is absent, because no call the merchant agent makes needs it. So is product_manufacturer:read.

That absence is the useful part. Shopware’s data layer re-checks every nested row a write touches through AclWriteValidator, so creating a promotion needs the nested privileges spelled out one by one. Handing an agent a broad role and hoping the application layer holds it back is a choice, and it is not one you are forced into.

The role template also ships a maker-checker split: one role that stages changes without agent_change:update, a separate approver role that has it, for shops that want the approval to happen inside Shopware rather than in a separate portal. That is the shape most merchants I talk to would actually want.

Where it still falls short

• Traffic and conversion come back as unavailable, with a note saying why. Shopware has no traffic source, so the agent cannot answer the question most merchants ask first.
• The merchant evaluation set passes 34 of 38 cases after a round of prompt work, up from 23. That is a demo-grade number, and the repository reports it as one.
• SwagCommerceAgentTools, the plugin that moves these capabilities into Shopware proper, is a first increment and is not yet installed in the project’s own shared container.
• The UCP SDK under the shopping half is version 0.0.5. Pre-1.0 means breaking changes are coming.
• Shopware labels the MCP server experimental, in the feature flag’s own description in core. Treat the tool names and shapes as a moving target.

This is a reference implementation. Nobody should put it on a client shop this quarter, and the repository does not suggest otherwise.

What is buildable today

Take the model out and look at what remains: a staged-change ledger, an ACL-scoped integration, server-validated previews, and an approval route. All four are available on Shopware 6.7 right now, and none of them need an AI agent to earn their keep.

It is the same architecture as approval-gated automation I have already shipped. Zero-touch order processing for a German dropshipper runs the same shape with a rules engine in the driver’s seat, and the agent readiness auditor scores a catalog against Shopware’s feed validator without ever writing to the shop. If you are earlier than that, what agentic commerce means for store visibility is the place to start.

My advice to anyone weighing this: build the gates first. The gates are the durable part. Whatever model sits behind them will be replaced twice before the ledger schema changes once.

If you want the approval workflow built, with or without an agent driving it, get in touch.

Frequently asked questions

What is a Shopware merchant agent? It is an AI agent pointed at Shopware’s Admin API instead of the storefront. It reads sales figures, low stock and order problems through Shopware’s aggregation tooling, and when you ask for a change it proposes a price, stock or promotion update as a staged change with a before and after preview. A human approves it before anything is written.

Can an AI agent change prices in Shopware without approval? Not in Shopware’s reference implementation. Staging writes nothing: the real payload runs through Admin MCP with dryRun=true, which Shopware executes in a transaction and rolls back. Applying it is a separate route that requires a change the host has marked approved, and the default configuration gives the model no path to dryRun=false. Whether your own setup behaves that way depends entirely on how it was built.

What does dryRun do on Shopware’s Admin MCP? Five write tools carry dryRun and it defaults to true. shopware-media-upload writes without one. Shopware runs the write inside a transaction, rolls it back, and reports which rows it would have touched, so the preview is the server’s own verdict and a payload Shopware would reject fails while someone is still looking at it.

Which Shopware version do I need for Admin MCP? 6.7.11 through 6.7.13 ship the MCP server behind the MCP_SERVER feature flag, off by default. Where the value has to live depends on the stack: a ddev container environment variable was enough on my lane, while Shopware’s notes describe a dockware setup where only the project .env worked over HTTP. On 6.7.14 the flag goes away and the tool list becomes progressive. Shopware 6.5 and 6.6 have no MCP server in core.