# Connect your AI (MCP)

Connect Claude, Cursor or another AI straight to your store, with nothing to
install and no key to copy. You just talk ("make a Black Friday banner at the
top"), the AI reads the theme guide, edits the draft, sends you the preview
link and asks to publish. A person always publishes, in the dashboard.

There is one address, for any app that supports MCP:

```text
https://mcp.hystore.com.br/mcp
```

> [!NOTE]
> MCP (Model Context Protocol) is the open standard AI apps use to talk to
> other services. The app keeps the address, signs you in through the Hystore
> dashboard and gets the theme tools.

## Before you start

- The store's plan must include **Code theme** with the **Connect your AI**
  option. Without it, the dashboard refuses the authorization and an existing
  connection stops answering.
- The person who authorizes is someone in the store with theme permissions
  (see [Permissions](/en/code-theme/#permissions)). The AI never does more
  than that person can.
- Each connection is for **one store**. To edit another store, connect again
  and pick the other store on the authorization screen.

## The path, in any app

1. Add the address `https://mcp.hystore.com.br/mcp` to the app as a remote MCP
   server (HTTP). Each app's steps are right below.
2. The app opens the browser on the **Connect an AI to your store** screen, in
   the Hystore dashboard. If you are not signed in, sign in first.
3. Check the app's name, pick the store and what the AI may do, and click
   **Authorize**.
4. Go back to the app. The connection shows as active, with the Hystore tools.
5. Ask something, for example: *"Use Hystore and tell me which store you are
   editing."*

## Claude (web and app)

This works for [claude.ai](https://claude.ai) and for the Claude app on the
computer and the phone: connectors belong to your account.

1. Open **Settings > Connectors**.
2. Click **Add custom connector**.
3. Fill in the name `Hystore` and the URL `https://mcp.hystore.com.br/mcp`.
4. Click **Add** and then **Connect**. The browser opens the Hystore
   dashboard: authorize (see [the authorization screen](#the-authorization-screen)).
5. In a new chat, open the chat's tools menu and check that **Hystore** is on.

> [!TIP]
> In the first message, ask: *"Read the Hystore theme guide and show me the
> files of my theme."* That way the AI learns the format before editing.

Custom connectors depend on your Claude plan. In company accounts (Team,
Enterprise), whoever manages the organization adds the connector in the
organization settings, and each person connects their own account afterwards.

## Claude Code

In the terminal, once:

```bash
claude mcp add --transport http hystore https://mcp.hystore.com.br/mcp
```

To have Hystore in every project, not only the current folder, add
`--scope user`:

```bash
claude mcp add --transport http --scope user hystore https://mcp.hystore.com.br/mcp
```

Then:

1. Run `claude` in the folder you work in.
2. Type `/mcp`, pick **hystore** and then **Authenticate**.
3. The browser opens the dashboard: authorize and go back to the terminal.
4. Ask: *"Use hystore to list the files of my theme."*

> [!TIP]
> Prefer the theme as files on your computer, with git? Use the
> [hystore tool](/en/code-theme/cli/): Claude Code reads the `CLAUDE.md` it
> writes and edits the files right in the folder.

## Cursor

1. Open **Cursor Settings > MCP** (in newer versions, *Tools & Integrations*)
   and click **New MCP Server**. Cursor opens the `mcp.json` file.
2. Paste:

```json ~/.cursor/mcp.json
{
  "mcpServers": {
    "hystore": { "url": "https://mcp.hystore.com.br/mcp" }
  }
}
```

3. Save. Hystore shows in the list asking to sign in: click **Connect** (or
   *Login*) and authorize in the browser.
4. In Cursor's chat (Agent mode), ask: *"Use hystore to read the file
   layout/theme.liquid."*

For a single project, use `.cursor/mcp.json` inside the project folder, with
the same content.

## VS Code (GitHub Copilot)

1. Create the file `.vscode/mcp.json` in the project (or run the **MCP: Add
   Server...** command and pick HTTP):

```json .vscode/mcp.json
{
  "servers": {
    "hystore": { "type": "http", "url": "https://mcp.hystore.com.br/mcp" }
  }
}
```

2. Click **Start**, shown above `"hystore"` in the file. VS Code asks to sign
   in: accept and authorize in the browser.
3. Open Copilot Chat in **Agent** mode, click the tools icon and check that
   the hystore tools are selected.

## Windsurf

In **Windsurf Settings > Cascade > MCP Servers**, open the configuration file
and paste:

```json ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "hystore": { "serverUrl": "https://mcp.hystore.com.br/mcp" }
  }
}
```

Refresh the server list and connect; the sign-in opens in the browser.

## Other apps

Look in the app for *custom connector*, *remote MCP server* or *MCP over
HTTP* and use the same address. No key or header is needed: the app finds
where to sign in by itself (from the documents at
`https://mcp.hystore.com.br/.well-known/`) and opens the dashboard. If the app
only accepts local servers (command line), use the
[hystore tool](/en/code-theme/cli/) instead of MCP.

## The authorization screen

When the app asks for access, the dashboard shows **Connect an AI to your
store**:

- **The app's name**, as the app itself says it. Check it is the app you are
  connecting.
- **Where the access goes.** When it is a program on your computer (Claude
  Code, Cursor, VS Code), the screen warns you: only authorize if you just
  asked for it.
- **The store** the AI will edit.
- **What the AI may do**, with boxes to untick:

| On the screen | The AI may |
|---|---|
| Read the theme files | read files, versions, images and the public catalog |
| Change the draft files | create, change and delete files and images of the draft |
| Request a publish | send the draft for someone to approve in the dashboard |

Click **Authorize** and go back to the app. **Refuse** gives no access at all.

> [!WARNING]
> If the screen opens without you asking for anything, click **Refuse**.
> Nobody from Hystore asks you to authorize apps.

## Example requests

Write as you would to a person. Some that work well:

- *"Read the theme guide and explain how my theme is organized."*
- *"On the home page, change the top title to 'Season 5 is here' in
  Portuguese, English and Spanish."*
- *"Create a Black Friday section with a countdown to 11/28 at 23:59 and a
  button to the vips category. Put it at the top of the home."*
- *"Show the 8 newest products of the kits category in cards with a buy
  button."*
- *"Change the accent colour to gold and make the buttons rounder."*
- *"Send me the preview link."*
- *"Check the whole theme and fix the errors."*
- *"Ask to publish with the note 'Black Friday banner'."*

After the publish request, open **Customization > Code theme > Publish
requests**, see what changed and click **Approve and publish** (or
**Refuse**).

## What the AI can do

| Tool | Does |
|---|---|
| `read_theme_guide` | reads the [theme guide](/en/code-theme/guide/), whole or one part |
| `get_store` | the store's name and address, the connection's permissions |
| `list_theme_files`, `read_theme_file` | reads the draft |
| `write_theme_files` | creates, changes or deletes draft files, up to 100 at once |
| `check_theme` | checks the whole draft |
| `get_preview_link` | a 24-hour link to the draft on the store's address |
| `request_publish` | asks to publish; someone approves in the dashboard |
| `list_versions`, `read_version_file`, `restore_version` | published versions and bringing one back to the draft |
| `list_assets`, `upload_asset`, `delete_asset` | the theme's images and fonts |
| `read_catalog` | active categories and products, only what a visitor sees |

Each tool's arguments and examples are in the
[MCP reference](/en/code-theme/mcp-reference/#tools).

Each file goes through the same check as in the dashboard: a file with an
error goes back to the AI with the line and the reason, and nothing is saved.
If someone changed the file in the dashboard meanwhile, the write is refused
instead of erasing that change.

The AI does **not** reach orders, payments, balance, players, coupons or
settings, and it never publishes by itself.

## Disconnect

The connection lasts 30 days and renews itself while the app is used. It shows
in **Customization > Theme access > Connected sessions**, marked as *AI app*,
with the app's name. **Disconnect** cuts the access at once.

For every connected app, the store owner gets an e-mail with the link to
disconnect. Every change made by the AI goes into the theme history with the
MCP origin.

## Common problems

| What happens | What to do |
|---|---|
| The dashboard says the store does not have the option | The plan needs **Code theme** with **Connect your AI**; also check Settings > Modules |
| The **Authorize** button does not show | Your role needs theme permissions; ask the store owner |
| The app says the connection expired | Disconnect and connect again; a connection unused for 30 days stops working |
| The AI edited, but the store did not change | It edits the **draft**. Look at the preview and approve the publish request |
| The AI says a file was refused | The message has the line and the reason; ask it to fix it. See [Common problems](/en/code-theme/faq/) |
| The AI is editing the wrong store | Disconnect in Connected sessions and connect again picking the right store |

For people who build apps and integrations, the sign-in, the routes and the
messages are in the [MCP reference](/en/code-theme/mcp-reference/).