Changes and confirmations
The MCP server is in beta. You can use it, but its tools, limits and behavior can still change. The changelog announces changes.
Every tool that changes data takes dryRun: true. A dry run checks everything a real run checks and returns exactly what would change, without changing anything.
Previews and the user's yes
Each dry run returns a nextStep that tells the assistant whether it may go ahead:
| Change | nextStep says | The assistant |
|---|---|---|
A rename, a move, a new order, hide or show (update_category without other texts, order_category_products) | Write now if this is exactly what the user asked for | Writes right after a matching dry run when the user named exactly what to change |
| Everything else: changes to many categories, texts the assistant writes or overwrites, links, main categories, new categories and deletes | Show the user and write only after their yes | Shows the dry run and waits for the user to agree |
This dry run of link_products puts two products in a category and makes it their main category, so it waits for the user's yes:
{
"filter": { "skus": ["LZ-1010-80", "LZ-1010-50"], "statuses": "any", "kind": "any" },
"matched": 2,
"dryRun": true,
"nextStep": "Show the user what this changes, and write only after they say yes.",
"changes": [
{
"add": { "categoryId": 3120, "name": "Filing", "path": "Office supplies", "catalogueId": 17 },
"wouldAdd": 2,
"alreadyIn": 0
},
{
"main": { "categoryId": 3120, "name": "Filing", "path": "Office supplies", "catalogueId": 17 },
"wouldMakeMain": 2,
"alreadyMain": 0
}
],
"gatewayCallsNeeded": 3,
"gatewayCallsLeftThisMinute": 594,
"sample": [
{ "productId": 10512, "sku": "LZ-1010-80", "name": "Leitz 180° lever arch file A4 80 mm" },
{ "productId": 10513, "sku": "LZ-1010-50", "name": "Leitz 180° lever arch file A4 50 mm" }
]
}
In the response, "statuses": "any" means the filter covers every status, the default when products are named by SKU or id. To ask for every status in a request, send "statuses": [].
Most assistants also ask the user to approve a tool that changes data. That approval comes on top of the dry run.
Texts
- A text write fills empty values. It replaces an existing value only with
overwrite: true, and the assistant says so when it uses it. - A write changes only the languages it names. The other languages stay as they are.
set_category_textscan fill one field across many categories from a template with{name},{parent}and{path}.- A name must stay filled in the catalog's default language. A slug must be lowercase and URL-friendly.
New categories
- New categories start hidden. The assistant makes them visible with
update_category(hidden: false) once they have content. - Every new category needs a name in the catalog's default language. Slugs are generated from the names.
- One
create_categoriescall can create a small tree: each category can name a parent created earlier in the same call. - Categories can't move from one catalog to another. A move stays within the catalog.
Main categories
- Every product and cluster has one main category, which applies across all catalogs.
link_productswithmainadds the items to that category first when they aren't in it yet.- An item is never left without a main category. Removing items from their main category keeps them there, reported as
keptBecauseMain, unless the same call gives them a newmain.
Deleting categories
- By default only empty categories are deleted.
includeSubcategoriestakes the whole branch, andunlinkProductstakes its products and clusters out first. - When items have their main category in the branch, the call needs
reassignMainTo, the category that becomes their new main category. - The root category of a channel's catalog can't be deleted.
- A delete can't be undone. Hiding a category with
update_categorycan.
When product lists show a change
Product lists and searches come from a search index that follows changes after a short delay. A product or cluster added to or removed from a category shows after about 10 seconds, a new main category after about 15 seconds and a new order after up to a minute. Category data itself changes immediately.
- A write result says when lists show the change, in
listsShowThisIn. - A list or search made shortly after the same user's change carries
recentChange, so an assistant knows the list may not show it yet. - The tools plan from the user's own recent changes, so an assistant can reorder or remove a product right after linking it.
list_category_products on Filing, four seconds after the two products from the example above were added:
{
"category": { "categoryId": 3120, "name": "Filing", "path": "Office supplies", "catalogueId": 17 },
"total": 0,
"page": 1,
"pages": 0,
"hasMore": false,
"items": [],
"recentChange": {
"secondsAgo": 4,
"note": "changed moments ago: this list may not show it yet (links and main categories take about 10 to 15 seconds)"
}
}
Partial results
| Field | Meaning | What to do |
|---|---|---|
truncated | A scan stopped at its limit | Narrow the filter, for example to one branch |
cappedAtMaxTargets | More items matched than one call changes (500 at most). The rest is untouched. | Split the job with a narrower filter, for example per category or manufacturer |
stoppedEarly | The time budget ended a change partway | Follow the result's note. Most calls continue when run again and skip what was written. A text overwrite lists the categories that are left. |
The assistant tells the user when an answer is partial and never presents a partial count as the total.