MCP tools

The 27 tools Cru’s MCP server offers, in the order tools/list returns them. A connection is shown only the tools its permissions allow, and partner keys get the write tools in a version of their own. Each has a page of its own, with its arguments, what it returns, and a console that calls it on your connection and shows what Cru answers.

Conventions every tool shares

• Prices are normal amounts in the market’s currency — 12345.5 is 12,345.50 — and every result says which currency. Price filters take whole units.
• Wines are LWIN18 codes, 18 digits; search_wines finds them by name. A list of LWIN18s may be an array or one comma-separated string, up to 20.
• Paging is limit and offset, with pagination in the result: 10 a page by default, at most 50, or 25 for search_wines.
• Unknown arguments are refused with a tool error listing what the tool accepts. Numbers may arrive as strings, and booleans as "true" or 1.
• Results come as structuredContent and as the same object in JSON text. Errors come back as a result with isError: true, worded for the assistant to act on.

Reading

The 14 read tools answer at once and change nothing. All are marked readOnlyHint, so an assistant may run them without asking.

Trading

With a connected app’s token, the 11 trading tools prepare an instruction and change nothing: they are marked read-only for that reason. Each checks the request against live data, refuses with a reason if Cru would not do it, and otherwise returns a summary and a confirmation code.

{
  "confirmation_code": "cnf_5DT4rt0U-KyEjnQUzHPTGKw86dNTZ8uZud_zQFdTa-k",
  "expires_at": "2026-10-19T10:25:55Z",
  "action": "bid.place",
  "summary": "Bid GBP 1,650.50 per unit for 1 x Lafite Rothschild 2024 (6x75cl) - GBP 1,650.50 in total, live for 90 days.",
  "preview": {
    "summary": "…the same sentence…",
    "lwin18": "101187220240600750",
    "quantity": 1,
    "price": 1650.5,
    "total": 1650.5,
    "currency": "GBP",
    "expires_on": "2027-01-17",
    "allowance_remaining": 48349.5
  },
  "next": "Nothing has happened yet. Show the customer the summary and ask them to confirm it. Only if they say yes in this conversation, call confirm_instruction with this confirmation_code. If they decline or want changes, do not confirm it; it expires on its own."
}

Confirmation

One tool carries a staged instruction out: confirm_instruction, marked destructiveHint. Every staging result ends with the same instruction to the assistant:

Nothing has happened yet. Show the customer the summary and ask them to confirm it. Only if they say yes in this conversation, call confirm_instruction with this confirmation_code. If they decline or want changes, do not confirm it; it expires on its own.

The same instructions can be inspected and confirmed over REST by the same app. Confirmations in full →

With partner keys

Cru builds the tool list for each caller. Called with partner keys — CLIENT-KEY and CLIENT-SECRET — a write over MCP is carried out at once, as it is over REST; only a connected app’s token gets a confirmation step. The pages here describe the token’s version, and a partner key’s differs in these ways:

• confirm_instruction is not offered, since nothing waits to be confirmed.
• Each write tool’s description opens with what it does, as below, and closes “It is carried out straight away, with no confirmation step; sending the same reference again returns the first result instead of doing it twice.” in place of saying it only prepares. buy_wine also drops “The preview gives the exact total.”, as there is no preview.
• Each takes a required last argument, reference, up to 50 characters: “Your own unique reference for this instruction.”
• Each is marked idempotentHint and not readOnlyHint, and those that move money or wine or remove an address — all but add_inbond_address and suggest_inbond_warehouse — destructiveHint.
• It returns the action’s result as the REST response’s data gives it, with replayed — true when the reference was used before. There is no confirmation_code, summary or next.

suggest_inbond_warehouse is offered to partner keys alone: it needs warehouses:suggest, which Cru grants only to a partner credential. Its page shows the version they get.