Read vintrace vessels, batches, work orders, lab results, stock; assign work orders, add notes. Hosted by usefulapi — connect from Claude, ChatGPT, Cursor, or any MCP client.
Team and Enterprise: an Owner adds the connector for the organization first.
Run this command, then run /mcp in Claude Code to log in:
Add to Cursor or add this to ~/.cursor/mcp.json:
{
"mcpServers": {
"vintrace": {
"url": "https://vintrace.usefulapi.io/mcp"
}
}
}Add to VS Code or add this to .vscode/mcp.json:
{
"servers": {
"vintrace": {
"type": "http",
"url": "https://vintrace.usefulapi.io/mcp"
}
}
}No Add custom MCP server option? It depends on your account or workspace settings: see OpenAI's guide.
Run these commands. The second one opens the login page:
Other MCP clients (Windsurf, Cline, Zed and more): add the URL as a remote MCP server (Streamable HTTP). The client then opens the login page in your browser. Do not add an Authorization header: see Before you connect.
The login page asks for your vintrace login URL and vintrace API token.
The URL is the address you log in to vintrace with, for example https://us36.vintrace.net/yourcode/1.app (it holds your server and customer code). A vintrace admin creates the token in vintrace under API tokens (permission: Local vintrace Admin); the token acts with the permissions of the user it is created for, so a dedicated user with only the access you want shared works best. The token is used only to call the vintrace API on your behalf and is never shown to anyone.
Add only the URL. Do not add an Authorization header or an API key to the client config. The server signs you in with OAuth: the login page asks for your vintrace login URL and vintrace API token. If the config has such a header, remove it: some clients then send that header instead of the login token, and every call fails with 401.
Turn on the vintrace connector, then ask in plain words. The AI picks the tools.
| Tool | Type | What it does |
|---|---|---|
vintrace_list_work_orders | read | List work orders List winery work orders (cellar jobs such as transfers, additions, bottling) with their jobs, assignee, status and scheduled time. Filter by scheduled time range, status and operation type. Reply: results plus next_offset. GET /v7/operation/work-orders. |
vintrace_list_wine_batches | read | List wine batches List wine batches (the named lots of wine) with volume, variety, vintage and owner. Use include=vessels,allocations to add where each batch sits. Reply: results plus next_offset. GET /v7/operation/wine-batches. |
vintrace_get_vessel_details_report | read | Vessel contents report The bulk wine report: every vessel (tank, barrel, bin, press, tanker) with its contents, volume, batch, owner and winery as at a date. Use extra_fields=composition,allocations,liveMetrics to add them. Covers every winery the token's user may access unless wineryId/wineryName narrows it. GET /v7/report/vessel-details-report. |
vintrace_get_vessel | read | Get vessel One vessel by id: a tank, barrel, barrel group, tanker or bin, with its details, dimensions and contents. GET /v7/vessel/<tanks|barrels|barrel-groups|tankers|bins>/{id}. |
vintrace_list_lab_requests | read | List lab requests The lab console: analysis tasks (samples to measure) with lab, template, vessel, batch, status and arrival. Completed tasks are left out unless status includes Completed. Reply: results plus next_offset. GET /v7/lab/lab-requests. |
vintrace_list_trial_blends | read | List trial blends List trial blends (planned blend trials) with status and composition. Use composition_summary_by=variety,vintage to summarise. Reply: results plus next_offset. GET /v7/operation/trial-blends. |
vintrace_search_transactions | read | Search winemaking transactions Winemaking operations completed in a date range (transfers, additions, blends, racking...) with the from/to vessels and before/after volumes. Defaults to today when no dates are given. GET /v6/transaction/search. |
vintrace_list_barrel_treatments | read | List barrel treatments Barrel move shipments / barrel treatments recorded in vintrace, with barrel states and treatment types. Reply: results plus next_offset. GET /v7/operation/barrel-treatments. |
vintrace_list_blocks | read | List vineyard blocks List vineyard blocks (grower, vineyard, region, variety). To see fruit placements for a vintage pass include=fruitPlacements together with vintage. Reply: results plus next_offset. GET /v7/harvest/blocks. |
vintrace_list_block_assessments | read | List block assessments List vineyard block assessments (vine and fruit assessments by the viticulture team). Reply: results plus next_offset. GET /v7/harvest/assessments. |
vintrace_list_bookings | read | List fruit bookings List active fruit bookings (grape deliveries planned for a vintage) for one or more wineries: grower, block, variety, expected pick time and quantity. vintage and winery_ids are required. Reply: results plus next_offset. GET /v7/operation/bookings. |
vintrace_list_bulk_intakes | read | List bulk intakes List bulk wine/juice intakes (wine bought or received in bulk) with batch, volume, owner and cost. Reply: results plus next_offset. GET /v7/operation/bulk-intakes. |
vintrace_search_fruit_intakes | read | Search fruit intakes Fruit intake operations (grape deliveries weighed in at the winery): weights, grower, block, vineyard, vintage, docket numbers and metrics. Filter by vintage, grower, vineyard, block or recorded time. Page with first_result and max_results. GET /v6/intake-operations/search. |
vintrace_list_stock_dispatches | read | List stock dispatches List stock dispatch actions (bottled goods and dry goods sent out) with routes, items and shipping information. Reply: results plus next_offset. GET /v7/stock/dispatches. |
vintrace_list_shipments | read | List bulk shipments List shipments created by Bulk Dispatch and inter-winery dispatch operations, with destination and wine details. Reply: results plus next_offset. GET /v7/operation/shipments. |
vintrace_list_cost_transactions | read | List bulk wine cost movements Bulk wine cost movements between two times (cost of wine moved between batches and wineries), optionally for one winery or business unit. Needs the vintrace permission to view costs. Reply: results plus next_offset. GET /v7/costs/business-unit-transactions. |
vintrace_list_brand_allocations | read | List brand allocations List brand allocations of bulk wine (how much of a wine is promised to which brand), by status and vintage. Reply: results plus next_offset. GET /v7/allocations/brand-allocations. |
vintrace_get_purchase_order | read | Get purchase order One purchase order with its lines, state and fulfilment. GET /v7/account/purchase-orders/{id}. |
vintrace_list_inventory | read | List stock inventory Stock on hand (bottled wine, dry goods, additives) up to a date: quantity, committed, on order and available per item, location, owner, tax class. breakout_costing needs the view-costs permission. GET /v6/inventory. |
vintrace_lookup_stock_item | read | Look up stock item Find one stock item by code (matched against the start of the code) or by id: type, unit, owner, accounts, tax class and sub-components. Give code or id. GET /v6/stock/lookup. |
vintrace_get_stock_item | read | Get stock item details One stock item by id with optional detail parts: expand=fields,distributions,notes,historyItems,rawComponents,bulkInfo. GET /v6/mrp/stock/{id}. |
vintrace_list_stock_item_notes | read | List stock item notes The notes recorded on a stock item. GET /v6/mrp/stock/{id}/notes. |
vintrace_list_products | read | List products (wines in vessels) List wine products as they sit in vessels: batch code, vessel, volume, colour, state and the latest lab metrics (TSO2, pH, Brix...). skip_metrics=true makes it faster. barcode matches a vessel code or asset id. GET /v6/products/list. |
vintrace_get_product | read | Get product One wine product by id (or by vessel barcode) with its vessel, volume and metrics. GET /v6/products/{id}. |
vintrace_list_sales_orders | read | List sales orders List sales orders with customer, status, price list, line items, totals and invoice date. Filter by status, customer, order date range or invoice date range. GET /v6/sales-order/list. |
vintrace_get_sales_order | read | Get sales order One sales order by id, or by order code (for example VSO20): customer, items, prices, taxes and status. Give exactly one. GET /v6/sales-order/{id} or /v6/sales-order?code=. |
vintrace_list_parties | read | List parties (customers, growers, owners) List parties: customers, growers, suppliers and owners, individuals or organisations, with address, phone and email. Filter by the start of the name and category. GET /v6/party/list. |
vintrace_get_party | read | Get party One party (customer, grower, supplier, owner) by id, or by exact name. Give exactly one. GET /v6/party/{id} or /v6/party?name=. |
vintrace_get_work_order | read | Get work order One work order by id: every job with its steps, summary text, status and assignee. Find the id with vintrace_list_work_orders or vintrace_list_work_orders_v6. GET /v6/workorders/{id}. |
vintrace_list_work_orders_v6 | read | List work orders (operator view) Work orders from the operator's point of view (what is waiting for me / unassigned), with job counts, status and scheduled dates. Defaults to the last 7 days to 3 days ahead. GET /v6/workorders/list. |
vintrace_search_items | read | Search vintrace items by type Look up names and ids of one kind of item: growers, owners, blocks, varietals, vintages, regions, programs, batches, products, tanks, barrels, bins and more. Use it to find the id or exact name another tool needs. GET /v6/search/list. |
vintrace_add_stock_item_note | write | Add a note to a stock item WRITE: adds a new note to a vintrace stock item (visible to everyone in the winery, recorded under the token's user). Adding the same note twice creates two notes. POST /v6/mrp/stock/{id}/notes. |
vintrace_assign_work_order | write | Assign a work order WRITE: assigns a work order to the token's own vintrace user (or to assign_operator_id), so it shows up in that operator's list. With reassign=true it takes over a work order already assigned to someone else. Check the work order first with vintrace_get_work_order. POST /v6/workorders/assign. |
vintrace_deactivate_booking | write | Deactivate a fruit booking WRITE: deactivates a fruit booking so it no longer counts as an active booking (the record is kept; it is not deleted). Use vintrace_list_bookings to find the booking id first. POST /v7/operation/bookings/{id}/deactivation. |
vintrace_usage_status | Usage status (free-tier meter) Report the caller's current usage: the plan, calls used this month, the limit of the plan (the free monthly cap or the Pro fair use limit), remaining, and whether the limit is reached. Read-only; does not count against the meter. | |
vintrace_request_feature | Request a missing feature Tell usefulapi that the user needs something the vintrace tools cannot do yet (a missing tool, field or filter). Call it only when the user asks for something none of the tools can do, and tell the user that you send the request. Do not call it for errors or for normal requests. Do not include personal data, credentials or customer records. Stored with the product name and the client type (for example Claude or Cursor), without the user's account. At most 5 requests per day. Does not count against the meter. | |
vintrace_upgrade | Upgrade to Pro (unlimited*) Get Pro: unlimited tool calls (fair use limit: 10,000 a month) on vintrace (the free tier caps monthly usage). Plans: "monthly" — $9/month; "yearly" — $90/year (2 months free). Cancel any time: Pro then runs to the end of the paid period, so it also suits a one-time job. *A fair use limit applies. For heavy use (near Pro's limit): "plus" or "plus_yearly" — Pro+, $19/month or $190/year, unlimited tool calls (fair use limit: 100,000 a month); an existing Pro subscription changes to Pro+ in place (needs confirm: true; the price difference for the rest of the period is charged at once). Otherwise returns a short link to open in your browser (it opens Stripe Checkout); after payment the account upgrades automatically. Does not count against the meter. | |
vintrace_cancel_subscription | Cancel the Pro subscription Cancel the caller's vintrace Pro subscription at the end of the paid period (no refund for the current period; Pro continues until then, then the free tier applies). Requires confirm: true. Run vintrace_upgrade later to undo the cancel before the period ends. Does not count against the meter. |
| Plan | Price | Limit |
|---|---|---|
| Free | $0 | 50 tool calls / month |
| Proper user | $9/mo · $90/yr | Unlimited* |
*Pro fair use limit: 10,000 tool calls a month on this server. For more, write to [email protected].
Pro covers this vintrace server only. Subscribe with vintrace_upgrade (it returns a Stripe Checkout link). Cancel any time with vintrace_cancel_subscription: Pro continues to the end of the paid period, with no refund for the current period, and running vintrace_upgrade before then undoes the cancel. Or write to [email protected].
No. usefulapi is an independent service. It is not affiliated with or endorsed by vintrace. The server calls the vintrace API with your own vintrace access, so it sees only the data that your account can see.
Yes. In Claude, add this server's URL as a custom connector. In ChatGPT, add it as a custom MCP server in Plugins. Then log in once. Cursor, VS Code, Claude Code and Codex work too. See the setup steps.
The login page asks for your vintrace login URL and vintrace API token. See Before you connect for where to find them.
No. Add only the URL. Do not add an Authorization header or an API key to the client config. The server signs you in with OAuth: the login page asks for your vintrace login URL and vintrace API token. If the config has such a header, remove it: some clients then send that header instead of the login token, and every call fails with 401.
The login stores them encrypted in the authorization grant of your connection. The server uses them to call the vintrace API for you and to derive a private account id for usage metering. usefulapi does not show them on any page or in any reply. To stop all access, remove the connector and change or delete these credentials in vintrace.
Yes, if you approve it. 3 of the 34 vintrace tools can create or change data. The other 31 are marked read-only. Most MCP clients ask you to approve a tool call before it runs.
The Free plan gives 50 tool calls / month. Pro costs $9/mo or $90/yr, with unlimited tool calls (fair use limit: 10,000 tool calls a month), for this vintrace server only. Cancel any time: Pro then runs to the end of the paid period. Run vintrace_usage_status to see how many calls you used.
Ask the AI to run vintrace_upgrade: it returns a Stripe Checkout link. To cancel, run vintrace_cancel_subscription. Pro continues to the end of the paid period.
Tell the AI what you wanted to do. It can send the request with vintrace_request_feature. We store the text with the server name, the type of AI client and the tool you tried, not with your account, and read every request when we plan new tools. You can send up to 5 requests per day.
Any client that supports remote MCP servers (Streamable HTTP) with OAuth login: Claude (web and desktop), Claude Code, ChatGPT, Codex, Cursor, VS Code, Windsurf and others.
This is a Model Context Protocol endpoint — meant to be connected from an AI client, not opened in a browser. An invalid_token response at the URL is the auth gate working as designed; clients authenticate automatically.