More and more shopping starts with a question to an assistant: "find me a ceramic mug under €30 that ships to Estonia". If your store can't answer that question in the assistant's own language, someone else's store will.
At Shopemaa, every store on Growth and above can turn on AI channels. When they are on, the store gets its own MCP server at api.shopemaa.com/mcp/{handle}. Claude, ChatGPT and any other MCP client can then search the store, price a cart and send the shopper to pay.
This post walks through how we built it: the decisions we made, the tools we expose, and the parts that took the most thought. The code is Go, simplified from the real service.
Where agentic commerce stands (November 2026)
Before building anything, we looked at what actually works today:
- OpenAI's Agentic Commerce Protocol is still maintained, but in March 2026 ChatGPT moved from in-chat checkout to product discovery that sends shoppers to the merchant's own checkout.
- Google and Shopify's Universal Commerce Protocol (UCP) drives checkout in AI Mode and Gemini from merchant feeds and a
/.well-known/ucpprofile. - Stripe's Agentic Commerce Suite (Shared Payment Tokens) had only previewed support for Connect platforms.
- MCP is the connection layer underneath most of this. It is how assistants call your system.
Every Shopemaa store is its own Stripe Connect account, and most of our merchants are outside the US. So we started with what works everywhere and needs no new payment path.
We split the work into three phases:
- Readable stores: product identifiers (GTIN, MPN, brand, condition), AI product feeds for Google and ChatGPT, and attribution, so we know which orders an assistant sent.
- Acting assistants: an MCP server per store, plus checkout handoff links. This post.
- Native agent checkout: once Stripe supports it for Connect platforms.
Decision 1: the shopper always pays on the store's checkout
This was the most important call, and it simplified everything after it.
The assistant can search, compare, build a cart and quote it. It never takes a payment. Instead, it gets a link that opens the store's own checkout with the cart already filled in. The shopper reviews it and pays there.
That gives us:
- No payment tokens held by agents. Nothing for an assistant to leak or misuse.
- One checkout to trust. The store's normal checkout re-prices everything, applies the store's rules and records the order.
- It works for every merchant today. It needs no new payment rails and no regional support from a payment provider.
A checkout link from an assistant is a capability to fill a cart, nothing more. Its prices are never trusted: checkout prices again.
Decision 2: tools shaped like a shopper's journey
It's tempting to expose your REST API one-to-one. Don't. An assistant needs a few tools that follow how a person shops, with descriptions that tell the model what to call next.
The server exposes six tools:
get_store: the store's name, address, currency and how checkout works.search_products: search by words and/or a collection, with sorting and paging. Returns price, availability and a link.get_product: one product by slug, with every variant id, price and availability (and licences for digital products).list_collections: collections with their slugs and product counts.quote_cart: price a cart exactly as checkout would. Changes nothing.start_checkout: save the cart and return a link to the store's checkout.
Every tool except start_checkout is read-only, and the tool annotations say so. Here is how a tool definition is built, simplified from the service:
func tool(name, description string, input map[string]any, readOnly bool) map[string]any {
return map[string]any{
"name": name,
"description": description,
"inputSchema": input,
"annotations": map[string]any{
"readOnlyHint": readOnly,
"destructiveHint": false,
"idempotentHint": readOnly,
"openWorldHint": false,
},
}
}The descriptions do real work. search_products ends with "Use get_product for variants and details." start_checkout says "Quote the cart first; a cart with unavailable lines is refused." Models follow these hints well, so the tool list itself teaches the flow.
Reuse the storefront, don't rebuild it
None of the tools has its own catalogue or pricing logic. They call the same use cases as the storefront, which gives some guarantees for free:
- Only ACTIVE products are visible, exactly as a shopper on the website would see them.
- Prices include the store's running sales.
- Assistants see availability, never stock counts.
The cart schema is deliberately strict: 1 to 50 lines, quantities from 1 to 999, and either a variant_id or, for digital products, a licence_id:
{
"name": "quote_cart",
"description": "Price a cart exactly as the store's checkout would: lines, discount code, shipping options for a destination, totals and any problems. Changes nothing.",
"inputSchema": {
"type": "object",
"properties": {
"lines": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"properties": {
"variant_id": { "type": "string", "description": "A variant_id from get_product" },
"licence_id": { "type": "string", "description": "For digital products: a licence_id from get_product" },
"quantity": { "type": "integer", "minimum": 1, "maximum": 999 }
},
"required": ["quantity"]
}
},
"discount_code": { "type": "string", "description": "A discount code the shopper has" },
"country": { "type": "string", "description": "Two-letter country code to quote shipping to, e.g. EE" }
},
"required": ["lines"]
},
"annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }
}quote_cart goes through the storefront's own cart pricer. The assistant gets the same prices, sales, discount codes, shipping options and problems as a shopper on the website. If the assistant quotes €27.50, the checkout says €27.50.
Decision 3: checkout handoff links that change nothing
start_checkout is the only tool that writes anything, and it writes as little as possible:
- It quotes the cart first and refuses lines that can't be bought, naming them so the assistant can fix the cart.
- It saves the lines, the applied discount code and which assistant sent the shopper.
- It returns a link to the store's own address:
https://<store>/checkout/handoff/<id>.
func (t *Tools) startCheckout(ctx context.Context, store *Store, args Args, source AgentSource) (any, error) {
quote, err := t.quote(ctx, store, args) // the storefront's own cart pricer
if err != nil {
return nil, err
}
if len(quote.Lines) == 0 {
return nil, ToolError("None of the lines can be bought: " + problems(quote))
}
if names := unavailable(quote); len(names) > 0 {
return nil, ToolError("These can't be bought now: " + strings.Join(names, ", ") +
". Remove them or pick other variants.")
}
handoff, err := t.handoffs.Create(ctx, store, linesOf(quote), appliedCode(quote), source)
if err != nil {
return nil, err
}
return map[string]any{
"checkout_url": handoff.URL,
"expires_at": handoff.ExpiresAt,
"currency": store.Currency,
"estimated_total": money(quote.GrandTotal, store),
"note": "Give this link to the shopper. They review the cart and pay on " +
store.Name + "'s own checkout; shipping is chosen there.",
}, nil
}The rules around a handoff are what make it safe to hand to an assistant:
- It changes nothing in the store. There's no order, no stock reservation and no discount code use. It is a single row.
- The id is unguessable: 24 random bytes, base64url.
- It expires after seven days.
- Opening it needs the storefront's key. Each open is counted, and an unknown, expired or other store's id is a plain 404.
- Checkout re-prices everything and records the order's
agent_source, so the merchant sees which assistant brought the sale.
The note field is there for the model. It tells the assistant exactly what to say to the shopper, which keeps the hand-off honest: you'll pay on the store's site.
Errors the model can fix vs errors it can't
This is the detail that most affects how well an assistant shops.
A mistake the assistant can fix is a tool result, not a protocol error. A missing slug, an unknown product, an empty cart, a quantity of 5,000 or an unavailable variant all come back as a normal result with isError: true and a clear sentence:
{
"jsonrpc": "2.0",
"id": 8,
"result": {
"content": [
{
"type": "text",
"text": "These can't be bought now: Speckled mug (Large). Remove them or pick other variants."
}
],
"isError": true
}
}The model reads that, calls get_product again, picks another variant and retries. If you return a JSON-RPC error instead, most clients show the shopper a failure and the conversation is over.
Protocol mistakes get JSON-RPC errors:
- unparseable JSON:
-32700; - a batch, or a missing
jsonrpcormethod:-32600; - an unknown method:
-32601; - an unknown tool or non-object arguments:
-32602; - anything unexpected:
-32603, logged without the payload.
Successful results carry the data twice: as structuredContent, and as the same JSON in content[0].text. Newer clients use the structured form; older ones still get something to read.
Stateless sessions, signed instead of stored
The server runs on several instances behind a load balancer, so we didn't want session state. But we did want attribution: when an order comes in, which assistant sent it?
Our answer: the initialize response sets an Mcp-Session-Id that is the state. It names the assistant (from clientInfo.name) and is HMAC-signed, so any instance can read it without a shared store:
// Open returns "<source>.<random>.<signature>"; any instance can verify it.
func (s *Sessions) Open(source AgentSource) string {
body := string(source) + "." + strings.ReplaceAll(uuid.NewString(), "-", "")
return body + "." + s.sign(body)
}
// Read returns the assistant for a session id this service signed.
func (s *Sessions) Read(id string) (AgentSource, bool) {
last := strings.LastIndex(id, ".")
if last <= 0 || !hmac.Equal([]byte(s.sign(id[:last])), []byte(id[last+1:])) {
return "", false // not ours: treat the caller as anonymous
}
source, _, _ := strings.Cut(id[:last], ".")
return AgentSource(source), true
}
func (s *Sessions) sign(body string) string {
mac := hmac.New(sha256.New, s.key)
mac.Write([]byte(body))
return base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
}The session is used for attribution only. An id we didn't sign is simply anonymous. Without a session, we fall back to the User-Agent, and anything we don't recognise is recorded as OTHER.
This turned out to be the right direction. The MCP 2026-07-28 specification made the protocol core stateless: it removed the initialize handshake and the Mcp-Session-Id header, and each request now carries its protocol version, client capabilities and client identity in _meta. Our server currently speaks the 2024-11-05 to 2025-11-25 versions. Because nothing depends on server-side sessions, moving to the new revision is mostly a matter of reading io.modelcontextprotocol/clientInfo from each request instead of from a signed id.
The transport: as boring as possible
The server speaks JSON-RPC 2.0 over Streamable HTTP, and keeps to the simplest subset:
- Only `POST /mcp/{handle}`.
GETandDELETEget a 405. - Always a single JSON response. There's no SSE and no server-initiated messages; a shopping tool has nothing to stream.
- Batches are refused, and a notification (a request without an
id) gets a 202 with no body. - Bodies are capped at 64 KB, and each client address gets 120 requests a minute.
It is public, with no OAuth. Assistants connect anonymously, and everything the server exposes is what any visitor to the storefront can already see. The one write, a handoff, changes nothing in the store. Adding an authorization flow would only make it harder for a shopper's assistant to connect.
One rule for who agents can reach
Feeds and MCP share a single access check. A store is reachable by agents only when:
- AI channels are on;
- the store's plan includes them;
- it has an online store with a handle that isn't password-protected;
- it has a store currency.
Every refusal is the same 404 with "No store here". An assistant learns nothing about a store that hasn't opted in, not even that it exists.
Testing it
Anything that speaks MCP can test it. Locally, the MCP Inspector is the fastest way to see the tools and run them from a form:
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:8282/mcp/kiln-and-clayTo shop with a real assistant, Claude Code can reach localhost directly:
claude mcp add --transport http kiln-and-clay http://localhost:8282/mcp/kiln-and-clayThen ask "find me a mug under €30 at Kiln & Clay and give me a checkout link". Claude.ai connectors and ChatGPT connect from the internet, so put a tunnel in front of a local API (for example cloudflared or ngrok) and add the HTTPS URL as a custom connector.
We also have an integration test against a real Postgres that walks the whole flow: an assistant finds a product, quotes a cart and gets a checkout link. It also checks that bad carts come back as tool errors, that protocol mistakes get JSON-RPC errors, and that a store without AI channels has no server at all.
What's next
- UCP. We held back on publishing a
/.well-known/ucpprofile. Advertising an MCP endpoint that doesn't implement UCP's own MCP binding could mislead Google's agents, so the profile ships together with that binding. - Native agent checkout. Phase 3, once Stripe's agent payments support Connect platforms.
- The 2026-07-28 MCP revision, with its stateless core and
server/discover.
If you're building one: a checklist
- Decide where money moves first. Handing off to your own checkout is the simplest safe default.
- Design tools around the shopper's journey, and let descriptions say what to call next.
- Reuse your storefront's use cases so the assistant can never see a price or product your website wouldn't show.
- Make writes as small as possible, and make any link you return expire and be unguessable.
- Return fixable mistakes as tool results with
isError: trueand a sentence the model can act on. - Keep the server stateless. If you need state, sign it or pass it back as an argument.
- Record which assistant sent each order, or you'll never know whether the channel works.
Assistants are becoming a sales channel like any other. The stores that win there will be the ones whose systems answer clearly, price honestly and make the last step obvious: here's your cart, pay on the store's site.
If you sell online and want this without building it yourself, it's built into Shopemaa.