Agent Commerce (MCP)

Storefront & Account MCP Servers

Last updated: October 3, 2026

STOAR ships a built-in Model Context Protocol surface so AI shopping agents — ChatGPT, Claude, and any other MCP client — can discover your store, search its catalogue, answer questions from your published policies, build a cart, quote a real delivered total, and hand the shopper a secure link to finish checkout in their browser. With the customer's explicit consent, an agent can also look up their orders.

It is the same core the storefront and REST APIs run on, exposed as another protocol adapter. Nothing new is invented behind the scenes: a cart built by an agent is a normal guest cart, and a quote comes from the same calculator that runs at checkout, so the number an agent quotes is the number that gets charged.

Two servers #

Server	Path	Auth	Covers
Storefront	`/mcp`	none	store info, catalogue, policies, cart, shipping quotes, guest order lookup
Account	`/mcp/account`	customer token	the signed-in customer's own order history

This is the full shopper-facing tier. Merchant and admin operations — editing products, refunding orders, changing inventory — are deliberately not exposed to agents.

Opt-in, and off by default #

Agent commerce is opt-in. Both servers stay off until you turn them on, and a store that has not opted in answers 404 — it is not even discoverable as an MCP host. Enable them under Manager → Agent Access (MCP), where you also control:

which of the two servers are on;
whether agents must identify themselves before they can act;
cart ceilings (max quantity per line, max lines, max cart value);
how long a handoff checkout link stays valid;
the request rate and result-size limits.

Changes apply on the next request — no deploy. Nothing on either server can place an order, take payment, or change an existing order. Money only moves after a human completes checkout in their own browser.

Quick start #

The server is mounted per store on the request domain, exactly like the REST API:

https://{your-store-domain}/mcp

Point any MCP client at it, or list the tools directly:

curl -s https://app.stoar.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A minimal shopping flow is five calls: learn the store's terms once, find a product, read its variants, build a cart, then quote a delivered total and hand the shopper cart.continue_url.

Tools #

Catalogue

Tool	What it does
`get_store_info`	The store's own terms — where it ships, the currencies it charges and displays, enabled payment methods, the returns window, free-shipping threshold and supported languages. Call once and reuse.
`search_catalog`	Free-text and filtered search, with price, category, stock and sort filters.
`get_product`	Full detail for one product, including the variant matrix needed before adding anything.
`check_availability`	Batch stock re-check for up to 20 items, with in-stock substitutes for anything unavailable.

Policies

Tool	What it does
`search_shop_policies_and_faqs`	Ranked passages from your shipping, returns, privacy, terms, contact and FAQ content — each with a citable URL, answered in the language the agent asked in.

Cart

All cart tools are addressed by the cart_id token returned from create_cart.

Tool	Semantics
`create_cart`	New cart, optionally seeded with line items.
`get_cart`	Full current state.
`add_cart_items`	Additive — quantities add to existing lines.
`update_cart_items`	Absolute quantity per line; `0` removes.
`remove_cart_items`	Drop named lines.
`cancel_cart`	Empty and expire the cart.
`estimate_shipping`	A delivered total per available delivery method, cheapest first, from a country (and postcode where needed).

The cart tools are targeted, not whole-cart replacements: each call names only what it touches, so a confused agent can fail to act but cannot silently drop an item it forgot to resend. Every mutation returns the complete cart. Every mutation is idempotent — replaying the same request returns the original result instead of applying it twice.

Orders

Tool	Where	Notes
`get_order_status`	`/mcp` (guest)	Needs the order number and the lookup token from the confirmation email.
`list_orders` / `get_order`	`/mcp/account`	The signed-in customer's own orders, read-only.

The handoff #

An agent builds a cart it can never pay for. cart.continue_url is how that basket becomes a real purchase: the shopper opens it in their browser, the cart loads into their session, and they land in the normal checkout. The link is signed, time-limited, scoped to one store, and only ever carries a guest cart — never a signed-in customer's basket or saved addresses.

Security model #

/mcp is unauthenticated by design. Everything it exposes is either already public (catalogue, policies) or addressed by an unguessable token (a cart, or one order given its emailed lookup token). No customer record, order history, payment surface or address is reachable without the customer's own credential.
/mcp/account requires a customer token the shopper mints themselves, scoped to a single read-only ability. It is not an admin credential and cannot drive any other API.
Guest order lookup is token-gated, not email + order number. Order numbers are sequential, so an email-based check exposed to a machine would let someone enumerate a stranger's purchase history. The per-order token already lives in the confirmation email, so nothing new is issued and nothing new leaks.
Prices hidden from guests stay hidden. On a B2B store that hides prices from unauthenticated visitors, agents see the same redaction and cart building is disabled rather than producing a basket of unknown value.
Tenancy is resolved from the request domain and cannot be overridden by any argument, so one storefront's agent can never reach another's catalogue or cart.

Measuring it #

When agent access is on, the dashboard shows 30-day agent carts, agent orders, agent revenue (net of refunds) and the top agent by order count — so you can answer the first question anyone asks about agentic commerce: is it selling anything?

How it compares to Shopify #

Shopify deprecated its Storefront MCP in favour of the Universal Commerce Protocol, whose agent checkout is a partner-gated preview. STOAR ships the full shopper-facing surface today, and adds several things UCP has no equivalent for:

get_store_info — agents otherwise guess shipping destinations, payment methods and the returns window.
estimate_shipping — a delivered total from the real checkout calculator, not a bare subtotal.
Guest order lookup — Shopify's is authenticated-only, so guest orders (a large share of real traffic) get nothing.
Targeted cart edits instead of a full-replace update_cart that silently drops any line the agent forgets to resend.
Idempotency on every mutation, not just cancellation.
In-stock substitutes when an item is unavailable.

Current limitations #

No returns, cancellations or address changes over MCP. These are irreversible and belong behind an explicit human confirmation the transport cannot yet guarantee; agents redirect the customer to the account page.
Bundles and subscriptions are readable but not purchasable through an agent — both are flagged so the agent routes the shopper to the product page rather than adding the wrong thing at the wrong price.
Order status is merchant-entered — one tracking number per order, with no live carrier integration, and the status note is labelled as potentially stale.
Policy content follows the storefront's translated pages, so changing it takes a deploy rather than a manager edit.