Resources and prompts
Resources
Besides tools, the server offers two resource templates. A client reads them like files: they cost no tool call and change nothing. Both answer JSON and work with any secret key of the project.
Mapping
index://{indexId}/mapping
The language of the index and every field with its type and flags (searchable, filterable, facetable, sortable, returnable), the same as get_mapping and the mapping route of the REST API. An agent reads it before it writes a profile, a facet or a rule, so it only uses fields that carry the flag they need.
Stats
index://{indexId}/stats
The status, docCount, activeVersion, buildingVersion and updatedAt of an index. A quick way to see whether an index is READY, still REINDEXING or waiting in NEEDS_REINDEX.
Replace {indexId} with the index id from list_indices. An id that is not a UUID answers 400 VALIDATION_FAILED; an index of another project, or outside the key's index scope, answers 404 INDEX_NOT_FOUND.
Prompts
tune_relevance
A ready-made task for the agent: fix queries that find nothing or find the wrong products. In Claude Code, prompts show up as slash commands, so you start it with /mcp__zaproo-search__tune_relevance followed by the index id and, if you like, the queries.
list_indices.The prompt tells the agent to work in this order:
Read analytics
get_search_analytics for the index, and its zero-result queries, most frequent first.
Learn the index
get_mapping and list_profiles, for the fields and the saved profiles.
Search each query
search with the main profile, noting the total and the top hits.
Propose fixes
Synonym rules (equivalent or one way) and profile changes: query field weights, match, typo tolerance.
Preview
preview_profile against the saved profile before saving anything.
Ask you
The agent shows the before and after and waits for your go.
Apply and check
upsert_synonyms and upsert_profile, then each query is searched again to confirm it now finds products.
The agent can only apply the changes with a full-access key. With a read-only key it stops after the proposal, which is a safe way to let it look without touching anything.
Errors
The server checks the key on every request, before any tool runs.
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHENTICATED | No Authorization: Bearer header, or a key that does not exist. |
| 401 | API_KEY_REVOKED | The key was revoked. |
| 401 | API_KEY_EXPIRED | The key is past its expiry date. |
| 403 | SECRET_KEY_REQUIRED | A public key (zs_pk_…) sent from one of its allowed origins. MCP needs a secret key. |
| 403 | ORIGIN_NOT_ALLOWED | A public key sent without an allowed Origin, which is how a public key from a terminal or a server fails. Use a secret key. |
| 429 | RATE_LIMITED | More than 600 requests a minute for the key, or 1200 for one client IP. The Retry-After header says when to try again. See rate limits. |
Once the key is accepted, problems come back inside the tool result, with isError set and the REST status and code in the text: 403 FORBIDDEN when a read-only key calls a write tool, 404 INDEX_NOT_FOUND for an index the key cannot reach, 400 with one issue per field for invalid input. Errors reading a resource come back as an MCP error with the same status and code.