Module reference

MCP Checkout for Magento 2 — module reference

Covers angeo/module-mcp-checkout 2.1.3 · Checked 16 October 2026 · MIT licensed

MCP Checkout adds six tools to MCP Server, so an AI agent can go from a product search to a placed order in a real Magento store. No browser automation and no scraping. Every limit is checked on the server, at the point where Magento places the order.

This page is the technical reference. For connecting Claude, ChatGPT or Perplexity step by step, see the MCP Checkout user guide.

Tools

The normal flow:

search_products → add_to_cart → get_shipping_methods
  → set_shipping_information → shopper confirms the total → place_order

Each tool declares MCP annotations that match what it does. place_order is the only destructive tool, and the only one marked open-world, because it can call a payment provider. A unit test pins these values, so they cannot drift from the code.

Security model

A limit written in a prompt is a request. A limit checked in PHP before the order is placed is a rule. Since 1.1.0 the checks run in a plugin on CartManagementInterface::placeOrder() — the single point every route to an order passes through.

This matters because the cart_id an agent gets is also valid for Magento’s own guest-cart REST API. Carts made by create_cart are flagged in angeo_mcp_agent_quote, and the plugin applies every limit to them, whichever way the order request arrives. Treat cart_id like a password.

The guardrails:

• Guest only. Carts with a customer, carts of another store view, and carts already ordered are refused.
• Payment allow-list. Default: checkmo (offline). Online methods must be added by hand.
• Order total cap. Default 100, in base currency. Checked when adding items and again with shipping and tax at order time.
• Quantity and line caps. Default 5 per item and 10 lines. The quantity cap applies to the resulting line, so repeated small adds cannot pass it.
• Country allow-list. Default NL. Checked at the estimate, at address save and at order time. Magento’s own allowed countries must also permit it.
• Rate limits. Orders per hour, global and per IP (default 10 each), per store. Slots are reserved before the order and released if it fails. Cloud clients such as Claude share a small pool of IP addresses, so the global cap is the real safety valve.
• Safe retries. The cart is closed once ordered. A retried place_order returns the first order with already_placed: true.
• Order tagging. Each agent order gets a history comment. The client IP is kept only in angeo_mcp_order_log, for seven days.
• Demo cleanup. Off by default. When on, it cancels unpaid agent orders older than 24 hours. Use it on demo and staging only.

Known limits: carts made outside create_cart get only the in-tool checks. The per-IP cap is weak behind a CDN or load balancer. Bearer-token checks belong to MCP Server, so set angeo_mcp/general/require_token deliberately.

Requirements

No payment SDKs are needed. The pay-by-link adapters call the Stripe, Mollie and Adyen REST APIs directly.

Installation

composer require angeo/module-mcp-checkout
bin/magento module:enable Angeo_McpCheckout
bin/magento setup:upgrade
bin/magento setup:di:compile                # production mode only
bin/magento cache:flush

Store settings that are easy to miss

1. MCP Server is on and reachable over HTTPS.
2. Sales → Checkout → Allow Guest Checkout is Yes. This module is guest-only.
3. An allowed payment method is on: Check / Money Order for demos, or Pay by secure payment link (angeo_mcp_paylink) for real money.
4. A shipping carrier (for example Flat Rate) serves your allowed countries.
5. Cron runs, for the cleanup jobs.
6. Products are simple, virtual or configurable. Grouped products return their parts to add one by one. Bundle and downloadable are not supported.

Pay by link (Stripe, Mollie, Adyen)

A card number must never appear in a chat. Pay by link splits the flow:

1. The agent places the order with angeo_mcp_paylink. The order is pending payment.
2. The module asks your payment provider for a hosted payment link. place_order returns it as payment_url, with an expiry time.
3. The shopper pays on the provider’s page. Magento, MCP and the chat never see card data.
4. The provider’s webhook confirms payment. The module checks the signature and moves the order to processing.

Setup:

1. Turn on Pay by secure payment link and add angeo_mcp_paylink to Allowed Payment Method Codes.
2. Choose a provider under Pay by Link and paste its API keys. They are stored encrypted.
3. Register the webhook: – Stripe: https://<store>/angeo-mcp-checkout/webhook/stripe, event checkout.session.completed, and paste the signing secret. – Mollie: nothing to register. The URL is sent with each link. – Adyen: https://<store>/angeo-mcp-checkout/webhook/adyen with an HMAC key (hex).
4. Test with the provider’s test keys first.

If the provider is down, the order still stands. The agent is told the store will follow up, and the failure goes into the order comments. Invoices, captures and refunds are out of scope — use the provider’s official Magento module for those. Zero-decimal currencies (JPY, KRW) are refused rather than charged 100 times too much.

GDPR notes

• The payment provider gets the amount, the currency and the order number. The email only if you opt in. Never the name, address or cart.
• The chat sees the payment URL and the order number. Never payment data.
• angeo_mcp_order_log keeps the client IP for rate limiting and fraud prevention, and deletes it after seven days. For cloud agents that IP belongs to the AI provider, not to the person.

This is engineering documentation, not legal advice.

Configuration reference

All settings are under Stores → Configuration → Angeo → MCP Checkout (AI Agents). The table shows each field, its config path (for bin/magento config:set) and its default value.

General (1)

Setting	Config path	Default
Enable Agent Checkout Tools	angeo_mcp_checkout/general/enabled	No

Order Limits (5)

Setting	Config path	Default
Maximum Order Total	angeo_mcp_checkout/limits/max_order_total	100
Maximum Quantity per Line Item	angeo_mcp_checkout/limits/max_qty_per_item	5
Maximum Line Items per Cart	angeo_mcp_checkout/limits/max_cart_items	10
Maximum Orders per Hour (Global)	angeo_mcp_checkout/limits/orders_per_hour	10
Maximum Orders per Hour (per IP)	angeo_mcp_checkout/limits/orders_per_hour_per_ip	10

Payment (1)

Setting	Config path	Default
Allowed Payment Method Codes	angeo_mcp_checkout/payment/allowed_methods	checkmo

Shipping (1)

Setting	Config path	Default
Allowed Destination Countries	angeo_mcp_checkout/shipping/allowed_countries	NL

Demo Cleanup (2)

Setting	Config path	Default
Auto-cancel Stale Agent Orders (demo only)	angeo_mcp_checkout/cleanup/enabled	No
Cancel After (hours)	angeo_mcp_checkout/cleanup/order_age_hours	24

Pay by Link (Stripe / Mollie / Adyen) (12)

Setting	Config path	Default
Enable Pay by Link	angeo_mcp_checkout/paylink/enabled	No
Provider	angeo_mcp_checkout/paylink/provider	mollie
Link Validity (hours)	angeo_mcp_checkout/paylink/expiry_hours	24
Send Customer Email to Provider	angeo_mcp_checkout/paylink/send_customer_email	No
Stripe Secret Key	angeo_mcp_checkout/paylink/stripe_secret_key	— (stored encrypted)
Stripe Webhook Signing Secret	angeo_mcp_checkout/paylink/stripe_webhook_secret	— (stored encrypted)
Mollie API Key	angeo_mcp_checkout/paylink/mollie_api_key	— (stored encrypted)
Adyen API Key	angeo_mcp_checkout/paylink/adyen_api_key	— (stored encrypted)
Adyen Merchant Account	angeo_mcp_checkout/paylink/adyen_merchant_account	—
Adyen Webhook HMAC Key (hex)	angeo_mcp_checkout/paylink/adyen_hmac_key	— (stored encrypted)
Adyen Live Mode	angeo_mcp_checkout/paylink/adyen_live_mode	No
Adyen Live URL Prefix	angeo_mcp_checkout/paylink/adyen_live_url_prefix	—

Cron and stored data

Adding a payment provider

Implement Angeo\McpCheckout\Api\PaymentLinkProviderInterface and register the adapter in ProviderPool through di.xml.

FAQ

Can an AI agent really place a live order?

Yes. That is what the tools do. This is why every limit is checked inside Magento, not in a prompt, and why the module ships switched off.

What stops an agent from buying a thousand units?

Server-side caps on order total, quantity per item, number of lines and orders per hour. They are checked again inside Magento’s order placement, so they hold even if the order does not come through the place_order tool.

How does the agent pay without card data?

With pay-by-link, place_order returns a link to a page hosted by Stripe, Mollie or Adyen. The shopper pays there. The agent never handles card data.

What happens if the agent retries place_order?

It gets the order that was already placed, marked already_placed: true. The cart is closed at order time, so a second order from the same cart cannot happen.

Why guest checkout only?

So there is no stored account or saved payment data for an agent session to misuse. For signed-in B2B buyers, use MCP Reorder, which fills their cart but never places the order.

Related

• MCP Server — live, read-only catalog tools for AI agents over MCP
• MCP Reorder — reorder and quick order into a signed-in buyer's own cart (B2B)
• UCP Checkout — UCP checkout sessions over REST; the buyer pays on your own checkout
• AI Agent Activity — report on AI agent calls, crawler visits, fake bots and agent-built orders
• MCP Checkout user guide — connecting Claude, ChatGPT and Perplexity
• Agentic checkout — definition
• All module reference pages · Compatibility matrix

This page was written from the README.md, composer.json and etc/*.xml files of tag 2.1.3, read on 16 October 2026. Settings, commands and defaults come straight from that code. If a newer release is out, the README on GitHub wins.