Skip to main content
This page takes you from an empty client to a working purchase: connect, set the ids, run the flow, and handle each case that can go wrong. For what each tool takes, open its page in the Shopping, Orders and updates, Saved carts, Saved addresses, and Account and stats groups, starting with buy. For the endpoint and credentials, see the overview.

Connect a client

Every snippet sends the same header. The examples read your credentials from the environment variables AGENTCARD_CLIENT_ID and AGENTCARD_CLIENT_SECRET, so no secret lands in a file you commit.
Run this in your terminal:
Terminal
Run claude mcp list to check the connection. The server shows as connected once Agentcard accepts the header.To share the server with a team through the project’s .mcp.json, reference the variables instead of the values:
.mcp.json

Know which clients can’t connect

  • ChatGPT: Custom connectors in ChatGPT authenticate with OAuth or with no authentication, and they don’t send a static Authorization header. The Commerce MCP server doesn’t support OAuth sign-in yet, so ChatGPT can’t connect to it.
  • claude.ai and Claude Desktop custom connectors: Claude’s custom connectors accept fixed credentials in a Request headers field, so you can add the same Authorization header there. A connector has no server of yours to fill in shopper_id and thread_id, so the model chooses them. Use this path to try the server, not to serve shoppers. On Team and Enterprise plans, everyone who uses the connector shares the credentials.

Set the shopper and chat ids

Every tool that acts for a shopper takes two ids that you own: Fill both in on your server, not in the model. A model that invents shopper_id can send one shopper’s cart to another, and one that changes thread_id mid-chat splits a purchase in two.

Set the ids in the AI SDK

Wrap each tool so your code adds the ids before the call leaves your server. The wrapper adds an id only to tools that take it, so get_account and get_stats stay untouched:
agentcard-mcp.ts
For a call such as toolsFor('user_8f3a21', 'chat_5521'), every buy carries shopper_id: "user_8f3a21" and thread_id: "chat_5521", whatever the model sends.

Run a purchase from ask to delivery

The shopper’s words go to buy, and Agentcard answers with the next thing it needs. A purchase moves through these steps:
  1. Ask: Call buy with the shopper’s own words in ask, such as two packs of AA batteries from Amazon, and confirm: false, new_order: false.
  2. Show products: The result holds products, or stores when Agentcard needs the shopper to choose a store. Show each product with its store, price, and link.
  3. Pick: When the shopper chooses, call buy again with their words in ask and that product’s product_id (or that store’s store_id, never both).
  4. Show the cart: Show the store, items, quantities, and total with currency. Say when the total is an estimate.
  5. Confirm only on the shopper’s yes: Call buy with confirm: true once, and only when the shopper says yes to that cart, or asks to check out. “Looks good” is interest, not a yes.
  6. Add a card, for a new shopper: The result has status: needs_card and an add_card link. The shopper opens it and saves a card once.
  7. Approve the payment: The result has status: approval_sent and an approval link. The shopper approves the payment on the approval page with a passkey or Face ID. Your agent can never approve for them.
  8. Order placed: After approval the status moves to placing, then order_placed, and the result carries the order. Only order_placed confirms a purchase.
  9. Follow the order: Call get_updates for what changed, and get_order for where an order stands now.

Know which steps the shopper finishes in a browser

Some stores need the shopper’s own account. In that case the result has next_action: store_login and a store_login link, and the purchase continues once the shopper signs in. When the shopper finishes one of these, get_updates continues the chat’s cart, so the shopper doesn’t type “done”. If they tell you first, call buy again in the same chat.

Read a buy result

A missing field means Agentcard returned nothing, not zero. A link reaches the shopper in one of two ways. Know which your app uses:
  • Your app shows links itself, as buttons or product cards. Never write a link in the reply. When link_sent is true, tell the shopper a link is waiting.
  • Your agent writes the reply, so it hands over every link verbatim, with every query parameter. Never shorten, rewrite, or invent one.
Links belong to one shopper. Never send them to anyone else or store them in notes. An expired link is replaced when you call buy again in the same chat.

Keep within the turn budget

Each buy call answers within about 45 seconds. When turn_continues is true, Agentcard is still working: tell the shopper you’re on it, then read get_conversation or get_updates later. Never send the same buy again.

Handle a busy chat

One buy call runs at a time for each shopper and chat. A second call gets the error busy, and nothing is sent. Read get_conversation, then continue.

Read before you retry

After a timeout, a busy error, or an error with retryable: false, read the current state before you do anything else: If get_conversation shows a last_checkout with an approval link, or an order in orders, the confirm went through. Hand over the link or report the order. If no read settles it, tell the shopper the outcome is unknown and stop. Never send a confirm twice, and never start a new purchase to recover an uncertain one.

Handle errors by code

A failed call returns this shape in the tool result:
Branch on code, never on message. Resend the same call only when retryable is true.

Show money from integer cents

Amounts are integer cents with a currency: { "amount_cents": 1250, "currency": "USD" } is $12.50. Show each amount in its own currency, and never add amounts in different currencies.

Keep going