Looking for how to connect an assistant? Connection flows for Claude, ChatGPT, Perplexity, Grok and Mistral, example prompts, the safety model and troubleshooting live in MCP Checkout for Magento 2. This page is the configuration and extension reference: agent presentation, conversation starters, the tool SPI, and what the modules deliberately do not do.
These two MIT-licensed modules turn a Magento 2 store into a Model Context Protocol server: an endpoint an AI assistant can connect to in order to browse your catalogue, build a guest cart, quote real shipping and place an order — all against live data, with no feed and no cache in between.
In short. module-mcp-server exposes four read-only tools (catalogue search, product details, categories, store info). module-mcp-checkout adds six write tools that complete a guest purchase. Both run on Magento Open Source and Adobe Commerce 2.4.x, install via Composer, and are configured entirely from the Admin. Authentication is a Magento Integration token; for public shopper access you put an OAuth 2.1 layer in front.
What these modules do
Model Context Protocol (MCP) is the standard an AI assistant uses to call external tools. It was released by Anthropic in November 2024 and moved to neutral governance under the Linux Foundation in December 2025; OpenAI, Google and Microsoft have all adopted it. In commerce it is now the layer that lets an assistant read a live catalogue rather than a stale feed.
A Magento store with these modules installed answers MCP requests at a single endpoint. An assistant connected to it can:
Read the live catalogue
Keyword search with category, price range, pagination and sorting. Full product cards by SKU, including configurable variants. Category tree with product counts.
Build a guest cart
Create a cart, add simple, virtual and configurable products by SKU, read back line items and totals.
Quote real shipping
Carrier rates for an actual destination country and postcode — the same rates your storefront would show, not an estimate.
Place an order
Set shipping and contact details, then create the order. Payment completes on a provider-hosted link, so card details never enter the conversation.
Nothing here is a feed export or a scheduled sync. Every call reads the same models your storefront reads, at request time.
How this differs from Adobe’s Commerce MCP
Adobe announced a Commerce MCP Server at Summit 2026, so the obvious question is why these modules exist. The two solve different problems.
| Adobe Commerce MCP | angeo modules | |
|---|---|---|
| Audience | Developers building integrations | Shoppers buying through an assistant |
| Coupling | Commerce Integration Starter Kit, App Builder | Plain Magento module, Composer install |
| Platform | Adobe Commerce as a Cloud Service | Magento Open Source and Adobe Commerce 2.4.x, on-prem or cloud |
| Licence | Adobe commercial | MIT |
| Checkout | Not the goal — it is a developer accelerator | Guest checkout to a real order |
If you are on ACCS and building integrations with App Builder, Adobe’s server is the right tool. If you run Magento Open Source and want an assistant to be able to sell, these modules are what fills that gap today.
Where the pieces sit
Two separate credentials, two trust boundaries. The shopper’s token is validated at the edge and stops there; Magento is called with the proxy’s own credential. That separation is what the MCP specification means when it forbids token pass-through, and it is the reason a compromised shopper session cannot reach further than one guest cart.
Installation
Requirements
- Magento Open Source or Adobe Commerce 2.4.x
- PHP 8.2, 8.3 or 8.4
- HTTPS with a valid certificate — assistants refuse anything else
composer require angeo/module-mcp-server
composer require angeo/module-mcp-checkout # optional: adds cart + checkout
bin/magento module:enable Angeo_McpServer Angeo_McpCheckout
bin/magento setup:upgrade
bin/magento setup:di:compile # required in production mode
bin/magento cache:flushAdmin configuration, bearer-token setup and order guardrails are covered in the checkout documentation. What follows here is everything that is specific to the 1.3.0 server release.
Full-page cache. The MCP endpoint must never be cached. Every response is state-dependent and several carry a session identifier. Confirm your FPC and any CDN in front of it bypass the endpoint path entirely — a cached initialize response breaks every session that follows it.
The endpoint is then live at https://your-store.example/mcp. Nothing is exposed publicly until you configure authentication, which is covered below.
Tool reference
Ten tools when both modules are installed. Each declares MCP tool annotations, so a client can group them by risk and apply different approval rules to reads and writes.
| Tool | Module | Writes? | What it does |
|---|---|---|---|
search_products | server | No | Keyword search with optional category, price range, pagination, sorting. Returns SKUs, live prices, stock and canonical URLs. |
get_product | server | No | Full product card for one SKU, including configurable variants and their option values. |
list_categories | server | No | Active category tree with URLs and product counts. |
get_store_info | server | No | Name, currency, locale, countries shipped to, and links to llms.txt and the UCP profile. |
create_cart | checkout | Yes | Opens an empty guest cart and returns the cart_id every other checkout tool needs. |
add_to_cart | checkout | Yes | Adds by SKU. Handles configurable products by variant SKU or parent SKU plus an options map. |
get_cart | checkout | No | Line items, quantities, prices, subtotal and grand total. |
get_shipping_methods | checkout | No | Real carrier rates for a destination country and postcode. |
set_shipping_information | checkout | Yes | Address, contact details and chosen method. Returns available payment methods and final totals. |
place_order | checkout | Yes | Creates the order. Idempotent: a repeat call for the same cart returns the existing order, never a duplicate. |
Payment never happens in the conversation. place_order returns a payment_url pointing at your provider’s hosted page (Stripe, Mollie, Adyen and similar). The assistant shows the link; the shopper pays there. No card or bank details are ever exchanged as chat text, and none reach the model.
Product types
Simple, virtual and configurable products are supported end to end. Grouped products cannot be added as a single unit — the error response lists their component SKUs so the assistant can add them individually. Bundle and downloadable products are not supported.
Agent presentation settings
Stores → Configuration → Angeo → MCP Server → Agent presentation.
These four settings decide what an assistant reads about your store before it decides whether to use your tools at all. They change nothing about what the tools do, and everything about how findable they are.
| Setting | Default | Effect |
|---|---|---|
| Store name for agents | Store view name | The name the assistant matches a shopper’s request against. Falls back to the website name when the store view is still called something generic. |
| Agent instructions | empty — generated | Built from the store name and the tools actually installed, so it stays accurate when you add or remove the checkout module. |
| Add store name to tool descriptions | Yes | Appends the store name to each description, so a shopper with several connectors can be told apart. |
| Generate tool titles | Yes | Human-readable titles for the client’s permission screen, e.g. “Search Acme Outdoor products”. |
Set the store name. It is the highest-leverage field on this page. “Default Store View” gives an assistant nothing to recognise; the name your customers actually use gives it something a shopper will type. Running bin/magento angeo:mcp:tools warns you when no usable name is configured.
Conversation starters
Since 1.3.0 the server also implements the MCP prompts capability — ready-made requests a client can offer the shopper after connecting, with your store’s name already in the text:
- Browse store — categories and a sense of the range
- Find something in store — a live catalogue search for whatever they type
- About store — shipping, currency, policies
- Buy from store — find, cart, shipping, checkout (only when the checkout module is installed)
A prompt is an offer, not an action. No MCP server can start a conversation turn or inject a message — deliberately, or any connected server could speak first. Clients also surface prompts to the user rather than to the model, so the assistant will not suggest one unprompted. What they remove is the guessing: the shopper no longer has to find a phrasing that beats the client’s own product search.
Client support varies. The server advertises the capability and answers prompts/list and prompts/get correctly. Whether a given assistant displays them is up to that client. Where it does not, the tools still work exactly as before.
Authentication and exposure
Out of the box the endpoint authenticates with a Magento Integration token. That is right for your own tooling, an internal assistant, or a single trusted client. It is not right for the public: an Integration token is a long-lived bearer credential with no per-shopper identity, no consent step and no revocation short of deleting the integration.
For public shopper access you put an OAuth 2.1 layer in front of the store. Practically that means a resource server that:
- publishes RFC 9728 protected-resource metadata and RFC 8414 authorization-server metadata, with the issuer matching byte for byte
- validates each token’s signature, issuer, expiry, audience (RFC 8707) and scope on every request
- presents a consent screen a human actually clicks
- never forwards the shopper’s token upstream — it calls Magento with its own separate credential
That last point is not optional. The MCP specification forbids passing a client’s token through to a downstream system; doing so makes the server a confused deputy. Two credentials, two trust boundaries.
If you build that layer yourself, read what actually breaks when you ship an MCP connector first. Every failure documented there produced a working-looking connector with a silent, hard-to-diagnose fault.
Extending with your own tools
Implement Angeo\McpServer\Api\ToolInterface and register the class in the ToolRegistry pool in your module’s di.xml:
<type name="Angeo\McpServer\Model\Tool\ToolRegistry">
<arguments>
<argument name="tools" xsi:type="array">
<item name="my_tool" xsi:type="object">Vendor\Module\Model\Tool\MyTool</item>
</argument>
</arguments>
</type>Optionally implement ToolAnnotationsInterface to declare readOnlyHint, destructiveHint and idempotentHint. Clients use these to group tools and to decide which need explicit approval — a write tool that does not declare itself is a write tool a shopper approves by accident.
Conversation starters work the same way: implement PromptInterface and add it to PromptRegistry. The built-in starters are StorePrompt virtual types configured entirely in di.xml, so adding one needs no PHP at all.
Store-name anchoring and generated titles are applied centrally when tools are listed, so anything you register through the SPI inherits them without changes.
Verifying the install
# Full protocol dump: capabilities, instructions, every tool and schema
bin/magento angeo:mcp:tools
# One tool, with arguments
bin/magento angeo:mcp:tools search_products '{"query":"backpack"}'Three things to check in the output:
capabilities.toolsis present. If it is missing, a client concludes there are no tools and never asks for the list — which surfaces as “this connector has no tools available” with no error anywhere.- The instructions name your store and describe what it can actually do. If they still say “read-only” while the checkout module is installed, the store name is unset or the config did not reach the server.
- Tool descriptions end with your store name when description anchoring is on.
Then connect a real client and walk the whole flow, including authorization. The MCP Inspector (npx @modelcontextprotocol/inspector) shows each HTTP step and is far better at diagnosing a broken handshake than any assistant’s error message.
Known limits
- Guest checkout only. No customer login, no saved addresses, no order history. A guest cart and a pay-by-link order.
- Bundle and downloadable products are not supported in the cart. Grouped products must be added component by component.
- Prices are the public customer group’s unless configured otherwise. Customer-group pricing, B2B catalogues and negotiated quotes are not exposed.
- Protocol revision. The server negotiates
2025-06-18. Clients on newer revisions negotiate down, which works, but the newer transport headers are not yet required or enforced. - Tool selection is not guaranteed. An assistant decides whether to use your tools before it calls anything. Requests about your store reach the connector reliably; a cold, unanchored shopping request often goes to the assistant’s own product search instead. This is covered honestly in the FAQ below.
FAQ
Does this work on Magento Open Source, or only Adobe Commerce?
Both. Magento Open Source and Adobe Commerce share a codebase, so the modules install identically on 2.4.x, on-premise or cloud. Adobe’s own Commerce MCP Server targets Adobe Commerce as a Cloud Service and the App Builder toolchain, which is a different platform and a different audience.
Can an AI agent actually place a real order?
Yes. place_order creates a genuine Magento order in pending status and returns a payment link. The shopper completes payment on the provider’s hosted page. The order is real from the moment it is placed; the payment is real once the shopper pays.
Are card details ever sent to the AI model?
No. Payment is handed entirely to the payment provider through a hosted link. No card or bank details are exchanged as conversation text, so none reach the model, the connector or your Magento logs.
Will an assistant automatically use my store instead of searching the web?
For anything about your store, yes — catalogue questions, cart state, shipping, policies. For a cold generic request that names no shop (“find me a grey backpack”), often no: that competes with the assistant’s own product search, and one store reasonably does not win a question about the whole market. Setting the store name and installing the checkout module both improve the odds; neither guarantees the outcome. The realistic path is a shopper who arrives already in your store’s context.
Do I need OAuth, or is the Integration token enough?
The Integration token is enough for your own tooling and internal assistants. For public shopper access you need OAuth 2.1 in front: an Integration token is long-lived, carries no per-shopper identity, has no consent step, and cannot be revoked individually.
How is this different from a product feed?
A feed is a periodic export an assistant reads from someone else’s copy. MCP is a live call into your store at the moment the question is asked. Prices, stock and availability are whatever they are right now, and the same endpoint can also transact — which no feed can.
What does it cost?
The modules are MIT-licensed and free, including commercial use. The only costs are your hosting and, if you expose the endpoint publicly, whatever you use for the OAuth layer.
Does this replace UCP or ACP?
No — they sit on different floors. MCP is how an assistant calls a tool. UCP and ACP are commerce-specific discovery and checkout protocols with their own surfaces. A store can implement several; they compose rather than compete.