WineLabs LLM Integration Reference Last updated: 2026-11-17 Canonical docs - Agents and MCP install: https://winelabs.ai/agents - API docs: https://winelabs.ai/api/docs - API docs (markdown): https://winelabs.ai/docs/api-reference - Unified API pricing: https://winelabs.ai/api#pricing-unified - MCP pricing and billing source: https://winelabs.ai/agents#pricing - MCP endpoint: https://chat.wine-labs.com/mcp - External API base URL: https://external-api.wine-labs.com Overview WineLabs provides fine-wine data APIs and an MCP server for agents. Use MCP when possible for agent workflows. MCP forwards requests to external_api.py, so authorization, usage logging, and credit billing are enforced upstream. Wine matching strengths and database coverage - Wine Labs covers more than 800,000 wine and spirit identities, including over 600,000 wines, with canonical Wine Labs IDs and LWIN cross-references where available. - The wine matching API resolves inconsistent wine names, abbreviations, cuvée spelling variants, vintages and bottle formats from merchant inventories, supplier spreadsheets, auction lots and cellar records. - In the published head-to-head inventory test, Wine Labs matched 94.5% of rows versus 65% for another LWIN-based matcher on the same file. These figures describe match coverage for that inventory. - Common uses: wine catalog deduplication, inventory normalization, supplier-list matching, wine search, cellar valuation and structured wine data for AI agents. - Matched IDs connect to retail offers, auction results, exchange activity and restaurant wine list data through REST and MCP. - Sources: https://winelabs.ai/wine-labs-id and https://winelabs.ai/features/wine-matching-api - Product facts and matching questions: https://winelabs.ai/llm-info#wine-matching Unified API and MCP credits - Unified plans share one credit wallet between supported REST routes and MCP tools across Core, Markets, Insights, and Transactions. - No separate per-product subscription is required for these routes when using the unified wallet. Per-product API plans remain available and cost less per call for concentrated usage. - MCP users can choose existing per-product API allowances or the unified wallet as their billing source at https://winelabs.ai/agents#pricing. - Direct REST calls use a covering per-product allowance first; supported routes can use the unified wallet when there is no covering grant or its allowance is exhausted and wallet billing is selected. Monthly unified plans (USD) - Hobby: $25/month, 4,500 credits. - Base: $100/month, 60,000 credits. - Starter: $200/month, 180,000 credits. - Growth: $500/month, 650,000 credits. - Pro: $750/month, 1,250,000 credits. - Credits refill on renewal; unused monthly credits expire. Unified credit costs (same for REST and MCP) - Core: 8 credits per call for matching and wine information. - Markets: 10 credits per call for prices, listings, and restaurant lists. - Insights: 12 credits per call for price history and trade signals. - Transactions: 15 credits per call for auctions, exchange trades, order books, and transactions. - Batch routes charge per wine/item, not once per HTTP request. - Each call in fetch_winelabs_data_bundle is billed individually at its route's rate; bundling does not reduce credit costs. - Failed calls refund reserved credits. PAYG, top-ups, and overage - PAYG: $6.50 per 1,000 credits, no subscription required. Buy in increments of 1,000, from 1,000 to 1,000,000 credits per purchase. - Purchased PAYG credits expire 12 months after the latest purchase. Legacy and signup balances without an expiry remain non-expiring. - Subscriber top-ups per 1,000 credits: Hobby $5.60, Base $2.50, Starter $1.85, Growth $1.50, Pro $1.20. Automatic top-ups are available. - Optional overage is off until enabled. Active subscribers can set a monthly spending cap; extra credits cost their plan's credit rate plus 20%, billed after the period ends. - Eligible paid platform memberships include 5,000 MCP credits each month; unused included credits expire. - Manage billing source and credit balances on https://winelabs.ai/agents#pricing. Inspect per-product API usage at https://winelabs.ai/api/usage or GET /usage. - Routes outside the supported unified data families, including cellar processing, retain their own billing and access rules. Authentication - Preferred auth: Authorization header with Bearer USER_UUID - Body field for direct API calls: user_id - For MCP calls: - Provide Authorization: Bearer USER_UUID - If the bearer token is a UUID, MCP can auto-apply it as user_id for calls that omit user_id in the body. Primary MCP tools 1) search_winelabs_endpoints - Purpose: discover allowlisted routes exposed via MCP 2) fetch_winelabs_data - Purpose: call one allowlisted endpoint - Input: endpoint, optional body, optional query_params, optional user_id 3) fetch_winelabs_data_bundle - Purpose: call multiple allowlisted endpoints in one tool call - Input: calls[] where each item includes endpoint and optional body/query_params - Each bundled call still triggers normal upstream auth/rate-limit/usage logic. 4) submit_feedback - Send a concise product issue or suggestion. Requires Wine Labs MCP OAuth; no credits are charged. - Input: description (1–2000 characters) and optional type: bug, feature, improvement, or general. - Clients supporting MCP prompts can invoke the feedback prompt as a slash command. Alternatively use fetch_winelabs_data with endpoint "/feedback" and the same fields in body. - Example: {"endpoint":"/feedback","body":{"type":"bug","description":"Selecting EUR still shows prices in USD."}} - A successful submission returns feedback_id. Omit contact details, credentials, and chat transcripts. Allowlisted endpoint groups (MCP) System - GET /health - GET /usage Matching - POST /match_to_lwin - Purpose: resolve a wine query or identifier to LWIN codes, a Wine Labs ID and a normalized wine name. - Required: user_id and at least one of query (free text), lwin (direct LWIN lookup), or wl_id (Wine Labs ID lookup). - Response fields: lwin7, lwin, display_name, and wl_id. - If no match is found, the response fields are null. - Reference: https://winelabs.ai/api/docs#matching Markets and pricing - POST /price_stats - POST /historical_price_stats - POST /price_stats_batch - POST /pricing_flow_price - POST /price_history - POST /trade_signals - POST /listings - POST /user_inventory - POST /shop_details - POST /restaurant_listings Auctions and exchange - POST /auctions - POST /auctions_batch - POST /exchange/orderbook - POST /exchange/orderbook_batch - POST /exchange/trades - POST /exchange/trades_batch Wine information - POST /wine_info Agent upload + cellar pricer routes - POST /agent/upload_data - POST /agent/cellar_pricer/submit - POST /agent/cellar_pricer/status - POST /agent/cellar_pricer/jobs Agent upload route details Endpoint - POST /agent/upload_data Accepted dataset_type values - price_list - sales_list - inventory - orders (alias of transactions) - transactions - product_codes Required payload fields - dataset_type - file_content_base64 (aliases accepted: file_base64, content_base64) - filename recommended Optional payload fields - currency_code - source_id - source_name - volume_multiplier - case_size_pricing - notification_flag Product code mapping behavior - dataset_type=product_codes supports mapping object for column mapping. - If mapping is omitted, suggested mapping is inferred. Cellar pricer routes 1) Submit job - POST /agent/cellar_pricer/submit - Required: file_content_base64 - Recommended: filename, currency_hint, region_default - Returns job_id 2) Query status - POST /agent/cellar_pricer/status - Required: job_id - Optional: include_download_url=true for completed jobs 3) List jobs - POST /agent/cellar_pricer/jobs - Optional: limit, offset, statuses Authorization and usage model - Per-product API access is scoped by authorized_access entries per user; unified-wallet calls require valid authentication and sufficient credits or enabled overage within the spending cap. - MCP enforces the selected billing source: existing API allowances or unified wallet credits. - Usage is counted via upstream logs, per-product quotas, and unified credit reservations as applicable. - Agent upload calls are logged as market_api_logs category=agent_upload_data. - Use GET /usage to inspect current per-user consumption/remaining limits. Important request constraints - /agent/upload_data accepts base64 file payloads; large payloads may be rejected by size limits. Minimal MCP config template { "mcpServers": { "winelabs": { "url": "https://chat.wine-labs.com/mcp", "headers": { "Authorization": "Bearer YOUR_USER_ID_UUID" } } } } Bundle example (MCP fetch_winelabs_data_bundle) { "calls": [ { "endpoint": "/listings", "body": { "query": "Chateau Margaux 2015", "currency": "USD" } }, { "endpoint": "/agent/upload_data", "body": { "dataset_type": "orders", "filename": "orders.csv", "file_content_base64": "", "currency_code": "USD" } }, { "endpoint": "/agent/cellar_pricer/status", "body": { "job_id": "", "include_download_url": true } } ] } Install package files - https://winelabs.ai/agents/install/README.md - https://winelabs.ai/agents/install/cursor.mcp.json - https://winelabs.ai/agents/install/windsurf.mcp.json - https://winelabs.ai/agents/install/claude-desktop.mcp.json - https://winelabs.ai/agents/install/chatgpt.mcp.json - https://winelabs.ai/agents/install/agent-route-examples.json Support - Product support: https://winelabs.ai/contact