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.

Setup

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.

“What are shoppers searching for that finds nothing?” Search analytics

“Which of my pages perform best?” Pages analytics

“Which products should I promote this Tuesday?” Product Intelligence

Troubleshoot data

Trace catalog problems and check what Search can use.

“Why does this product show the wrong price or availability?” Product dataFeeds

“Which fields can I filter and sort Search by?” Data fields

“Show me the failed API calls for my website from the last day.” API log

Design experiences

Review and reshape the interfaces your customers see.

“Make the search field more prominent in my overlay Search design.” Search

“Make the product titles larger in my Recommendations box.” Recommendations

“Redesign the product tiles in my newsletters.” Newsletter Content

“Give my category pages a new look.” Pages

Manage your setup

Inspect your account and operate Product Agents.

“Turn on the Replenishment Reminder agent.” Product Agents settings

“How are my Product Agents performing?” Product Agents analytics

“What websites and configurations does my account have?” Website

“Who changed my Search configuration last, and what did they change?” Audit log

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.

Four more tools are immediate, because what they change isn't rendered to shoppers:

Tool	When it takes effect
`updateProductFieldsIndexing`, `updateContentFieldsIndexing`	Immediately, and any real change starts a full catalog re-index, which is slow on a large catalog. Batch every field into one call.
`createProductFeed`, `updateProductFeed`	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 getProductFields, getContentFields, getProductFeed or newsletterContent_getDesign. 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.

Company ID

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).

List the websites for company <your company ID>.

Website UUID

Every other tool needs one

website_getInfo and website_listForCompany return the website UUID that every other tool needs as input.

List the websites for my company and show me each one's UUID.

Quick win

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.

Show the top searches with no results for my website over the last 30 days.

Read or write

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.

Which Hello Retail MCP tools can change data, and which are read-only?

Sign-in

OAuth happens on first use

The assistant handles OAuth login on first use and reuses the token until it expires.

Connect to the Hello Retail MCP server and confirm you can call its tools.