Curie Commerce MCP Server

Add a line to the caller's aggregated multi-merchant cart with UPSERT-increment semantics — re-adding the same (shop_domain, product_variant_id) increments the existing line's quantity instead of inserting a duplicate row. The cart row is auto-created on first add (find-or-create on identity). Identity is resolved from the request: Authorization: Bearer <jwt> for authed users, X-Curie-Device-Id (or the session device-id) for anon (matches /api/v1/aggregated-cart REST contract). Free / device-scoped — persists the cart anonymously like the wishlist; the actual purchase happens later at checkout.

List the caller's aggregated multi-merchant cart, grouped by shop_domain by default. The cart is auto-created on first call so iOS/web UIs always have a stable id for the cart-icon badge (matches REST GET behaviour). Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header. Optional `shop_domain` filter returns the flat lines for a single shop. Returns `{ cart_id, shops, total_cents, currency_code, line_count }` — the same envelope the REST GET emits so iOS + web render identical numbers.

Remove a single line from the caller's aggregated cart by line_id. Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header (same identity that owns the parent cart). Idempotent — removing an already-removed line is a no-op success. Destructive: the row is hard-deleted, not soft-deleted.

Set the quantity on an aggregated cart line. Special case: `quantity: 0` DELETES the line (matches UI affordance 'set to 0' === 'remove'). Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header (or the session device-id for anon). Free / device-scoped — like the wishlist; the actual purchase happens later at checkout. Returns the updated line, or `{ line: null }` when the line was deleted via quantity:0.

Returns an MCP-UI UIResource for an inline 3D viewer for the given product (when a USDZ/GLB model exists). Hosts that support MCP Apps render the iframe-embedded model-viewer inline in chat; legacy hosts fall back to structured text + a direct USDZ URL. Differs from view_3d_model (which returns just the URL) — try_on_3d returns a renderable iframe component so the 3D is shown without the shopper leaving chat. Recommended visualization (fallback path): an HTML Artifact embedding Google's `<model-viewer>` web component on the GLB URL with `auto-rotate camera-controls ar ar-modes="webxr scene-viewer quick-look" ios-src="<USDZ>"`. Frame ≥480px tall. The Artifact is the fallback when the host doesn't honor `_meta.ui.resourceUri`.

Save a product to the caller's wishlist. Pinterest-style — the wishlist row is auto-created on first add (find-or-create on identity). Identity is resolved from the request: Authorization: Bearer <jwt> for authed users, X-Curie-Device-Id for anon (matches /api/v1/wishlist REST contract). When `product_url` is given without `product_id`/`shop_domain`, the URL is parsed into `{shop_domain, product_id}` via Curie's product-url-resolver so re-shares of the same product link dedupe. share_kind ∈ {url, text, image} discriminates the three iOS share-extension payload shapes; the same enum is used here so MCP-driven saves dedupe against iOS-shared saves of the same product.

List items on the caller's wishlist, newest-saved first. Wishlist is auto-created on first call (matches the REST GET behaviour so iOS UI always has a stable id). Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header. Optional filters: `shop_domain` (only items from one shop), `limit` (cap; default 200, max 500). Returns the wishlist row + items array.

Mark a wishlist item AS moved-to-cart (sets `moved_to_cart_at = now()`). This tool does NOT directly add the item to a Shopify cart — cart wrapping is the host AI's job via the existing `update_cart` MCP tool. Use this tool to record the move intent on the wishlist row; then call `update_cart` separately with the product_id to complete the transfer. Pro-tier only (spends-money intent). Returns the marked-moved timestamp + a note instructing the host AI to follow up with update_cart.

Remove an item from the caller's wishlist by item_id. Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header (the same identity that owns the wishlist this item belongs to). Idempotent — removing an already-removed item is a no-op success. Destructive: the row is hard-deleted, not soft-deleted.

Create a new Shopify cart for the target shop, optionally pre-loaded with line items. UCP-canonical dev.ucp.shopping.cart.create_cart. Returns the new cart_id + checkout_url ready for in-chat checkout handoff. Passthrough to Shopify Storefront MCP's create_cart.

Read a shopper's current cart by id. Returns line items, totals, discount info, and checkout URL. Passthrough to Shopify Storefront MCP's get_cart for the target shop; requires shop scope and is not available for cross-merchant queries.

Modify a Shopify cart — add line items, update quantities, remove lines. Pass cart_id=null to create a new cart. Returns the updated cart with checkout URL ready for in-chat completion. Passthrough to Shopify Storefront MCP's update_cart.

Cancel an existing Shopify cart. UCP-canonical dev.ucp.shopping.cart.cancel_cart. Idempotent — re-cancelling a cancelled cart returns success. Passthrough to Shopify Storefront MCP's cancel_cart.

Cancel a Shopify checkout session. UCP-canonical dev.ucp.shopping.checkout.cancel_checkout. Idempotent — re-cancelling returns success. Idempotency-key auto-managed.

Read a Shopify checkout session's current state by id. Returns status, line items, shipping address, totals, brand voice. UCP-canonical dev.ucp.shopping.checkout.get_checkout. Passthrough to Shopify Checkout MCP.

Update fields on a Shopify checkout session. UCP-canonical dev.ucp.shopping.checkout.update_checkout — Curie's wrapper performs a PUT-semantics-safe diff (fetches current state, merges your partial input, forwards the full payload) so omitting a field doesn't silently delete it. Set `clear_fields[]` to explicitly clear values.

Add a generated 3D model to the merchant's Shopify store as MODEL_3D media — creating the product if needed — and optionally publish it. This is the store-side 'cut-and-paste' step: pass the hosted `glb_url` of an already-generated model, OR pass just an `image_url` and (when the Curie generation engine is configured) the tool runs the photo→3D step for you. WRITE operation; works only on an installed merchant store (uses the app's offline Admin token). Defaults to a DRAFT product unless `publish: true`. Returns the new product id + the 3D-viewer surface.

Get full details for a specific product by its ID. The UCP/Shopify-Storefront-MCP-canonical product-detail tool. Returns the full Shopify product payload (description, options, variants, selling_plan_groups, requires_selling_plan, selectedOrFirstAvailableVariant, total_variants, url) PLUS Curie's additions (glbUrl, usdzUrl, has3DModel, media cascade, brand voice). Returns a single structured product object suitable for an inline product-detail Artifact. Recommended visualization: a React Artifact with a hero image (or embedded `<model-viewer>` when has_3d_model is true), uppercase brand label, title, price callout, and a vertical attribute list. Use _meta.curie.brand.palette for the surface + accent colors.

Check product availability and pricing across retailers. Returns all affiliate links with current prices.

Returns the merchant's brand palette, typography hints, voice/tone profile, signature phrases, forbidden words, and a system_prompt_block the AI client can prepend to subsequent responses so they sound like the merchant rather than generic AI output.

Search the store catalog by name, brand, style, color, or keywords. This is the UCP/Shopify-canonical catalog-search tool (Shopify Storefront MCP's `search_catalog`, formerly `search_shop_catalog`); `search_products` is a deprecated alias of this tool. Returns matching products with images, prices, and 3D model availability. Use `max_price` / `min_price` for structured price filters — natural-language constraints like 'under $150' embedded in the query are also post-clamped server-side, but passing the structured arg is preferred (matches Shopify UCP `filters.price.min/max`). Returns structured product items suitable for inline gallery rendering. Recommended visualization: a horizontal scrolling React Artifact with product cards showing image, uppercase brand, title, price, and a small "3D" pill when has_3d_model is true. Use _meta.curie.brand.palette.brand_color for the accent color and tap-to-view as the primary action.

Compare 2 to 6 products side-by-side. Returns a comparison matrix with each product's name, price, brand, 3D model availability, key attributes, and a cascade-aware visual hint for each row. Optional criteria narrow which features are weighted (e.g. ['waterproof', 'budget under $150']). Returns matrix data suitable for an inline comparison Artifact. Recommended visualization: a React table Artifact with product columns (image header + name + price) and attribute rows. Use winnerIndex on each row to highlight the winning cell with _meta.curie.brand.palette.accent_color. Include a footer row of criteria_scores with weighted bars.

Complete (finalize payment + place order) a Shopify checkout session. UCP-canonical dev.ucp.shopping.checkout.complete_checkout. Requires a selected_instrument_id from the checkout's available payment instruments. Token-tier merchants complete in-protocol; Free-tier merchants return a continue_url for hosted-redirect handoff. Idempotency-key auto-managed.

Begin a GUEST checkout flow for one or more products — NO sign-in required. Pass `shop_domain` (e.g. "allbirds.com") on Curie's cross-merchant route so Curie resolves the shop, creates an UNAUTHENTICATED Shopify cart, and returns its `continue_url` — the shop's OWN Shopify-hosted guest checkout where the buyer completes payment securely (Curie never charges or stores card data). On a shop-scoped connector the storeId already names the shop, so `shop_domain` is optional. `product_ids` accept the SAME identifiers `search_catalog` / `get_product` return (Shopify Product GIDs `gid://shopify/Product/...`, product URLs, or Curie UUIDs). Returns a checkout UIResource + cascade media (3D / 360° / image) for every line item.

Batch-retrieve full product objects by ID in ONE call. This is the UCP/Shopify-canonical batch product-lookup primitive (Shopify Catalog MCP's `lookup_catalog`) — the multi-id counterpart of `get_product`. Pass an array of product identifiers (the SAME identifiers `search_catalog` / `get_product` return: Shopify Product GIDs (gid://shopify/Product/...), canonical product URLs, or Curie catalog UUIDs) and Curie resolves them all against the shop's live catalog in one round-trip. Returns the same product-summary list `search_catalog` returns. Use it instead of N separate `get_product` calls when you already know which products you want (e.g. re-hydrating a cart, wishlist, or comparison set). Returns structured product items suitable for inline gallery rendering. Recommended visualization: a horizontal scrolling React Artifact with product cards showing image, uppercase brand, title, price, and a small "3D" pill when has_3d_model is true. Use _meta.curie.brand.palette.brand_color for the accent color and tap-to-view as the primary action.

Read the live status of an order by id (UCP-canonical dev.ucp.shopping.order.get_order). Returns the real order body — line items, fulfillment/tracking, totals, status — when the order is visible to Curie. Visibility today is per-agent (Shopify Order MCP scope): orders placed THROUGH Curie's checkout return real data; orders placed in another session or on the storefront directly return a graceful "connect your account at chat.curie.app" state (NOT an error) because cross-session/cross-agent history requires the Customer Accounts MCP OAuth handoff (Curie slice 5 — not yet shipped). Renders the order-status surface either way.

Get product recommendations similar to a given product. Useful for 'show me more like this' requests. Returns structured product items (same shape as search_products). Recommended visualization: a horizontal scrolling React Artifact with product cards labeled "More like this" — image, uppercase brand, title, price, 3D pill. Use _meta.curie.brand.palette.brand_color for the accent color and tap-to-view as the primary action.

Get facts about the shop's policies (returns, shipping, refunds, exchanges) or product FAQs. Example questions: "What's your return policy?", "Do you ship to Canada?", "How long do exchanges take?". Passthrough to Shopify Storefront MCP's search_shop_policies_and_faqs.

Editorial 'best for the job' answer. Given a shopper's job-to-be-done (e.g. 'shoes for flat feet', 'beach wedding outfit under $200'), returns one top pick, 2 alternatives (also-great / budget / step-up), the criteria used to rank them with weights + explainers, and product citations linking back to real product pages. Use when the shopper asks a how-do-I-choose question rather than a specific-product question. Accepts `job_description` (canonical) or `goal` / `job` / `query` (aliases) — same field, named for caller convenience. Recommended visualization: an editorial-style React Artifact card showing a small uppercase "CURIE'S PICK" badge, the problem statement, the top pick (large hero image + name + price + 1-line explainer), then 2 alternative cards in a row labeled by tier (budget / step-up / also-great), then a criteria list with weighted bars. Use _meta.curie.brand.palette for the editorial frame.

Onboarding suggestion chips for the chat surface — the same 'What's trending?' / 'Find me a gift' / 'Compare products' chips chat.curie.app shows above its input. When called on a per-shop MCP endpoint (e.g. /api/mcp/allbirds.com), returns brand-themed prompts mentioning that merchant. When called on /api/mcp/global, returns cross-merchant discovery prompts. Lets any AI host (Claude.ai, ChatGPT, Cursor) render the same starting-suggestions Curie's own chat shows — universal experience across harnesses. Recommended visualization: a React Artifact with a chip-grid UI showing each prompt as a tappable button styled with _meta.curie.brand.palette.brand_color. Optional category groupings if more than 4 chips.