# Claude Commerce Agents on Magento 2: the StorefrontBackend

> How to run Anthropic's Claude Commerce Agents on Magento 2: the StorefrontBackend, what it maps to the REST API, credentials, setup and status.

Source: https://angeo.dev/claude-commerce-agents-magento/
Updated: 2026-10-03

Guide

# Claude Commerce Agents on Magento 2: the StorefrontBackend

**Anthropic's Claude Commerce Agents blueprint needs one class per store platform: a `StorefrontBackend` that turns the catalog, cart and orders into records the agent reads.** [claude-for-commerce-magento](https://github.com/angeo-dev/claude-for-commerce-magento) is that class for Magento 2 and Adobe Commerce, built over the REST API. This guide explains what it maps, how it keeps customer data safe, and how to try it on your store.

**In one sentence**
The blueprint ships the shopping agent; this repository connects it to a Magento store.

## What Anthropic published

In September 2026 Anthropic released [Claude Commerce Agents](https://github.com/anthropics/commerce-agents), an open blueprint for two agents:

- a **shopping agent** a business embeds in its own site or app - it searches, compares, plans, fills the cart and answers order and policy questions;

- a **merchant agent** for staff - it explains performance, fixes listings, handles inventory alerts, and stages every change for a person to approve.

Each agent is defined once - prompt, skills, tool contracts, safety gates - and runs on the Messages API, the Claude Agent SDK or Managed Agents. The blueprint is Apache-2.0 and is a reference implementation: **it is not maintained and does not accept contributions**. Nothing in it places an order or charges a card; checkout hands the cart to the host.

**The one thing you have to write**
The shopping agent reads your store through one Python interface, `StorefrontBackend`. The blueprint ships the agent; it does not ship the code that turns your catalog, cart and orders into the records the agent reads. For Magento, that class is [claude-for-commerce-magento](https://github.com/angeo-dev/claude-for-commerce-magento).

## What the Magento backend does

`MagentoStorefrontBackend` implements every method of the contract over Magento's REST API:

| Agent capability | Magento REST |

| `search_products` | `/V1/search` with `quick_search_container`, so results match the site's own search; falls back to a name and SKU filter if the search engine is down |

| `get_product_details` | `/V1/products/{sku}`, plus `/V1/configurable-products/{sku}/children` for variants |

| cart methods | `/V1/guest-carts` for guests, `/V1/carts/mine` for signed-in customers |

| `get_preferences` | `/V1/customers/me`, customer group as loyalty tier |

| `get_orders`, `get_order` | `/V1/orders`, always filtered to the session's own customer |

| `search_policies` | `/V1/cmsPage/search` over active CMS pages |

| `get_fulfillment_options` | `/V1/guest-carts/{id}/estimate-shipping-methods` |

| `checkout_handoff` | the storefront cart, or a payment link from `angeo/module-mcp-checkout` |

It covers the **shopping agent** only. The merchant agent needs a separate `MerchantBackend` over analytics, catalog, inventory and pricing, which this repository does not provide.

## Three design decisions worth knowing

### Two credentials

The blueprint forbids any tool argument that carries a customer id. So the backend uses a Magento **integration token** for catalog, CMS, customer and order reads, and the **customer's own token** only for their cart and profile. Order reads are filtered by the session's customer server-side: an order id the model invents for someone else returns nothing.

### Sign-in is a state, not an empty list

For a guest, order history raises `SignInRequired` instead of returning `[]`. An empty list would tell the agent the customer has no orders; the exception makes it ask the customer to sign in.

### Product types

- `simple`, `virtual` and `downloadable` are plain records.

- `configurable` is a family: options from the variation attributes, variants from the children, price from the cheapest in-stock child.

- `grouped` and `bundle` are excluded by default. Offered as buyable records, they would make the agent build carts Magento refuses.

- Ratings stay empty unless a review extension fills them. Magento core has no review summary on the product payload, and a fake zero is worse than no number.

## Set it up

You need Python 3.11 or later and a Magento integration token (**System > Extensions > Integrations**) with read access to Catalog, Sales, Customers and CMS Pages, and write access to Carts.

```
git clone https://github.com/anthropics/commerce-agents.git
git clone https://github.com/angeo-dev/claude-for-commerce-magento.git

cd commerce-agents && ./scripts/install.sh && cd ..
cd claude-for-commerce-magento && pip install -e ".[dev]"
cp .env.example .env        # MAGENTO_BASE_URL, MAGENTO_ACCESS_TOKEN, ANTHROPIC_API_KEY

pytest                                   # fixtures only: no store, no API key
python examples/smoke.py "backpack"      # your real store, still no model
python examples/run_turn.py --trace "do you have a grey backpack?"
```

Run `smoke.py` first. It calls every backend method against your store and costs nothing, because it uses no model. The catalog mapping is where a real store surprises you.

**Status: v0.1.0**
Every method is implemented and unit-tested, but against fixtures. The mapping has not yet run on a production catalog with a real attribute set, several store views, or enough variants to hit the cap. Expect to adjust the mapping for your store.

## Where the angeo modules fit

The backend works on a plain Magento 2.4 with nothing else installed. Two modules extend it:

- [angeo/module-mcp-checkout](https://angeo.dev/modules/mcp-checkout/) issues a payment link for the cart (`MAGENTO_MCP_CHECKOUT_PAYLINK=1`), which an agent running outside the shop needs.

- [angeo/module-mcp-server](https://angeo.dev/modules/mcp-server/) is a Magento-native MCP server. On Managed Agents, use it instead of the blueprint's Python storefront MCP server: there is no second service to run.

## Store agent or assistant agent?

This is an agent **you** run, on your site, on your terms. It is not the same as being found by ChatGPT or Gemini: for that, the store needs crawler access, structured data and a feed. The two work together - see [commerce agent](https://angeo.dev/commerce-agent-definition/) and [agentic checkout](https://angeo.dev/agentic-checkout-definition/) for the difference.

## Questions

What is Claude Commerce Agents?
An open reference blueprint from Anthropic for two agents - a shopping agent for customers and a merchant agent for staff - that run on the Messages API, the Claude Agent SDK or Managed Agents. It is Apache-2.0, not maintained and does not accept contributions.

Does Claude Commerce Agents work with Magento?
Yes, through a StorefrontBackend implementation. `claude-for-commerce-magento` implements it over Magento's REST API for Magento Open Source and Adobe Commerce 2.4.

Does the agent place orders in Magento?
No. The blueprint never places an order or charges a card. `checkout_handoff` sends the cart to the storefront or to a payment link, and the order is created in Magento.

Do I need the angeo modules?
No. The backend works on plain Magento 2.4. `angeo/module-mcp-checkout` adds payment links, and `angeo/module-mcp-server` replaces the blueprint's Python MCP server on Managed Agents.

Is it production-ready?
Version 0.1.0 is complete and unit-tested against fixtures, but has not yet run on a production catalog. Run `examples/smoke.py` against your store first and expect to adjust the catalog mapping.

Does it include the merchant agent?
No. It implements StorefrontBackend for the shopping agent. The merchant agent needs a separate MerchantBackend.

## Related

- [Commerce agent - definition](https://angeo.dev/commerce-agent-definition/)

- [Agentic checkout - definition](https://angeo.dev/agentic-checkout-definition/)

- [MCP for Magento](https://angeo.dev/magento-mcp-server/)

- [Module: MCP checkout](https://angeo.dev/modules/mcp-checkout/)

- [Magento MCP servers compared](https://angeo.dev/magento-mcp-servers-compared/)

- [Claude places a real Magento order via MCP](https://angeo.dev/ai-agent-checkout-in-magento-2-claude-places-a-real-order-via-mcp/)

## Sources

- [Anthropic: Claude Commerce Agents (reference blueprint)](https://github.com/anthropics/commerce-agents)

- [angeo-dev/claude-for-commerce-magento](https://github.com/angeo-dev/claude-for-commerce-magento)

- [Shopify: claude-for-commerce-examples](https://github.com/Shopify/claude-for-commerce-examples)

Checked 24 September 2026 against the READMEs of anthropics/commerce-agents and angeo-dev/claude-for-commerce-magento v0.1.0. Disclosure: we build claude-for-commerce-magento and the angeo modules. Anthropic did not review this page.

## More on this topic

- [MCP 2026-07-28 Without Sessions: What Changes for Magento](https://angeo.dev/mcp-2026-07-28-magento/)
- [Merchant of Record - Definition](https://angeo.dev/merchant-of-record-definition/)
- [MCP for Commerce - Definition](https://angeo.dev/mcp-commerce-definition/)
- [AP2 (Agent Payments Protocol) - Definition](https://angeo.dev/ap2-definition/)
- [MCP Modules for Magento 2  -  Configuration Reference](https://angeo.dev/docs/mcp/)
- [MCP Checkout for Magento 2: Claude, ChatGPT, Perplexity](https://angeo.dev/docs/mcp-checkout/)