Quickstart (Path A — hosted bridge)

The hosted bridge at https://agent.artos.sh/mcp is the fastest way to make an agent shop on Artos. It exposes flat, agent-friendly tools and handles OAuth, AP2 mandate signing, and the crypto rail for you.

Prerequisites

1. A My Artos account for OAuth consent — my.artos.sh .
2. For crypto purchases, additionally authorize the agent under My Artos → Agents and set spend caps. This is separate from OAuth consent (Connected apps); OAuth alone cannot complete a crypto checkout.

Connect Claude (production)

1. Open Settings → Connectors and add a custom connector.
2. MCP URL: https://agent.artos.sh/mcp
3. Anthropic runs OAuth with Claude’s own CIMD client (it appears as “Claude” under Connected apps in My Artos). Complete consent when prompted.
4. For crypto: open My Artos → Agents, authorize the agent, set caps.
5. In chat, try: “Search for running shoes under $100, then buy the cheapest pair and ship to my default address.”

Connecting from a local dev stack works differently — the native Connector can’t reach localhost. See Local development.

The happy path, tool by tool

The agent calls these tools; you don’t write transport code. Shapes below are the exact bridge inputs.

1. Load buyer context

Call this first so you can ship to the default address without asking.

{ "name": "get_buyer_context", "arguments": {} }

2. Search the global catalog

Price is in major units (dollars). Every result carries metadata.artos_seller.slug — you need it for the cart.

{
  "name": "search_products",
  "arguments": {
    "query": "running shoes",
    "filters": { "price": { "max": 100, "currency": "USD" } },
    "sort": "price_asc"
  }
}

3. Create a checkout

Pass the store_slug from the search result and items as [{ id, quantity }] (variant ids). You can seed from a cart_id instead of items.

{
  "name": "create_checkout",
  "arguments": {
    "store_slug": "energy-sport",
    "items": [{ "id": "variant_123", "quantity": 1 }],
    "shipping_address": {
      "line1": "1 Market St",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94105",
      "country": "US"
    }
  }
}

4. Confirm the purchase

The bridge re-prices, verifies the store’s signed terms, mints the AP2 mandate, and completes. Pass payment_method to pick a rail.

{
  "name": "confirm_purchase",
  "arguments": {
    "store_slug": "energy-sport",
    "checkout_id": "checkout_456",
    "payment_method": "artos.card"
  }
}

If the store offers more than one rail and you omit payment_method, you get a recoverable payment_selection_required error naming the rails — ask the buyer, then call again with payment_method set. See Checkout for card vs crypto details, coupons, and $0 orders.

Verify success

• The order appears in My Artos → Orders .
• The OAuth connection appears under Connected apps.

Cursor (development)

Install the bundled skill, then connect via mcp-remote (see Local development for dev TLS and CIMD):

npx skills https://github.com/mkitsos/artos-docs --skill artos-ucp

Or copy skills/artos-ucp/ from this repo into .cursor/skills/.

Next steps

• Authentication — credentials, OAuth, scopes, spend caps
• Catalog — natural-language search → filters, multi-store routing
• Checkout — card + crypto, AP2, coupons
• Direct UCP — build your own client without the bridge