Purpose
The Hou Tea MCP server wraps the hou-tea.com agent API as MCP tools, enabling AI assistants to purchase Chinese tea on the user's behalf. The project description notes that Chinese tea has over 1,500 years of cultural heritage and a global market larger than coffee, yet AI agents previously either hallucinated product names from training data or could not scrape JavaScript-rendered storefront pages; this MCP provides agents with a channel directly to the real product catalog, real prices, and on-chain settlement.
Main Capabilities
The default tools/list (core + meta tools) is always visible; extended tools are revealed on demand after calling hou_tea_discover_extended, including hou_tea_compare, hou_tea_filter_by_health, and hou_tea_agent_card.
The server is designed as an "agent application layer" and includes: progressive tool discovery (core + extended), strict JSON Schema, structured response/error envelopes (ok, data, error, next_action, meta.request_id), stable error codes, explicit wallet MCP handoff hints, and MCP Apps UI metadata backed by the public @hou-tea/agent-ui-contract package.
Each call returns a structured envelope, for example when ok is true it carries data, next_action, and meta (request_id, tool, took_ms, server_version). Errors use the same envelope with 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), and each error also carries retryable and hint.
Input Schema is strict: each inputSchema sets additionalProperties: false and uses required, enum, pattern, minItems / maxItems, and other constraints.
Payment-related: hou_tea_get_payment_requirements returns the 402 buy_request_body and a next_action block, pointing the agent to an x402 wallet MCP (such as @coinbase/payments-mcp), then back to hou_tea_check_order.
0.3.0-beta adds a public Agent UI protocol layer: core purchase tools publish UI metadata via _meta.ui (component name, agent-ui/v1 schema version, resource URI, result mapping ID); @hou-tea/agent-ui-contract serves as the single source of truth for component manifest, TypeScript types, MCP UI resource names, and result mappings; MCP resources/read responses embed the exact component manifest in HTML, allowing compatible hosts to render product grids, payment review cards, and order timelines without scraping text; the Agent Card and public /agents page provide the npm package, schema JSON, MCP installation snippet, and wallet pairing instructions.
Usage
Configuration example (Claude Desktop): edit claude_desktop_config.json (Settings → Developer → Edit Config), restart Claude Desktop, and you should see "hou-tea" among your tools.
Cursor: add to ~/.cursor/mcp.json or <project>/.cursor/mcp.json.
Cline / Continue / Zed: use the same npx -y @hou-tea/mcp-server@next invocation in their MCP configuration.
Wallet MCP pairing: Hou Tea only issues x402 payment requirements; it does not hold keys or sign transactions. To complete agent-native checkout, pair this MCP with an x402-capable wallet MCP (such as @coinbase/payments-mcp). Fund the wallet with Base USDC before purchasing. After the first successful purchaseThen, copy the returned buyer_list_token to HOU_TEA_BUYER_LIST_TOKEN so that subsequent order history queries remain under the same buyer identity.
Usage example: Say to the agent, "Recommend a warming tea for winter nights, around $30." The agent will call hou_tea_recommend, returning real products, prices, and brewing instructions, then ask whether to purchase. Next, say "I'll take the first one." The agent will call hou_tea_get_payment_requirements, obtaining a 402 with the merchant's Base chain USDC address and amount, as well as buy_request_body (containing register_buyer_list_token or a saved buyer_list_token). When retrying POST /pay/api/v1/buy after payment, you must use that exact JSON body plus the X-Payment header, otherwise the buyer grouping will break. If @coinbase/payments-mcp with a funded wallet is also installed, it must be configured to forward the same body. After the first successful purchase, copy the buyer_list_token from the JSON response to the MCP environment variable HOU_TEA_BUYER_LIST_TOKEN so that hou_tea_list_my_orders and subsequent checkout remain under the same identity.
Optional environment variables: Most users do not need to set them; the public catalog and x402 purchase endpoint are open; to query buyer order history, set HOU_TEA_BUYER_LIST_TOKEN after confirming a purchase.
Build and install from source (beta uses the next tag): npm i -g @hou-tea/mcp-server@next. If your company network blocks npm, you can install it globally once and point the MCP configuration command to hou-tea-mcp.
Public discovery entry points: Agent Card https://hou-tea.com/.well-known/agent；Agent App documentation https://shop.hou-tea.com/agents；UI schema JSON https://shop.hou-tea.com/api/agent-ui-contract。
Use cases
Suitable for building AI shopping agents, tea recommendation applications, or letting Claude directly buy Chinese tea on your behalf. Supports Claude Desktop, Cursor, Cline, Continue, Zed, and any MCP-compatible AI agent.
Limitations and troubleshooting
The server does not hold keys or sign transactions; payment must be completed by a separately installed x402 wallet MCP; the wallet needs Base USDC. If the tools do not appear, restart the host application and run npx -y @hou-tea/mcp-server@next --help in the terminal to confirm that npm can download the package. If payment fails, confirm that the wallet MCP is installed separately, that the wallet has Base USDC, and that the retry POST uses the exact buy_request_body returned by hou_tea_get_payment_requirements. If the order history is empty, you need to set HOU_TEA_BUYER_LIST_TOKEN from the confirmed purchase response; otherwise hou_tea_list_my_orders cannot safely scope the buyer. 0.1.x is still available, and the tool names are unchanged; 0.2.0-beta changes the result shape and the default tools/list count; 0.3.0-beta is the next-tag beta, adding structured wrappers, progressive discovery, and UI metadata.
