MCP tools

Tools use your current workspace role on every call. Read-only connections keep working. Making changes requires the additional tradecatalog:write scope. Consequential actions show a Confirm/Cancel card in compatible clients, with a signed-in review link as a fallback, and run only after you approve. Results are JSON text; the original lookup tools format prices, while management tools use integer minor currency units and basis points (100 = 1%).

Most tools take a workspace: the workspace address from list_workspaces, like northgate. The AI app normally calls list_workspaces first on its own.

When a tool can’t do something, for example you aren’t staff at that workspace or the customer doesn’t exist, it returns an error message the AI app can read and act on, like “No customer "OAK99". Use list_customers for account codes.”

When a supplier’s catalogue is prices only for the selected customer, set_basket_quantity, send_order and reorder return that error. get_basket, list_buyer_orders and get_buyer_order still work, so existing orders stay readable. The supplier sets this in Settings, and can override it per customer (ordering: follow, prices_only or can_order on update_customer).

When the supplier has switched off price-list downloads, download_my_price_list returns an error and the signed-in CSV link answers 403.

quote_configured_product reads the selected buyer account's line price for productId, qty and optional configuration, without changing a basket. set_configured_basket_line creates a separate line or updates/removes its exact lineId (qty: 0 removes). Supply the full specification on edits. Re-read get_basket after changes and review all selections, measures and current prices before send_order. A specification or pricing-version change invalidates the old review even if the total is unchanged.

Staff can use save_product_family for shared variant metadata and save_ordering_draft for a reviewed advanced-pricing draft. The latter requires Pro and global pricing permission; publication uses the existing price-change review. Product imports accept optional family, order increment and ordering definitions. See trade catalogue setup.

Set up a supplier workspaceLink to this section#

create_workspace creates a Free supplier workspace for the signed-in, verified person, after they confirm a card. Ask for the business name, product currency, timezone and country. The person becomes its owner. No subscription or payment is created. Then call list_workspaces again and use the returned address for product and customer setup. Reviewer and guest logins cannot create workspaces.

Free includes up to 100 products and connected AI apps. Each SKU counts, including hidden and inactive products. At the allowance, existing products, edits and orders keep working; creating more products is unavailable. Explain this entitlement without promoting upgrades or starting subscription checkout in the plugin.

list_workspacesLink to this section#

Supplier workspaces you work in, and trade portals where you buy. Start here.

Who: anyone signed in. Inputs: none.

{
  "supplierWorkspaces": [
    { "workspace": "northgate", "name": "Northgate Fixings", "role": "owner" }
  ],
  "tradePortals": [
    {
      "workspace": "hartley-timber",
      "supplier": "Hartley Timber",
      "yourAccount": "Northgate Fixings",
      "accountId": "example-account-id"
    }
  ]
}

search_productsLink to this section#

Search a catalogue by SKU, manufacturer reference, name, brand or category. Returns up to 25 products.

Who: staff and buyers.

• Buyers always see their own account’s prices and only active products they can see.
• Staff see list prices and every product, or a named customer’s view.

{
  "supplier": "Northgate Fixings",
  "pricesFor": "Oakfield Joinery",
  "taxNote": "ex VAT",
  "products": [
    {
      "sku": "HX-8510",
      "name": "Hex bolt M10 x 50 zinc",
      "unit": "Box of 100",
      "availability": "in_stock",
      "price": "£15.73",
      "listPrice": "£18.50",
      "why": "Brand discount −15%"
    }
  ]
}

When the supplier has switched off Show customers the standard price beside their own price, a buyer’s results leave out listPrice and why, and get_buyer_product, get_basket and get_buyer_order carry no list price or price reason either.

Try: “Search Northgate for M10 hex bolts at Oakfield’s prices.”

download_products_csv and download_my_price_listLink to this section#

These tools return a link to an existing CSV download in TradeCatalog. Open it while signed in; returning a link does not download or send the file into chat.

• download_products_csv: staff choose workspace to download that supplier's product list.
• download_my_price_list: buyers choose workspace and the exact accountId from list_workspaces to download only that account's agreed prices.
• download_my_price_list_pdf: the same account, as a branded PDF (Pro). Both tools are blocked when the supplier has turned off price-list downloads.

check_priceLink to this section#

What a customer pays for a SKU at a quantity, and which rule set the price.

Who: staff only.

{
  "customer": "Oakfield Joinery",
  "sku": "HX-8510",
  "name": "Hex bolt M10 x 50 zinc",
  "qty": 20,
  "unitPrice": "£15.73",
  "lineTotal": "£314.60",
  "listPrice": "£18.50",
  "why": "Brand discount −15%",
  "taxNote": "ex VAT"
}

Try: “What does OAK01 pay for 20 of HX-8510, and why?”

list_customersLink to this section#

Trade customers with account codes, contact emails, active status and account discount.

Who: staff only. Inputs: workspace.

[
  {
    "accountCode": "OAK01",
    "name": "Oakfield Joinery",
    "email": "accounts@oakfieldjoinery.co.uk",
    "active": true,
    "discount": "5%"
  }
]

Try: “Which customers have no discount set?”

list_ordersLink to this section#

Recent orders, newest first, up to 50.

Who: staff see every customer’s orders; buyers see their own account’s.

[
  {
    "reference": "SO-000142",
    "customer": "Oakfield Joinery",
    "status": "new",
    "total": "£314.60",
    "poNumber": "PO-88231",
    "placed": "2026-09-27T07:48:12.000Z"
  }
]

Try: “Any new orders since yesterday? Total them up by customer.”

recent_activityLink to this section#

The activity log of changes to customers, discounts and prices, newest first, up to 50 entries. Optionally one customer’s history.

Who: staff only. Owners and admins see the whole log; other staff see only changes about customers they can see.

[
  {
    "when": "2026-09-26T14:21:03.000Z",
    "who": "Jo Hartley",
    "customer": "Oakfield Joinery",
    "what": "Set Northgate brand discount to 15% (was 12.5%)"
  }
]

Try: “Who changed Oakfield’s prices this month?”

NotesLink to this section#

• Customer names and account codes are matched without regard to case. An exact account code is safest.
• list_workspaces returns buyer accountId values. Supply the intended one to search_products and every buyer action. Never guess between accounts.
• Page product searches with offset and the returned nextOffset. Use list_buyer_orders for an explicitly selected buyer account.

Changes and confirmationsLink to this section#

Buyer basket edits, marking updates read and creating unpublished price drafts run immediately when authorised. Other writes return awaiting_confirmation, an actionId and a reviewUrl. ChatGPT and compatible clients display a card with the exact workspace and proposed change: choose Confirm or Cancel without leaving the conversation. Clients without cards use the signed-in review link. Reviews expire after 15 minutes and execute at most once. Disconnecting the app or removing the required workspace access invalidates pending reviews. Changed order baskets and price-change previews require a new review. Use get_action_status to read the outcome; a pending request is not a completed action.

The decide_action helper is available only to the card UI. Its short-lived confirmation capability is hidden from model output and bound to the requesting person, OAuth connection and proposal. A model message or an action ID cannot approve a change. The same role, snapshot, expiry and single-use checks apply to both card and browser approvals.

Every buyer action requires your exact accountId. For send_order, copy the basket fingerprint into expectedBasket, alongside expectedTotal. Prices, quantities and account are checked again before sending.

Use the separate handoff tools for work that finishes in the signed-in app: owners use open_api_key_settings, download_workspace_export and open_logo_settings; staff use open_import_page, open_product_image_upload and open_product_file_manager. The two product handoffs require a tenant-checked productId. File links from get_product and get_buyer_product require your signed-in browser; returning a link has not read the document or completed an upload, removal, export or credential creation. Platform administration is never delegated through OAuth.

Approved customer listsLink to this section#

Staff use get_customer to read the customer's catalogue scope and approved products. set_catalogue_scope changes between all and approved. approve_products adds explicit products or a category; unapprove_product removes one product. These changes require review of the exact customer, current list and affected products. Category membership is checked again at confirmation. Buyers remain limited to their selected account and products visible to that account.

Supplier and buyer toolsLink to this section#

create_workspace is available even when list_workspaces is empty. It creates a Free supplier workspace and owner membership only after confirmation. The optional /mcp/account connection also offers open_billing: owners can open secure subscription billing and confirm payment in Stripe, then check get_settings for the resulting state. Billing links do not complete payments. The standard /mcp connection used by the ChatGPT plugin does not expose open_billing. See sign-up and billing.

MCP 3.0.0 exposes every model-callable operation upfront with its own name, description, input schema and annotations. The previous bulk_products and open_workspace_action tools are replaced by the individual operations below; refresh your client’s tool definitions after updating. The MCP tools/list response is the authoritative input schema. The following tools supplement the lookup tools above:

Staff order entry uses preview_customer_order then reviewed create_customer_order with exact prices and a retry UUID. Processing uses set_order_status with public note, private internalNote/correctionReason, and expectedRevision. Reviewed set_order_delivery records a customer-visible delivery method and optional courier, reference and HTTPS link. These tools follow the member’s current permissions and customer scope. See Orders for the fields and behaviour.