@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:

Extended (revealed after hou_tea_discover_extended):

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):

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  │
└─────────────────┘         └────────────────────┘

Build from source

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)

What changed in 0.2.0-beta

Anthropic's Skills + MCP guidance pushes MCP servers from "a flat list of tools" toward an agent app layer: progressive discovery, strict schemas, program-friendly responses, and explicit hand-off to other MCPs. This release brings that posture to @hou-tea/mcp-server:

1. Progressive tool discovery. Default tools/list returns 6 core tools

   • hou_tea_discover_extended. Extended tools (hou_tea_compare, hou_tea_filter_by_health, hou_tea_agent_card) are revealed on demand. Calling an extended tool before discovery returns a structured error:

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

2. Structured envelope on every call.

   {
     "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:

npm i @hou-tea/mcp-server@next
# or, in MCP config: "args": ["-y", "@hou-tea/mcp-server@next"]

The 0.1.x line keeps working — tool names are unchanged, only the result shape and the default tools/list size are different.

Why this exists

Chinese tea has 1500+ years of cultural depth and a global market larger than coffee. But until now, AI agents either (a) hallucinated product names from training data, or (b) failed to scrape JavaScript-rendered storefronts. This MCP gives agents a direct, authoritative, agent-native path to a real catalog with real prices and real on-chain settlement.

If you're building an AI shopping agent, a tea recommendation app, or just want your Claude to be able to actually buy you tea — this is for you.

License

MIT © hou-tea