MCP tools

The server has six tools. All are read-only (readOnlyHint: true) and only touch TradeCatalog (openWorldHint: false). Results come back as JSON text, with prices already formatted as money, like £15.73.

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.”

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"
    }
  ]
}

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%"
    }
  ]
}

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

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.

[
  {
    "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.
• A buyer with several accounts at one supplier sees the first account by name. To check another account, use the trade portal.
• For more than 25 products or 50 orders, or to change anything, use the REST API.