1. Connect
The MCP server is streamable HTTP athttps://mcp.getagentmall.com. Pass your key as a Bearer token.
https://api.getagentmall.com with the same Bearer header.
2. Create a cart
create_cart returns an empty cart. The id in the response (a ses_ string) is your cart ID for every later call.
This guide uses Walmart. To shop another store, call list_merchants and pass that store’s merchant_id (for example mrc_target or mrc_ocado) here and in search. Every step below is the same.
account: "platform" uses a shared signed-in AgentMall account at the merchant and clears its cart. Omit account for a fresh shopper browser, then call sign_in before checkout.
3. Search
search_catalog returns up to 10 products with id, title, price (integer minor units, cents for USD), url, and availability.
Check titles before using a result. If relevance is "low", the query was ambiguous — retry with a more specific term. For a single product, call get_product with the url and your session_id to get details, reviews, and variant options.
4. Add items to cart
update_cart replaces the entire cart. List every item you want, each with a quantity from 1 to 12. The URL must be the specific variant (size, colour) if the product has options.
The response returns line_items and totals with the live cart contents.
5. Start checkout
create_checkout opens checkout on the merchant site and returns:
line_items— what’s in the ordertotals— subtotal, tax, fees, total (all integer minor units)fulfillment.methods— shipping, delivery, or pickup optionsreview_hash— a fingerprint of this exact review statestatus—"incomplete"until address and payment are set
6. Set address and payment
update_checkout writes the address and card. The card credential.value is an Evervault ev: ciphertext collected through the console vault page. AgentMall never sees the raw card number.
Call with only fulfillment.address first to see estimated tax and total before asking for a card. The response includes an updated review_hash and totals.
7. Place the order
complete_checkout places the order when the review_hash and total_minor match the live review. One approval, one merchant commit. The response includes order.id and status: "completed".
If the review changed since you last read it, you get review_changed with the reason and changes. Nothing was placed. Read the checkout again, show the new review to the user, and confirm again.
If commit_unknown is returned, the order may have been placed. Do not retry. Call get_order with the order ID and wait for confirmation.
Test keys (am_test_) run the full flow — the review is read and checked — but nothing is submitted to the merchant. The order is stored with test: true and no fee is charged.
8. Check the order
get_order returns status, totals, merchant_status, and permalink_url. No session needed.
Next steps
- Sessions and Carts — session lifecycle and cart state
- Checkout — the five-step checkout flow in detail
- Review and Safety — why review_hash exists and how to handle changes
- Error Codes — every error code with recovery guidance
- MCP Tools — full tool reference with inputs and error tables