--- name: numi-tea-shop-and-checkout description: >- Find Numi Tea products, build a cart, and drive a checkout to the point of human approval using Numi Tea's Universal Commerce Protocol MCP server. Stops at payment: completing a purchase requires the buyer's explicit, contemporaneous approval, which this skill will not simulate. api: Numi Tea UCP Shopping MCP endpoint: https://numitea.com/api/ucp/mcp transport: mcp operations: - search_catalog - lookup_catalog - get_product - create_cart - update_cart - get_cart - cancel_cart - create_checkout - update_checkout - get_checkout - cancel_checkout - complete_checkout generated: '2026-08-26' method: generated source: >- Grounded in the verbatim tools/list manifest probed from https://numitea.com/api/ucp/mcp on 2026-08-26 (mcp/numi-tea-mcp-tools-list.json) plus the published rules in https://numitea.com/llms.txt and https://numitea.com/robots.txt. Every tool name used here appears in that manifest; none is invented. --- # Shop and check out at Numi Tea Numi Tea sells organic and Fair Trade tea. Its storefront exposes a Universal Commerce Protocol shopping service over MCP. You can search the catalog, build a cart and prepare a checkout programmatically — but you may not complete payment without the buyer in the loop. ## Before you start **Every single call needs two things.** 1. **A bearer JWT.** `initialize` and `tools/list` are anonymous, but every `tools/call` returns JSON-RPC `-32000 AuthenticationRequired` without a token. Get one through Shopify's agent authentication flow: 2. **Your own agent profile.** Every tool requires a `meta` object shaped `{"ucp-agent": {"profile": ""}}`. Omit it and you get `-32001 UCP discovery failed` with `data.code = "invalid_profile_url"`. Numi Tea's server will not transact with an agent that has not published a profile of its own. **Prices are integers in ISO 4217 minor units.** `{"amount": 600, "currency": "USD"}` is **$6.00**. Divide by 100 for USD/EUR before you ever say a number to a person. Zero-decimal currencies such as JPY are already whole units. ## Steps 1. **Find the product.** Call `search_catalog` with the shopper's constraints (flavor, caffeine, format). For a known handle or identifier, use `get_product` for one product or `lookup_catalog` for several at once. 2. **Confirm the facts before you recommend.** Numi Tea's own instructions require you to check the product page for ingredients, caffeine, current price, availability and subscription eligibility. Do not state a price or a stock status you did not just read from a response. 3. **Never invent health claims.** If the shopper mentions allergies, dietary sensitivities, pregnancy, nursing, or medication, point them at the ingredient list and an appropriate healthcare professional. Do not advise. 4. **Build the cart.** `create_cart` with the chosen variants and quantities, then `update_cart` to adjust. `get_cart` re-reads current state. Keep the returned cart `id` — there is no idempotency key on this API, so a retried `create_cart` may produce a second cart. 5. **Open a checkout.** `create_checkout` from the cart, then `update_checkout` to attach the shipping destination. Pass `context.address_country` and `context.currency` when you have them so price and availability come back right. 6. **Read the totals back.** `get_checkout` returns line items, totals, discounts and taxes. Convert from minor units and present the real total, including shipping. 7. **Stop. Get human approval.** Show the buyer the full order and total, and ask for explicit approval *now* — not approval collected earlier for something else. 8. **Only then, `complete_checkout`.** It returns the order ID and Thank You Page URL. Afterwards `get_order` reads order state. ## Backing out | Situation | Do this | |---|---| | Shopper changes their mind mid-cart | `cancel_cart` | | Shopper abandons before payment | `cancel_checkout` | | After `complete_checkout` | **Nothing programmatic.** There is no refund, void or cancel-order tool. | `complete_checkout` is the point of no return on this API. After it, the only remedy is a human return — Numi Tea allows returns or refunds within **30 days** of purchase from numitea.com, started by contacting them before mailing anything, with original shipping and handling non-refundable unless Numi Tea erred (). Treat `complete_checkout` as the approval boundary, because that is exactly where Numi Tea's published policy puts it. ## Shipping constraints that will fail a checkout - **United States only.** No international addresses, no P.O. Boxes, no APO/FPO. - Free standard shipping on contiguous-US orders of **$65+**; below that a **$12.95** charge applies. Alaska and Hawaii ship free at **$75+**. - Most orders placed by 1 PM Eastern, Mon–Fri, ship within 24–48 hours. Do not promise a delivery date; confirm rate and timing at checkout. Check the destination before building a cart for a shopper outside the US — you will save them the whole flow. ## Errors | Code | Meaning | What to do | |---|---|---| | `-32000` `AuthenticationRequired` | No valid JWT | Authenticate and retry. Note this fires *before* tool-name resolution, so it can also mask a typo in the tool name. | | `-32001` `UCP discovery failed` | Missing or unfetchable agent profile URI | Publish a UCP agent profile and pass it in `meta["ucp-agent"]["profile"]`. `data.continue_url` gives a URL you can hand to a human. | | HTTP `429` | Rate limited | Back off and retry. No `Retry-After` value or backoff schedule is published, so use your own conservative exponential backoff. | `data` is a **string** on `-32000` and an **object** on `-32001`. Type-check it before reading fields. ## Hard rules - Never complete payment without contemporaneous buyer approval. - Never use scripted form fills or browser automation to finalize a checkout — Numi Tea's `robots.txt` prohibits it explicitly. Use these MCP tools. - Never collect or expose payment credentials directly. - Do not claim an order was placed until `complete_checkout` returns a success.