jackrain19743/hou-tea-mcp-server

> Agent-app MCP server for hou-tea.com — let your AI agent browse, recommend, and **buy authentic Chinese tea with USDC** via the x402 protocol.
Designed for Claude Desktop, Cursor, Cline, Continue, Zed, and any Model Context Protocol compatible AI agent.
> **v0.3.0-beta** - server now ships as an *agent app layer*, not just a tool list:
> progressive tool discovery (core + extended), strict JSON Schemas, structured
> response/error envelopes (ok, data, error, next_action, meta.request_id),
> stable error codes, explicit hand-off hints to wallet MCPs, and MCP Apps UI
> metadata backed by the public @hou-tea/agent-ui-contract package. See
> What changed in 0.3.0 below.
---
What it does
Exposes the hou-tea agent API as MCP tools so your AI assistant can shop on your behalf.
**Default tools/list (core + meta) — always visible:**
| Tool | What it does |
|---|---|
| hou_tea_browse | List tea catalog with filters (category, price, season, difficulty) |
| hou_tea_recommend | Natural-language recommendations: "warming tea for cold winter nights" |
| hou_tea_explain | Deep dive on one product: brewing guide, story, health info |
| hou_tea_get_payment_requirements | Initiate x402 payment intent (returns recipient + amount; auto register_buyer_list_token / buyer_list_token for buyer order history) |
| hou_tea_check_order | Poll order status after payment |
| hou_tea_list_my_orders | List your x402 orders by buyer_list_token (Bearer; uses HOU_TEA_BUYER_LIST_TOKEN env) |
| hou_tea_discover_extended | Reveal extended tools (compare / health-filter / agent-card) on demand |
**Extended (revealed after hou_tea_discover_extended):**
| Tool | What it does |
|---|---|
| hou_tea_compare | Side-by-side comparison of 2–4 candidates |
| hou_tea_filter_by_health | Filter by conditions: pregnant, insomnia, caffeine sensitive |
| hou_tea_agent_card | Fetch full agent capability descriptor (diagnostics) |
**Payment is handled by an x402-capable wallet MCP** (e.g. @coinbase/payments-mcp) — this server only emits payment intents, it never holds keys or signs transactions.
---
Install
Claude Desktop
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
Restart Claude Desktop. You should see "hou-tea" listed under tools.
Cursor
Add to ~/.cursor/mcp.json or /.cursor/mcp.json:
Cline / Continue / Zed
Same npx -y @hou-tea/mcp-server@next invocation in their MCP config.
Wallet MCP pairing
Hou Tea emits x402 payment requirements, but it does not hold keys or sign
transactions. For agent-native checkout, pair this MCP with an x402-capable
wallet MCP such as @coinbase/payments-mcp:
Fund the wallet with Base USDC before asking the agent to buy. After the first
successful purchase, copy the returned buyer_list_token into
HOU_TEA_BUYER_LIST_TOKEN so future order history queries stay scoped to the
same buyer identity.
---
Try it
After install, ask your agent:
> *"Recommend a warming tea for winter nights, around $30."*
The agent will call hou_tea_recommend, return real products with prices and brewing notes, then offer to buy.
> *"I'll take the first one."*
The agent calls hou_tea_get_payment_requirements, gets back a 402 with the merchant's Base-chain USDC address and amount, plus a buy_request_body field (includes register_buyer_list_token or your saved buyer_list_token). The **retry POST to /pay/api/v1/buy after paying must use that exact JSON body** plus the X-Payment header — otherwise buyer grouping breaks. If you've also installed @coinbase/payments-mcp with a funded wallet, configure it to forward the same body. After the first successful purchase, copy buyer_list_token from the JSON response into MCP env HOU_TEA_BUYER_LIST_TOKEN so hou_tea_list_my_orders and future checkouts stay under one identity.