HeirloomHelp CenterContact support

Agents and MCP

AI shopping assistants can search your products and fill a cart for a customer. Shopify answers these assistants for every store, with nothing to set up. Heirloom adds an optional set of tools that work inside the customer’s browser, so an assistant can also see the page the customer is on and use the same cart as the customer. The Agents and MCP settings control these extra tools, and they’re off until you turn them on.

How assistants work with your store

Two terms come up when you read about AI assistants and online stores:

  • MCP, the Model Context Protocol, is a standard way for an AI assistant to ask a service for information or to take an action, such as “find olive oil under $30”. Shopify runs MCP for every online store, so assistants can search your catalog, build a cart and answer questions about your policies. It’s always on, and no theme setting changes it.
  • WebMCP is the same idea inside a web browser. A page offers tools, and an assistant built into the browser uses them for the customer. Shopify adds its own WebMCP tools to online stores, whichever theme they use.

Heirloom’s agent tools are WebMCP tools. They add what Shopify’s tools can’t know, because they run on the page the customer is looking at:

  • The page the customer is on, such as the product and the options that they’ve selected.
  • Your menus, your store details and the notes that you write for assistants.
  • Product details with subscription options, and product recommendations.
  • The cart, through Heirloom’s cart drawer, so a change that an assistant makes shows up for the customer right away.

Every Heirloom tool name starts with theme_, so assistants can tell Heirloom’s tools apart from Shopify’s.

What Heirloom’s tools can’t do

Heirloom’s tools stop at the cart. None of them completes checkout, enters payment details or changes customer accounts.

Customers don’t see the tools. With agent tools off, Heirloom adds no agent tools or script to your pages. With them on, Heirloom loads one small script, and nothing on the page changes.

Open theme settings

Steps:

  1. From your Shopify admin, go to Online Store > Themes.
  2. Find Heirloom, and then click Edit theme.
  3. Click the Theme settings icon.
  4. Click Agents and MCP.

Turn on agent tools

Steps:

  1. In the Agents and MCP settings, check Enable agent tools.
  2. Under Tool groups, check the groups that you want assistants to use.
  3. Under What agents should know, enter your Notes for agents.
  4. Click Save.

The tool groups are:

  • Catalog and store context: reading tools that describe your store, your menus, the current page, search results, product details and recommendations. They don’t change anything. The menus come from the menus with the handles main-menu and footer in your Shopify admin, whichever menus your header and footer show.
  • Cart: reading the cart, adding a product, changing a quantity and setting the cart note.
  • Subscriptions: subscription options in product details, and adding a subscription to the cart. Turn it off to hide subscriptions from assistants. Customers can still buy subscriptions as usual.
  • Discount codes: lets an assistant try a discount code on the customer’s cart. A code that doesn’t apply is removed straight away, so a wrong guess never reaches checkout. It’s off by default, because which codes to offer is your decision.

Write notes for agents

Notes for agents is text that assistants receive when they ask about your store, word for word. Write what a good shop assistant would tell a customer and a product page can’t, for example:

  • How you’d like your store described, such as “family-run olive grove, harvested by hand”.
  • What you recommend as a gift.
  • Shipping details, such as “glass ships upright, Monday to Thursday”.
  • Anything you don’t ship, or don’t ship to some places.

Create an agent guide page

The agent guide is a page on your online store that briefs people and assistants at the same time. It shows your page content, followed by a store summary: your notes for agents, your free shipping threshold (Free shipping threshold in the Cart settings), your policies and your main menu (the menu with the handle main-menu). The same facts are included in a form that assistants read, and the page works without JavaScript, so assistants that only read a page’s HTML get the briefing too.

Steps:

  1. From your Shopify admin, go to Online Store > Pages, and then click Add page.
  2. Give the page a title, such as “For AI shopping assistants”, and write what you’d like assistants to know.
  3. Under Theme template, select agents.
  4. Click Save.
  5. In the theme editor, in the Agents and MCP settings, under Agent guide page, select the page.
  6. Click Save.

Heirloom’s tools give assistants the address of the page that you select. If a page that uses the agents template has no content of its own, it shows the content of the selected page instead.

Agent guide section

The agents template uses the Agent guide section. It shows the page’s breadcrumbs, title and content, then the store summary, then any blocks that you add. The section isn’t in the Add section list, because it belongs to the agents template.

You can add these blocks:

  • Custom Liquid
  • App blocks from apps you install

Section style

  • Color scheme: The colors of the guide page.
  • Vertical padding: The space above and below the guide. Options: None, Small, Medium, Large. Default: Large.

Store summary

The store summary is a fixed block in the Agent guide section, named Agent guide.

  • Show the store summary: Adds the generated policy, shipping, and navigation summary under the page content. On by default.

With Show the store summary off, people don’t see the summary, but assistants still get the same facts from the page.

Agent attribution

Shopify records which sales channel an order came from, but an order from a cart that an assistant filled in a customer’s browser looks like any other online store order. With Tag carts that agents change on, Heirloom marks those carts so you can tell them apart. It works whether agent tools are on or off, because Shopify’s own browser tools change carts too.

The first time an assistant changes a cart that has products in it, Heirloom adds a hidden cart attribute named _epl_agent, which carries over to the order. It’s added once per cart, so it shows the first way that the cart was changed. To find it, open the order in your Shopify admin and look in its additional details:

  • theme-webmcp means one of Heirloom’s tools changed the cart.
  • shopify-actions means the cart was changed through Shopify’s cart actions, which Shopify’s own assistant tools and some apps use.

Heirloom also publishes a customer event named epl:agent_cart each time an assistant changes the cart. The event says which path and tool made the change, what kind of change it was, such as adding a product or applying a discount code, and how many lines the cart has. To count these, add a custom pixel that subscribes to it in Settings > Customer events.

Settings

  • Enable agent tools: Off by default. When on, the theme loads a small script that offers its tools to agent-aware browsers. Shoppers see no change to the page. Off by default.
  • Tag carts that agents change: Tags agent-changed carts for orders and custom pixels, even with agent tools off. On by default.

Tool groups

  • Catalog and store context: Store context, navigation, current page context, product search, product detail, and recommendations. Read-only. On by default.
  • Cart: Read the cart, add a variant, change a line quantity, and set the cart note. An agent can fill the cart, but it never completes checkout. On by default.
  • Subscriptions: Includes selling plan groups (intervals and discounts) in product detail, and lets an agent add a subscription line. Turn this off to hide subscriptions from agents entirely. On by default.
  • Discount codes: Off by default. Lets an agent try a discount code on the shopper's cart, and removes any code that does not apply. Off by default.

What agents should know

  • Notes for agents: Free text handed to any agent that asks for store context. Worth saying: your tone, shipping quirks, what you recommend as a gift, and anything you will not ship.
  • Agent guide page: The page whose content backs the agent guide template. Create a page, apply the Agents template to it, then pick it here.