@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.2.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, and explicit hand-off hints to wallet MCPs. See
> What changed in 0.2.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):

{
  "mcpServers": {
    "hou-tea": {
      "command": "npx",
      "args": ["-y", "@hou-tea/mcp-server"]
    },
    "coinbase-payments": {
      "command": "npx",
      "args": ["-y", "@coinbase/payments-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Restart Claude Desktop. You should see "hou-tea" listed under tools.

Cursor

Add to ~/.cursor/mcp.json or <project>/.cursor/mcp.json:

{
  "mcpServers": {
    "hou-tea": {
      "command": "npx",
      "args": ["-y", "@hou-tea/mcp-server"]
    }
  }
}

Cline / Continue / Zed

Same npx -y @hou-tea/mcp-server invocation in their MCP config.

---

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.

---

Configuration

All settings via environment variables (optional):

| Env var | Default | Purpose |
|---|---|---|
| HOU_TEA_API_BASE | https://hou-tea.com | Override API host (e.g. for staging). |
| HOU_TEA_PAY_BASE | https://hou-tea.com/pay | Override x402 middleware host. |
| HOU_TEA_STORE_ID | fengshui | Default store_id. |
| HOU_TEA_AGENT_KEY | (none) | Optional X-Agent-Key for higher rate limits / private skills. Contact support@hou-tea.com. |
| HOU_TEA_BUYER_LIST_TOKEN | (none) | After first successful /buy, paste the buyer_list_token from the response. Future hou_tea_get_payment_requirements calls send this as buyer_list_token; enables hou_tea_list_my_orders. |
| HOU_TEA_AUTO_REGISTER_BUYER_LIST_TOKEN | true | Set to false to stop sending register_buyer_list_token / buyer_list_token on /buy (legacy behavior). |

Most users need none of these — the public catalog and x402 buy endpoint are open. For buyer order history, set HOU_TEA_BUYER_LIST_TOKEN once you have it from a confirmed purchase.

---

Architecture

┌─────────────────┐         ┌────────────────────┐
│ Claude / Cursor │         │  hou-tea.com       │
│                 │  HTTPS  │  /api/agent/      │
│ ┌─────────────┐ │ ──────► │  (catalog/         │
│ │ hou-tea MCP │ │ ◄────── │   recommend/etc.)  │
│ └─────────────┘ │         └────────────────────┘
│                 │
│ ┌─────────────┐ │  HTTPS  ┌────────────────────┐
│ │ payments MCP│ │ ──────► │ /pay/api/v1/buy    │
│ │ (Coinbase)  │ │ ◄ 402 ─ │ x402-middleware    │
│ └─────────────┘ │         │                    │
│       │         │  Base   │   verifies on-     │
│       └─────────┼──────►──┤   chain tx, marks  │
│   USDC transfer │  chain  │   order confirmed  │
└─────────────────┘         └────────────────────┘

git clone https://github.com/hou-tea/hou-tea-mcp-server.git
cd hou-tea-mcp-server
npm install
npm run build
node dist/index.js          # speaks MCP over stdio
npm run test:unit           # offline unit tests (envelope + registry)

npm run test:smoke          # live HTTP smoke (hits hou-tea.com)

npm run test:mcp            # full MCP stdio smoke (build + spawn)

   { "ok": false,
     "error": { "code": "extended_not_revealed",
                "retryable": true,
                "hint": "Call hou_tea_discover_extended …" } }
   

   {
     "ok": true,
     "data": { / tool payload */ },
     "next_action": [
       { "tool": "hou_tea_explain", "reason": "...", "args_hint": { "skill_id": "..." } }
     ],
     "meta": { "request_id": "req_…", "tool": "hou_tea_recommend",
               "took_ms": 412, "server_version": "0.2.0-beta.0" }
   }
   

Errors share the same envelope with ok: false and a stable error.code
(bad_request, unauthorized, not_found, conflict, timeout,
rate_limited, server_error, network_error,
missing_buyer_list_token, extended_not_revealed, unknown_tool,
internal_error). Each error also carries retryable and a hint.

3. Strict JSON Schema. Every inputSchema sets
additionalProperties: false, with required, enum, pattern,
minItems / maxItems etc. — so agent-side validators can rely on it.

4. Hand-off hints to wallet MCP. hou_tea_get_payment_requirements
returns the 402 buy_request_body plus a next_action block that points
the agent to an x402 wallet MCP (e.g. @coinbase/payments-mcp) and then
back to hou_tea_check_order.

5. Traceability. Every response carries meta.request_id so you can
include it in support tickets / logs.

This is a next-tagged beta; install with:

```bash
npm i @hou-tea/mcp-server@next