Skip to main content

Tools

Beta

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.

ToolWhat it doesAccess on Product Data
whoamiThe tenant, the app and the effective access per moduleNone
disconnectDeletes this connection's stored loginNone
list_cataloguesCatalogs (root categories), the channels that use each, their default language and number of top-level categories. Flags channels without a catalog.Viewer
search_categoriesCategories 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_productsProducts and clusters by filter, with their main category and every category they are in, per catalogViewer
list_category_productsA category's products and clusters in display order, marked where it is their main categoryViewer
update_categoryOne category: texts in several fields and languages, a move to another parent, its position among its siblings, hide or showEditor
set_category_textsOne text field in one language across many categories, a text per category or a templateEditor
link_productsAdds products and clusters to categories, removes them and sets their main category, in one call and in any catalogEditor
order_category_productsMoves products and clusters to the top or the bottom of a category, or above or below another itemEditor
create_categoriesCreates one category, a small tree or new catalogs. New categories start hidden.Owner
delete_categoriesDeletes 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:

FieldSelects
productIds, skusThese products and clusters. Any status unless statuses says otherwise.
termA match on name, SKU, description or manufacturer
manufacturers, suppliersAn exact match on the stored name. search_products shows each product's manufacturer.
categoryId, includeSubcategoriesThe items in a category, optionally with its subcategories
modifiedSinceItems changed since an ISO date
statusesDefault ["A"] (active), [] for any status
kindproduct, 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.

See also​