AI agents (MCP)

MCP tools

Every tool the Zaproo Search MCP server offers, what an agent can do with each group, and prompts to start from.

How the tools work

Each tool runs the same service as the matching REST route, with the same validation, the same error codes and the same audit log. A tool acts on the project of the secret key the client connected with, and only on the indices in the key's index scope when it has one.

Read tools work with any secret key. Write tools need a key with full access; a read-only key gets 403 FORBIDDEN back as a tool error.
Writes to documents, reindex and suggestion rebuilds are asynchronous. The tool answers a taskId at once, and get_task tells when the work is done: SUCCEEDED, PARTIAL, FAILED or CANCELLED.
Search tools answer at most 10 hits, so a result fits the agent's context. Paging still works.
A failed call is a tool result, not a crash. It carries the REST status and code, for example 400 PROFILE_INVALID with one issue per field, so the agent can fix its input and try again.

All tools

The same list is on the project's MCP connection page in the cabinet. To connect a client, see MCP setup.

MCP tools
Tool	What it does
`list_indices`	List the indices of the project with status and document count
`get_index`	One index: status, document count and versions
`create_index`	Create an index; by default its mapping is inferred from the first upload
`update_index`	Rename an index; search, keys and plugins keep working
`delete_index`	Delete an index with everything in it, after repeating its name
`get_mapping`	The language and every field of an index with its flags
`update_mapping`	Replace the mapping; the answer says whether a reindex is needed
`update_fields`	Change only the named fields and leave the rest of the mapping as it is
`get_facets`	The facets of an index, which profiles without their own show
`update_facets`	Replace the index facets, labels and order included
`reindex`	Rebuild the index into a new version and swap it in without downtime
`index_documents`	Add or replace up to 1000 documents (asynchronous, returns a task id)
`delete_documents`	Delete up to 1000 documents by id (asynchronous)
`flush_documents`	Delete every document of an index, irreversibly; the settings stay (asynchronous)
`get_task`	Poll an asynchronous write: status, counts and per-document errors
`get_document`	Read one stored document by id
`search`	Search with a saved profile or an inline one, with filters, sort and facets
`list_profiles`	The search profiles of an index and their profile keys
`upsert_profile`	Create or replace a search profile
`preview_profile`	Compare an unsaved profile with the saved one for the same query
`list_synonyms`	The synonym rules of an index, page by page
`upsert_synonyms`	Create or replace a synonym rule (equivalent or one way)
`delete_synonyms`	Delete one synonym rule
`list_rules`	The ranking rules of an index in the order they run, with what needs attention
`upsert_rule`	Create or replace a ranking rule: pin, hide, boost or filter products for chosen searches
`delete_rule`	Delete one ranking rule
`reorder_rules`	Set the order ranking rules run in
`test_rule`	Run a search with the rules that fire, and compare a draft rule before saving it
`suggest`	Autocomplete a partial query, with facet hints
`rebuild_suggestions`	Rebuild the autocomplete index from recent searches (asynchronous)
`list_assistant_conversations`	The shopping assistant conversations, newest first, page by page
`get_assistant_conversation`	One shopping assistant conversation with its messages and tool calls
`list_assistants`	The shopping assistants of the project with their state and widget keys
`create_assistant`	Create a shopping assistant; it starts disabled
`get_assistant`	One shopping assistant with its settings and widget key
`update_assistant`	Replace the settings of an assistant: sources, instructions, origins, appearance
`set_assistant_enabled`	Switch an assistant live or off
`regenerate_assistant_key`	Issue a new widget key; the old one stops working
`delete_assistant`	Delete an assistant
`test_assistant`	Run one test turn of an assistant, with a draft or the saved settings; uses tokens
`get_search_analytics`	The analytics overview: searches, CTR, conversion, revenue and latency with a comparison, plus the timeline
`get_analytics_report`	One report: queries, no-click, products, positions, filters, autocomplete, rules, refinements or opportunities
`get_query_analytics`	One query day by day, with the synonyms and rules that touched it and the before/after

Indices and mapping

list_indices, get_index, create_index, update_index, delete_index, get_mapping, update_mapping, update_fields, get_facets, update_facets, reindex.

An agent can create, rename and delete an index, read and change its fields and flags, set the facets every profile shows by default, and rebuild the index after a breaking mapping change. update_fields changes only the fields it names, with null to remove one, so an agent can change one field's type, flags or text analysis without resending the whole mapping. update_mapping replaces the whole mapping and the language. Both answer a diff: an additive change applies at once, a breaking one leaves the index NEEDS_REINDEX until the agent calls reindex. A change that would break a profile, rule, facet, autocomplete field or data source is refused with 409 MAPPING_BREAKS_CONFIG, and the tool error lists each use, so the agent changes those first. While a shop plugin manages the mapping, get_index shows it under integration, and removing a field is refused with 409 MAPPING_MANAGED_BY_INTEGRATION. delete_index removes the index with everything in it and cannot be undone. Its name must repeat the index name exactly, or it fails with 400 INDEX_NAME_MISMATCH, and the agent is told to ask you before it calls it.

Create an index called products in German. Then show me its mapping after the first upload
and make brand and color facetable.

Make the title field use normalizeCodes, check whether that needs a reindex, and if it does,
start it and tell me when it is done.

Index attributes.width as a number and show it as a range slider facet. Turn off number splitting
on the school field. Reindex if either change needs it.

Documents and tasks

index_documents, delete_documents, flush_documents, get_task, get_document.

An agent can add or replace up to 1000 documents per call, delete up to 1000 by id, read one stored document and follow a task to the end. Per-document errors appear on the task. flush_documents deletes every document of an index and cannot be undone: every version goes, the live one included, while the configuration and keys stay. See Delete all documents.

Upload the products in ./catalog.json in batches of 1000, wait for every task,
and list the documents that failed with the reason.

Search and profiles

search, list_profiles, upsert_profile, preview_profile.

An agent can search with a saved profile or with an unsaved one, compare an edited profile with the saved one for the same query, and save it once the results look right. upsert_profile replaces the whole profile, so the agent should read it with list_profiles first.

search takes the same body as the search API: filters with $or, $and and $not groups, fields to trim each hit to the fields the agent needs, and excludeIds. Asking for fewer fields keeps the answer short.

Search "bubble wrap" with the storefront profile. Then try the same profile with phrase boost 4
and typo tolerance 1, compare the top 10, and only save it if more bubble wrap rolls rank first.

Synonyms

list_synonyms, upsert_synonyms, delete_synonyms.

An agent can list synonym rules, add or change an equivalent rule (box, carton) or a one-way rule (scotch => tape), and delete one. A change applies to the next search without a reindex.

Our shoppers write "scotch" but the catalog says "tape". Add a one-way synonym
and check that "scotch" now finds products.

Ranking rules

list_rules, upsert_rule, delete_rule, reorder_rules, test_rule.

An agent can pin, hide, boost or filter products for chosen searches, schedule a rule for a campaign, set the order rules run in, and test a draft rule against the saved ones before saving it. list_rules also lists each rule's issues, for example a filter on a field that a later mapping change made unfilterable.

For the query "moving boxes", pin products box-300, box-400 and tape-48 in that order from
2026-11-27 to 2026-11-30. Test it first and show me the top 5 before and after.

Autocomplete

suggest, rebuild_suggestions.

An agent can try what the search box suggests for a partial query and rebuild the suggestions after a catalog change.

Shopping assistant

list_assistants, create_assistant, get_assistant, update_assistant, set_assistant_enabled, regenerate_assistant_key, delete_assistant, test_assistant, list_assistant_conversations, get_assistant_conversation.

An agent can create and configure the project's storefront assistants, switch them on and off, rotate their widget keys, and read their conversations with messages and tool calls. update_assistant replaces the whole configuration, appearance included, so read the assistant with get_assistant first. test_assistant runs one turn of an assistant, with a draft configuration or the saved one, and returns the reply, products, tool calls and token usage; it stores nothing but the tokens, which count toward the monthly limit. Writes and tests need a FULL key.

Analytics

get_search_analytics, get_analytics_report, get_query_analytics.

The three tools read what the Analytics page shows, with the same from, to, compare, device, country and includeInternal parameters. get_search_analytics is the overview: searches, sessions, zero-result rate, click-through, add-to-cart and conversion rates, revenue and latency, each against the comparison window, plus the timeline. get_analytics_report takes a report name (queries, no-click, products, positions, filters, autocomplete, rules, refinements or opportunities) and answers its rows; see Reports. get_query_analytics takes q and answers one query day by day, with the synonyms and rules that touched it and the numbers before and after the latest one.

There is no tool for sending events: those come from the storefront. See Event tracking.

Start relevance work from the opportunities list, or use the tune_relevance prompt, which runs the whole loop.

Which searches lost us the most money last week? For the top ten, propose synonyms or rules,
test them and wait for my go before applying anything.

Show me "scotch" over the last 90 days. Did the synonym we added in September change anything?

What the tools do not cover

Some work stays in the cabinet or the REST API: API keys, members and billing, data sources, full catalog sync with replace sessions, custom suggestions and the autocomplete settings, and the synonym file import and export.

Searches the search tool runs with a saved profile are logged as mcp traffic. They never feed autocomplete, and analytics shows them only with Include internal traffic. preview_profile and test_rule are not logged.

MCP setup

Connect Claude Code or another MCP client to your project from the cabinet's MCP connection page, and let an agent manage indices, documents, profiles, synonyms and rules.

Resources and prompts

The index resources an MCP client can read, the tune_relevance prompt, and the errors the MCP server answers.