Coffee Company MCP Server
This server provides enterprise B2B tools for partner integrations (delivery platforms, loyalty aggregators, payment providers) with Coffee Company's loyalty, membership, and payment systems via standardized HTTP APIs.
Member Lookup: Search for members by mobile number, openId, or member ID
Member Tier Info: Retrieve loyalty tier details, star balance, tier expiry, and progression toward the next tier
Member Benefits: Query status of 8 benefit types (welcome gift, birthday reward, upgrade reward, etc.) with statuses: hidden, locked, available, or used/expired
Member Benefit List: List all coupons and benefit vouchers associated with a member
Coupon Query: Check the generation/issuance status of coupon codes linked to a specific order
Coupon Detail: Get detailed info on a coupon including status (unused, used, expired, voided), face value, validity period, and redemption count
Equity Query: Check whether an electronic equity/voucher was successfully issued for a given equity order
Equity Detail: Retrieve full details of an equity order including coupon codes, status, amount, and redemption count
Assets Overview: View all of a customer's assets (coupons + equity vouchers) in a consolidated list
Payment Status: Query payment results for cashier transactions with statuses: processing, success, or failed
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Coffee Company MCP Server List all my available coffee coupons and member benefits."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Coffee MCP
The MCP platform that connects beverage brands to every AI assistant.
When a customer says "help me order a latte" to ChatGPT, Claude, Doubao, or any AI assistant — only brands connected via MCP get discovered. This platform is how you get connected.
The Problem
AI assistants are becoming the new storefront. Hundreds of millions of users already ask AI to help them shop, order food, and make decisions. But most brands have zero presence in this channel — no way to be discovered, recommended, or ordered from.
Traditional APIs don't solve this. AI assistants speak MCP (Model Context Protocol) — the open standard for connecting AI to external tools and data.
Related MCP server: mcp-coffee
The Solution
Coffee MCP is an open-source, multi-brand MCP platform that lets any coffee, tea, juice, or bakery brand plug into the AI ecosystem — with a YAML config and a brand adapter.
Customer → AI Assistant → MCP Protocol → Coffee MCP → Your Brand's Backend APIWhat you get:
21 consumer-facing tools (browse menu, find stores, order, pay, track)
10 B2B enterprise tools (member query, coupons, loyalty, payments)
4-tier security model (L0-L3) with rate limiting and transaction safety
Multi-brand support — one platform, unlimited brands
Category presets for coffee, tea, juice, and bakery
Brand onboarding in as little as 5 minutes (CLI) or 30 minutes (AI-assisted)
What it costs: Nothing. MIT licensed. Self-host or extend as you wish.
Who Is This For?
Audience | Value |
Brand CTOs / Digital Leaders | Ship AI ordering for your brand in 2-3 weeks, not 6 months |
AI/MCP Developers | Production-grade reference for multi-tenant MCP server design |
Retail Tech Teams | Battle-tested security model (L0-L3) for AI-to-commerce flows |
Founders | Fork this to build your own vertical MCP platform |
Quick Start
# Install (requires uv + Python 3.13)
uv sync
# Run consumer ordering server (default brand)
uv run coffee-company-toc
# Run with a different brand
BRAND=tea_house uv run coffee-company-toc
# Run B2B enterprise server
uv run coffee-company-mcp
# Run all tests (122 passing)
uv run python tests/test_toc_mcp.py # 89 ToC tests
uv run python tests/test_mcp_real.py # 33 B2B tests
# Initialize a new brand (interactive)
uv run brand-initArchitecture
┌──────────────────────────────┐
│ AI Assistants (MCP Clients) │
│ ChatGPT / Claude / Doubao │
│ OpenClaw / Cursor / Custom │
└──────────────┬───────────────┘
│ MCP Protocol
┌──────────────▼───────────────┐
│ Gateway (Kong/CloudFlare) │
│ OAuth · Rate Limit · WAF │
└──────────────┬───────────────┘
│
┌────────────────────┼────────────────────┐
│ │
┌────────▼─────────┐ ┌────────────▼───────────┐
│ B2B Server │ │ ToC Server (factory) │
│ 10 read tools │ │ 21 tools · L0-L3 │
│ Kong HMAC auth │ │ Multi-brand YAML │
└──────────────────┘ └────────────┬───────────┘
│
┌────────────▼───────────┐
│ BrandAdapter (ABC) │
│ 21 abstract methods │
├────────────────────────┤
│ DemoAdapter (mock) │
│ YourBrandAdapter (HTTP)│
└────────────────────────┘Brand Onboarding
Three paths, pick what fits your team:
1. CLI Init (5 min) — Zero-code, YAML-driven:
uv run brand-init
# → Select: coffee / tea / juice / bakery
# → Generates brands/<your_brand>/brand.yaml
# → Done. Run the server.2. AI-Assisted (30 min) — Give your API docs to Claude:
/brand-onboard https://api.yourbrand.com/docs
# → Generates adapter.py + brand.yaml + integration tests3. Full Custom (1-2 weeks) — Implement BrandAdapter with 21 methods:
class MyBrandAdapter(BrandAdapter):
def nearby_stores(self, city=None, keyword=None):
resp = httpx.get(f"{self.api}/stores", params={"city": city})
return resp.json()["stores"]
# ... 20 more methodsSee Brand Integration Guide for the complete walkthrough.
Category Presets
Preset | Sizes | Extras | Sweetness |
Coffee | tall / grande / venti | espresso shots, syrups | 4 levels |
Tea | regular / large | boba, pudding, taro | 5 levels |
Juice | regular / large | chia seeds, nata | 3 levels |
Bakery | single / combo | gift box | — |
Consumer Tools (ToC Server — 21 Tools)
The full ordering journey, from discovery to delivery:
Group | Tools | Security |
Utility |
| L0 |
Discovery |
| L1-L2 |
Account |
| L1 |
Menu |
| L0 |
Points |
| L1-L3 |
Order |
| L1-L3 |
Security Model
Four tiers designed for AI-to-commerce, where the AI acts on behalf of the user:
L0 (60/min) — Public data: menus, stores, nutrition
L1 (30/min) — User data: account, coupons, orders
L2 (5/hour) — Write ops: claim coupons, add address
L3 (10/day) — Transactions: create order, redeem points
Requires
confirmation_tokenfromcalculate_priceRequires
idempotency_keyto prevent duplicate operations
Enterprise Tools (B2B Server — 10 Tools)
For partner integrations (delivery platforms, loyalty aggregators, payment providers):
Tool | HTTP API | Description |
| POST /crmadapter/account/query | Query member by mobile/openId/memberId |
| POST /crmadapter/account/memberTier | Tier details + stars balance |
| POST /crmadapter/customers/getBenefits | 8 benefit statuses |
| POST /crmadapter/asset/coupon/getBenefitList | Coupon list |
| POST /coupon/query | Order coupon status |
| POST /coupon/detail | Coupon details |
| POST /equity/query | Equity distribution status |
| POST /equity/detail | Equity details |
| POST /assets/list | All customer assets |
| POST /cashier/payQuery | Payment status |
Connect to AI Assistants
Claude Desktop / Cursor (stdio):
{
"mcpServers": {
"coffee-toc": {
"command": "uv",
"args": ["run", "--directory", "/path/to/coffee-mcp", "coffee-company-toc"],
"env": { "BRAND": "coffee_company" }
}
}
}OpenClaw / Agent SDK (Streamable HTTP):
coffee = McpServer.http(
url="https://mcp.yourbrand.com/mcp",
headers={"Authorization": f"Bearer {token}"}
)
agent.add_mcp_server(coffee)Project Structure
brands/ # Brand configs (zero-code onboarding)
├── coffee_company/brand.yaml # Default demo brand
└── tea_house/brand.yaml # Example: tea chain
src/coffee_mcp/
├── toc_server.py # ToC server factory (21 tools)
├── brand_config.py # YAML config loader
├── brand_adapter.py # BrandAdapter ABC (21 methods)
├── demo_adapter.py # Mock data adapter
├── brand_init.py # CLI brand initializer
├── presets/catalog.py # Category presets
├── server.py # B2B server (10 tools)
└── cli.py # CLI + REPL
docs/
├── BRAND_INTEGRATION_GUIDE.md # Step-by-step brand onboarding
├── TOC_MCP_PLATFORM_DESIGN.md # Platform design & competitive analysis
├── TOC_SECURITY.md # Security architecture (L0-L3)
└── MCP_API_DESIGN_GUIDE.md # MCP tool design principlesDocs
Brand Integration Guide — Connect your brand step by step
Platform Design — Architecture, competitive analysis, roadmap
Security Model — L0-L3 threat model for AI-commerce
API Design Guide — MCP tool design principles
Roadmap
Hosted multi-tenant mode (brands self-register, zero-deploy)
Payment provider integrations (Alipay, WeChat Pay, Stripe)
Analytics dashboard (AI ordering funnel, conversion tracking)
More verticals beyond beverage (fast food, convenience stores)
Contributing
PRs welcome. See the Brand Integration Guide if you want to add support for a new brand or category.
License
MIT
Available Tools
10 toolsassets_listC
查询客户全部资产(优惠券 + 权益券),一览式展示。
对应 HTTP API: POST /assets/list
Args: member_id: Coffee Company会员ID
Inputs: member_id (required). Returns: result
cashier_pay_queryB
查询支付状态(收银台下单后的支付结果)。
对应 HTTP API: POST /cashier/payQuery
状态: 0=支付中, 1=支付成功, 2=支付失败
Args: pay_token: 支付令牌(收银下单接口返回的 payToken)
Inputs: pay_token (required). Returns: result
coupon_detailA
查询单张券码的详细信息,包括状态、面值、有效期、核销次数。
对应 HTTP API: POST /coupon/detail
券码状态: 4=未使用, 10=已使用, 20=已过期, 30=已作废
Args: coupon_code: 券码(如 "CC20260301A001")
Inputs: coupon_code (required). Returns: result
coupon_queryC
查询订单关联的券码生成状态。
对应 HTTP API: POST /coupon/query
Args: order_id: 订单号
Inputs: order_id (required). Returns: result
equity_detailB
查询权益详情,包括券码、状态、金额、核销次数等完整信息。
对应 HTTP API: POST /equity/detail
Args: order_id: 权益订单号
Inputs: order_id (required). Returns: result
equity_queryB
查询权益发放状态(电子券是否发放成功)。
对应 HTTP API: POST /equity/query
Args: order_id: 权益订单号
Inputs: order_id (required). Returns: result
member_benefit_listB
查询会员的优惠券和权益券列表。
对应 HTTP API: POST /crmadapter/asset/coupon/getBenefitList
Args: member_id: Coffee Company会员ID
Inputs: member_id (required). Returns: result
member_benefitsB
查询会员 8 项权益状态(新人礼、生日奖励、升级奖励等)。
对应 HTTP API: POST /crmadapter/customers/getBenefits
状态说明: 0=隐藏, 1=未解锁, 2=可使用, 3=已使用/已过期
Args: member_id: Coffee Company会员ID
Inputs: member_id (required). Returns: result
member_queryB
查询Coffee Company会员信息。通过手机号、openId 或会员ID查询。
对应 HTTP API: POST /crmadapter/account/query
Args: mobile: 手机号(模糊匹配,如 "138****1234") open_id: 第三方平台 openId member_id: Coffee Company会员ID
Inputs: mobile, open_id, member_id. Returns: result
member_tierB
查询会员等级详情,包括当前星星数、等级有效期、距下一级的差距。
对应 HTTP API: POST /crmadapter/account/memberTier
Args: member_id: Coffee Company会员ID
Inputs: member_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools have distinct purposes targeting specific resources like assets, payments, coupons, equity, and member data. However, 'assets_list' and 'member_benefit_list' both query member assets/coupons with similar descriptions, creating some ambiguity. The other tools are clearly differentiated by their specific functions.
The naming follows a mostly consistent pattern of 'resource_action' (e.g., coupon_detail, equity_query), but there are notable deviations: 'assets_list' uses plural while others use singular (e.g., 'coupon_query'), and 'member_benefit_list' and 'member_benefits' have inconsistent naming despite similar domains. The pattern is readable but mixed.
With 10 tools, the count is well-scoped for a coffee company server covering assets, payments, coupons, equity, and member management. Each tool serves a specific purpose in this domain, and the number is typical for such a scope, avoiding bloat or thin coverage.
The tool set provides good coverage for querying and managing member data, assets, coupons, equity, and payments, with clear CRUD-like operations for details and lists. Minor gaps exist, such as no explicit tools for creating or updating assets/coupons, but agents can likely work around this with the provided query tools for core workflows.
Related MCP Connectors
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Discover and call 10,000+ production APIs from one MCP server. Pay-per-call billing for AI agents.
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered customer support with real-time access to CRM, ticketing, and communication tools via MCP, supporting context-aware conversations and automated actions.Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables coffee shop order management via MCP, including menu lookup, order creation, and status tracking.-
- FlicenseNot gradedqualityDmaintenanceExposes internal company services as LLM-callable MCP tools, enabling AI agents to perform business operations like customer management, order processing, and support ticketing through natural language.-
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes customer profile, order listing, and order cancellation tools, integrating with underlying REST services to enable AI agents to manage customer and order workflows.-