Guide: connect an assistant

Goal: an AI assistant (Claude, Cursor, your own) discovers products across every Artos store, completes a real purchase, and tracks the order — on card or crypto — without you writing transport code or holding any credentials.

Who this is for: you want an assistant to shop, not to be the platform. If you are building your own commerce client, see the Shopping agent (SDK) guide instead.

The hosted bridge at https://agent.artos.sh/mcp owns the platform key, AP2 signing, and the crypto rail. The only credential in play is the buyer’s own OAuth bearer, minted when the buyer consents.

Connect the client

The exact connection steps (Claude Connector, Cursor via mcp-remote, example prompts, and the tool-by-tool happy path) live in the Quickstart. In short:

• Claude (production): Settings → Connectors → add https://agent.artos.sh/mcp. Anthropic runs OAuth with its own CIMD client; the buyer consents in My Artos.
• Cursor / local dev: connect via mcp-remote; see Local development for dev TLS + CIMD.

Then try: “Search for running shoes under $100, then buy the cheapest pair and ship to my default address.”

Actors

The sequence

Step by step

1. Consent once (OAuth). The buyer signs in at My Artos  and authorizes the agent via OAuth 2.1 + PKCE. With offline_access the agent gets a refresh token, so it stays connected without re-consent. See Authentication.
2. Load buyer context. Call get_buyer_context first — it returns the buyer’s default shipping address, order history, wallet balances, and spend caps, so the agent can ship and pay without interrogating the buyer.
3. Discover. search_products searches every Artos store in one call. Each result carries metadata.artos_seller.slug — the store to route the checkout to. There is no universal cart; buy per store, sequentially.
4. Build a checkout. create_checkout with the store_slug and items. The server re-prices and advertises the enabled rails.
5. Confirm the purchase. confirm_purchase re-prices, verifies the store’s signed merchant_authorization, mints the AP2 mandate, routes the rail, and completes — one call. The outcome is one of completed, escalation_required (open the continue_url), or payment_selection_required (ask the buyer which rail, then retry).
6. Track the order. list_my_orders / get_my_order read the buyer’s orders across every store from their account — distinct from the store-scoped get_order, which needs a platform key minted with the orders:read permission (Authentication).

Which tools place an order?

The bridge tags every tool with an MCP annotation so a host can reason about safety. All the reads (search_products, get_product, get_cart, get_buyer_context, list_my_orders, …) are read-only; cart and checkout writes are additive; only confirm_purchase is marked destructive — it is the one call that places the order and moves money. A well-behaved client will confirm with the buyer before invoking it.

The one extra step crypto needs

Card checkout works with OAuth consent alone. Crypto checkout needs one more thing: the buyer must authorize the agent under My Artos → Agents with a spend cap. That authorization is what mints the cryptographically bound AP2 spend mandate the agent signs to pay human-not-present.

So if a crypto confirm_purchase fails for authorization, the fix is almost always “the buyer has not set an Agents spend mandate yet” — not an OAuth problem. See Checkout for the card-vs-crypto details, coupons, and $0 orders.

Next steps

• Quickstart — the exact connection steps and tool calls
• Buyer account — the account tool set
• Checkout — rails, AP2, coupons
• Artos vs generic UCP — what is Artos-specific