Getting started¶
More endpoints on the way
This is just the start: we're actively rolling out more MCP tools. If the endpoint you're looking for isn't here yet, check back soon, or reach out at support@helloretail.com and let us know what you need.
The Model Context Protocol (MCP) server lets AI assistants call Hello Retail APIs as tools. Supported clients include Claude (Code, Desktop, and Projects), OpenAI Codex, and ChatGPT. Ask in plain language; the assistant works out which tools to call and in what order.
Pointing an assistant at these docs? /mcp/llms.txt lists every MCP page as plain Markdown.
What you can ask¶
Choose a goal, then ask your assistant in plain language. These prompts are ready to use as they are.
Find opportunities
Turn customer and product data into your next action.
Troubleshoot data
Trace catalog problems and check what Search can use.
Design experiences
Review and reshape the interfaces your customers see.
Manage your setup
Inspect your account and operate Product Agents.
What a write actually changes¶
Most tools are read-only, and the ones that write are marked on their tool page with a Write operation warning. Your assistant asks for confirmation before running any of them.
No MCP tool publishes. When you update a solution that has a draft and a live state, the change always lands in the draft, so you can verify it and push it live yourself from My Hello Retail. That covers search configs, Recommendations boxes and designs, and Pages and page designs. Editing a LIVE search config forks a new draft from it; editing a LIVE Recommendations box or Page leaves that box or page in DRAFT. The live version keeps serving the whole time.
Newsletter Content designs are the exception among the rendered solutions, because they have no draft and live states: a save is immediately the design's only version. What it doesn't do is rewrite the newsletters that have already gone out. Manual and Rolling campaigns keep their own copy of the template and go on rendering it until someone re-saves the campaign with that design selected; Auto campaigns follow the design, but each send freezes it, so sends that already went out keep the old look. Because tile images are fetched when the recipient opens the mail, an edit that does reach a campaign also changes the pictures in mail already sitting in inboxes. To change a design that live campaigns render, copy it with newsletterContent_copyDesign, edit and render the copy, and point campaigns at it from the dashboard.
Search engines and their query rules are the other one. A search config has a draft and a live state, but the engine it points at has neither, so a change to an engine's search steps, boosts, elevates, excludes or personalization, or to one of its query rules, is live for every config using that engine as soon as it is saved. Boosts can take up to five minutes, the lifetime of their cache. search_listProductEngines names the configs each engine serves, so check that before you edit. Pointing a config at a different engine with search_setConfigProductEngine is a normal config edit and does go through a draft.
The remaining write tools are immediate, because what they change isn't rendered to shoppers, though some of it reaches the search index only on the next re-index:
| Tool | When it takes effect |
|---|---|
dataFields_updateProductFieldsIndexing, dataFields_updateContentFieldsIndexing | Immediately, but the catalog reflects a change only once it has been re-indexed. A run is scheduled a few minutes out, so batch every field into one call and later edits join that run. |
search_addSynonyms, search_updateSynonym, search_deleteSynonym, search_replaceSynonyms | Immediately, but visitors see it only once the product catalog has been re-indexed. That run is scheduled for you, on the same few-minute delay. |
search_addStopWords, search_updateStopWord, search_deleteStopWord, search_replaceStopWords | For the next search. The indexed product text catches up on the next re-index. |
feeds_create, feeds_update | Immediately. A new feed starts INACTIVE, so it won't run until you activate it. |
To undo a draft, leave it unpublished or discard it in My Hello Retail. The tools that take effect immediately have no undo, so read the current state first, with dataFields_getProductFields, dataFields_getContentFields, feeds_get, search_listSynonyms, search_listStopWords, newsletterContent_getDesign or the engine get tools. That leaves you the old values to write back.
Your first call¶
After connecting (see Installation & setup), ask your assistant to "list the websites for my company", then use a returned website UUID to explore its search or analytics tools.
Tips & tricks¶
Pick the card that matches what you're doing. Each prompt is ready to paste into your assistant.
Find it in your profile
Calls like website_listForCompany need your company ID. Find it in my.helloretail.com via the profile icon (top-right) → Company Profile, in the Company Id field (see the website tools guide for a screenshot).
Every other tool needs one
website_getInfo and website_listForCompany return the website UUID that every other tool needs as input.
Start with the empty searches
Search analytics tools reveal how visitors search. Start with the top searches that return no results, since those are quick wins for synonyms or new content. See the search analytics tools for the full set.
Know which tools change data
Tools are read-only unless their description states otherwise. Ask your assistant which write tools are available so you know what to expect when a confirmation prompt appears.
OAuth happens on first use
The assistant handles OAuth login on first use and reuses the token until it expires.