Tools
The MCP server is in beta. You can use it, but its tools, limits and behavior can still change. The changelog announces changes.
The server offers an assistant only the tools its effective access covers. All category tools need access to Product Data.
| Tool | What it does | Access on Product Data |
|---|---|---|
whoami | The tenant, the app and the effective access per module | None |
disconnect | Deletes this connection's stored login | None |
list_catalogues | Catalogs (root categories), the channels that use each, their default language and number of top-level categories. Flags channels without a catalog. | Viewer |
search_categories | Categories by name, id or path, a parent's subcategories or a branch down to a depth. Optionally their texts per language, only those missing a text and active product counts. | Viewer |
search_products | Products and clusters by filter, with their main category and every category they are in, per catalog | Viewer |
list_category_products | A category's products and clusters in display order, marked where it is their main category | Viewer |
update_category | One category: texts in several fields and languages, a move to another parent, its position among its siblings, hide or show | Editor |
set_category_texts | One text field in one language across many categories, a text per category or a template | Editor |
link_products | Adds products and clusters to categories, removes them and sets their main category, in one call and in any catalog | Editor |
order_category_products | Moves products and clusters to the top or the bottom of a category, or above or below another item | Editor |
create_categories | Creates one category, a small tree or new catalogs. New categories start hidden. | Owner |
delete_categories | Deletes categories. Optionally a whole branch, with its products and clusters taken out and new main categories assigned. | Owner |
Tool names and fields spell catalog the British way: list_catalogues, catalogueId and filter.catalogue.
Name categories and catalogs
Every tool takes a category as an id or as a path from the catalog down:
{ "category": "Office supplies > Paper > Copy paper" }
A path can also start at any category with a unique name. When a name or path matches more than one category, the tool returns the candidates with their ids and paths, and the assistant asks the user which one is meant.
A catalog is named by the id of its root category, its name or the name of a channel that uses it.
Find categories with their texts
search_categories returns each category with its path and catalog. This call reads the Dutch and English descriptions of one category by its path, with names in English:
{
"filter": { "categories": ["Office supplies > Paper > Copy paper"] },
"texts": { "fields": ["descriptions"], "languages": ["nl", "en"] },
"language": "en"
}
{
"total": 1,
"page": 1,
"pages": 1,
"hasMore": false,
"items": [
{
"categoryId": 3104,
"name": "Copy paper",
"path": "Office supplies > Paper",
"parentId": 3101,
"catalogueId": 17,
"texts": {
"descriptions": {
"nl": "Kopieerpapier in A4 en A3, in 80 en 100 grams. Geschikt voor alle printers en kopieerapparaten."
}
}
}
]
}
A language without a value is left out of texts, so the English description in this example is still empty. path is where the category sits, without the category itself.
Select products and clusters
search_products, list_category_products and link_products take the same filter:
| Field | Selects |
|---|---|
productIds, skus | These products and clusters. Any status unless statuses says otherwise. |
term | A match on name, SKU, description or manufacturer |
manufacturers, suppliers | An exact match on the stored name. search_products shows each product's manufacturer. |
categoryId, includeSubcategories | The items in a category, optionally with its subcategories |
modifiedSince | Items changed since an ISO date |
statuses | Default ["A"] (active), [] for any status |
kind | product, cluster or any (default) |
A filter for a change must select something specific: a filter with only statuses or kind is refused. An argument the tool doesn't know is refused instead of ignored, so a misspelled field never widens a change.
Text fields and languages
The text tools work on these category fields: names, descriptions, shortDescriptions, metadataTitles, metadataDescriptions, metadataKeywords, metadataCanonicalUrls and slugs. Languages are codes such as nl, en, de and fr. A write changes only the languages it names.
Large results
Lists come in pages with total, hasMore and pages. countOnly returns only the total. A scan of a large catalog stops at 2,000 categories and returns truncated with a note on how to narrow it.