# Shopify (/docs/quickstart/shopify)

On Shopify, AI Connect comes as an app with a theme app extension. Its app embed adds the chat of the [Web Components](/docs/modules/web-components) to every page of the store once the merchant switches it on in the theme editor. The shopper's model reads the store's catalog through an MCP server the app serves on the store's own domain, and answers on the shopper's account through AI Wallet.

<Callout type="warn">
The Shopify app is not on the Shopify App Store yet. Its code is in `integrations/shopify` of the AI Connect repository: the app, its theme app extension and its catalog MCP server, tested end to end against a played Storefront API.
</Callout>

## The app embed [#the-app-embed]

In the theme editor, under **App embeds**, the merchant switches on **AI chat** and sets it:

| Setting | What it sets |
| --- | --- |
| Form | `Popup, opened from a button` (the default) or `Panel at the page edge`. |
| Button label | The text of the button that opens the chat. |
| Heading | The chat's heading. |
| Instructions for the visitor's AI | What the shopper's model is told before the first question. By default it searches the catalog before it recommends a product. |
| MCP server address | `/apps/aiconnect/mcp` by default, the app proxy path of the catalog MCP server. |
| Site key | The store's [site key](/docs/quickstart/site-key), which offers **Sign in with TensorPass** to a shopper without AI Wallet. Left empty, the chat offers **Sign in with OpenRouter** beside the wallet's install button. |

A site key names one domain, so a store takes the key of the domain its shoppers visit, such as `shop.example` or `example.myshopify.com`. The [web accounts page](/docs/providers/web-accounts) describes both sign ins.

The chat speaks the store's language when it is English, French, Hebrew, Arabic or Chinese, and English otherwise. A store in traditional Chinese gets the chat in simplified Chinese.

Shopify allows 10 KB for the script of an app embed, and the Web Components script weighs 707 KB. The embed's script is therefore the loader, `aiconnect-loader.js` (9.5 KB, 3.7 KB compressed), which `@tensorpass/aiconnect-elements` builds next to the Web Components script. It draws the chat's button at once, in the chat's own look, and loads the chat when the shopper points at the button, focuses it or presses it. The chat's own button then takes the loader's place. Any page with a tight script budget can use the loader the same way: load `aiconnect-loader.js`, and put the address of `aiconnect-elements.js` on each element in `data-elements-src`.

## The catalog MCP server [#the-catalog-mcp-server]

The chat calls its MCP server from the shopper's page, so the server answers on the store's domain through a Shopify [app proxy](https://shopify.dev/docs/apps/build/online-store/app-proxies): Shopify forwards `/apps/aiconnect/mcp` to the app's server, signed, and the browser sees one origin. The app's server reads the store through the Storefront API and answers MCP with three tools:

| Tool | What it returns |
| --- | --- |
| `search_products` | The products that match the shopper's words, each with its handle, title, price range, stock and the address of its page. |
| `get_product` | One product in full: its description, its options, each variant with its price and stock, its collections. A product sold in one form shows no options. |
| `list_collections` | The store's collections, each with a short summary and the address of its page. |

Each read has a time limit of 8 seconds: a slow store gives the chat an error the shopper's model can pass on. The server answers only the calls Shopify signed, and tells a store without the app that the app is not installed.

The app's page in Shopify's admin opens the theme editor with the embed switched on, and holds the store's [guards](/docs/modules/guards) for the catalog: names and content kept out of the chat, one regular expression per line, up to 50 lines of 200 characters in each field. The server holds back any result that matches one of them, since anyone can call it without the store's page. Every store shares that server, so it reads each result within 50 milliseconds: a pattern that takes longer holds back every result of its store until the merchant changes it, and the other stores are answered as before.

When a store uninstalls the app, and again when Shopify asks for the store's erasure, the server removes the store's sessions with the tokens that read its catalog. It keeps nothing about shoppers.

Shopify's own [Storefront Catalog MCP](https://shopify.dev/docs/agents/catalog/storefront-catalog), at `/api/ucp/mcp`, expects an agent profile in the arguments of every call, which the shopper's model has no way to add, so the app's server sits between the two.

## Run it on a development store [#run-it-on-a-development-store]

The steps, each a script in `integrations/shopify/scripts`, are in that folder's README: link the app created in the Dev Dashboard, put its server on a host, publish the app with its extension, install it on the development store, and switch on the embed.

`npm run e2e` in `integrations/shopify` runs Shopify's theme check on the extension, then the end to end tests: the loader on a store page rendered from the embed's Liquid, the app's server behind its signature checks, and a shopper with AI Wallet answered from the store's catalog.
