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 variablesAGENTCARD_CLIENT_ID and AGENTCARD_CLIENT_SECRET, so no secret lands in a file you commit.
- Claude Code
- Cursor
- AI SDK
- Other MCP clients
Run this in your terminal:Run
Terminal
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
Authorizationheader. 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
Authorizationheader there. A connector has no server of yours to fill inshopper_idandthread_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, soget_account and get_stats stay untouched:
agentcard-mcp.ts
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 tobuy, and Agentcard answers with the next thing it needs. A purchase moves through these steps:
- Ask: Call
buywith the shopper’s own words inask, such astwo packs of AA batteries from Amazon, andconfirm: false,new_order: false. - Show products: The result holds
products, orstoreswhen Agentcard needs the shopper to choose a store. Show each product with its store, price, and link. - Pick: When the shopper chooses, call
buyagain with their words inaskand that product’sproduct_id(or that store’sstore_id, never both). - Show the cart: Show the store, items, quantities, and total with currency. Say when the total is an estimate.
- Confirm only on the shopper’s yes: Call
buywithconfirm: trueonce, and only when the shopper says yes to that cart, or asks to check out. “Looks good” is interest, not a yes. - Add a card, for a new shopper: The result has
status: needs_cardand anadd_cardlink. The shopper opens it and saves a card once. - Approve the payment: The result has
status: approval_sentand anapprovallink. The shopper approves the payment on the approval page with a passkey or Face ID. Your agent can never approve for them. - Order placed: After approval the status moves to
placing, thenorder_placed, and the result carries the order. Onlyorder_placedconfirms a purchase. - Follow the order: Call
get_updatesfor what changed, andget_orderfor 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.
Send links the right way
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_sentistrue, 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.
buy again in the same chat.
Keep within the turn budget
Eachbuy 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
Onebuy 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, abusy 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: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
- Look up every argument on each tool’s page, starting with
buy. - Load Agentcard’s rules into your model with the shopping skill.
- Give your model the same rules in your own prompt: Give your model Agentcard’s instructions.