hou-tea-mcp-server

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

{
  "mcpServers": {
    "hou-tea": {
      "command": "npx",
      "args": ["-y", "@hou-tea/mcp-server@next"]
    },
    "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@next"]
    }
  }
}

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:

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

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.

---

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.

---

Agent UI and MCP Apps

The next beta exposes MCP Apps metadata for hosts that can render structured tool results. The shared UI contract is public:

npm i @hou-tea/agent-ui-contract

The contract currently defines:

| Component | Used by | |---|---| | TeaRecommendationGrid | hou_tea_browse, hou_tea_recommend | | PaymentReviewCard | hou_tea_get_payment_requirements | | OrderTimeline | hou_tea_check_order, hou_tea_list_my_orders |

Tool descriptors include _meta.ui.component, _meta.ui.schemaVersion, _meta.ui.resourceUri, and _meta.ui.resultMappingId. MCP hosts can read the matching resource URI and inspect the embedded agent-ui/v1 manifest.

Public discovery:

• Agent Card: https://hou-tea.com/.well-known/agent
• Agent App docs: https://shop.hou-tea.com/agents
• UI schema JSON: https://shop.hou-tea.com/api/agent-ui-contract

---

Troubleshooting

• Tools do not appear: restart the host app after editing MCP config, then

run npx -y @hou-tea/mcp-server@next --help in a terminal to confirm npm can download the package.

• Payment fails: confirm the wallet MCP is installed separately, the wallet

has Base USDC, and the retry POST uses the exact buy_request_body returned by hou_tea_get_payment_requirements.

• Order history is empty: set HOU_TEA_BUYER_LIST_TOKEN from a confirmed

purchase response. Without it, hou_tea_list_my_orders cannot scope the buyer safely.

• Corporate network blocks npm: install once with

npm i -g @hou-tea/mcp-server@next and point the MCP config command to hou-tea-mcp.

---

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.3.0-beta

This release adds the public Agent UI protocol layer:

1. Public MCP Apps manifests. Core buying tools now advertise UI metadata

through _meta.ui, including component name, agent-ui/v1 schema version, resource URI, and result mapping ID.

1. Shared npm contract. @hou-tea/agent-ui-contract is published as the

single source of truth for component manifests, TypeScript types, MCP UI resource names, and result mappings.

1. Manifest-backed UI resources. MCP resources/read responses now embed

the exact component manifest in HTML so compatible hosts can render product grids, payment review cards, and order timelines without scraping text.

1. External discovery surfaces. The Agent Card and public /agents page

point agents and developers to npm packages, schema JSON, MCP install snippets, and wallet pairing instructions.

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, but the next beta adds structured envelopes, progressive discovery, and UI metadata.

---

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 …" } }

1. 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.

1. Strict JSON Schema. Every inputSchema sets

additionalProperties: false, with required, enum, pattern, minItems / maxItems etc. — so agent-side validators can rely on it.

1. 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.

1. 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