AI shopping agents

A buyer can ask an AI agent to shop for them. With the MCP endpoint in the Checkout SDK, that agent can find your products, build a cart and prepare a checkout in your store, then give the buyer a link to COPE’s checkout page. The buyer accepts your terms and pays there themselves. An agent cannot accept terms or pay on the buyer’s behalf. The endpoint runs on your server, under your domain, with your publishable key. It speaks the Model Context Protocol (MCP), which AI agents use to call tools.

Requirements

A COPE publishable key (cope_pk_live_...).
The success and cancel URLs you use for checkout, registered as redirect URLs in the COPE dashboard.
A server that runs Node.js 20 or later, Bun, Deno, Cloudflare Workers or a Next.js route handler.

Install

npm install cope-sdk @modelcontextprotocol/server zod
npm install @modelcontextprotocol/node   # only for node:http or Express

Create a cart key

The endpoint gives agents an encrypted handle for each cart, so an agent never holds the cart’s secret. Create a 32-byte key for that once, and store it as a server-side secret:

import { generateCartRefKey } from "cope-sdk/mcp"

console.log(generateCartRefKey())

Keep this key out of browsers and source control. Anyone holding it can open and change the carts its handles point to.

Mount the endpoint

On Node.js:

import { createServer } from "node:http"
import { createCopeMcpNodeHandler } from "cope-sdk/mcp/node"

const mcp = createCopeMcpNodeHandler({
  publishableKey: process.env.COPE_PUBLISHABLE_KEY!,
  cartRefKeys: [process.env.COPE_CART_REF_KEY!],
  checkout: {
    successUrl: "https://shop.example.com/thanks",
    cancelUrl: "https://shop.example.com/cart",
  },
  allowedHosts: ["shop.example.com"],
})

createServer((req, res) => {
  if (req.url?.startsWith("/mcp")) return void mcp(req, res)
  res.statusCode = 404
  res.end()
}).listen(3000)

On Bun, Deno, Cloudflare Workers or a Next.js route handler, use the fetch handler instead. It does not need @modelcontextprotocol/node:

import { createCopeMcpHandler } from "cope-sdk/mcp"

const mcp = createCopeMcpHandler({ /* the same options */ })

export function POST(request: Request) {
  return mcp.fetch(request)
}

Agents then connect to https://shop.example.com/mcp.

Options

Option	Required	Meaning
`publishableKey`	Yes	Your `cope_pk_live_...` key
`cartRefKeys`	Yes	Cart keys, base64 or base64url, 32 bytes each. The first one encrypts and all of them decrypt
`checkout`	Yes	`successUrl` and `cancelUrl` for the checkout page. Both must be registered redirect URLs
`allowedHosts`	Yes	Host names the endpoint answers to. Requests for any other host are refused
`allowedOrigins`	No	Browser origins allowed to call the endpoint. Agents that call it from a server are not affected
`rateLimit`	No	`{ perClientPerMinute, perStorePerMinute }`, 120 and 1200 by default, or `false` if you limit requests yourself. Counted in memory, per process
`clientKey`	No	How to tell clients apart for the per-client limit, for example from a trusted proxy’s header

Tools

Tool	What the agent can do
`get_product`	Read a product and its prices
`create_cart`	Start a cart. Returns a `cartRef` that the other cart tools take
`get_cart`	Read the cart with current prices
`add_line`, `update_line`, `remove_line`	Change what is in the cart
`apply_promo_code`, `remove_promo_code`	Apply or remove a promo code
`set_buyer_identity`	Record who is buying and where: email, name, country, postal code, company and VAT ID. Country and postal code decide tax
`start_checkout`	Prepare the checkout and return the link for the buyer. Calling it again returns the same checkout

When a tool fails, its result includes a guidance string telling the agent what to do next.

Rotate the cart key

Add a new key at the front of cartRefKeys and deploy. New handles use it, and existing handles still work.
After your longest-lived carts have expired, remove the old key and deploy again.

Security

The endpoint uses only your publishable key, the same key your storefront already exposes.
Terms, consents and payment happen on COPE’s checkout page, in the buyer’s own browser.

AI agents

Changelog

Reference

AI shopping agents

AI shopping agents

Requirements

Install

Create a cart key

Mount the endpoint

Options

Tools

Rotate the cart key

Security

​AI shopping agents

​Requirements

​Install

​Create a cart key

​Mount the endpoint

​Options

​Tools

​Rotate the cart key

​Security

AI shopping agents

Requirements

Install

Create a cart key

Mount the endpoint

Options

Tools

Rotate the cart key

Security