# Conectar a IA (MCP)

Conecte o Claude, o Cursor ou outra IA direto na sua loja, sem instalar nada e
sem copiar chave. Você conversa normalmente ("faz um banner de Black Friday no
topo"), a IA lê o guia do tema, edita o rascunho, te manda o link da prévia e
pede a publicação. Quem publica é sempre uma pessoa, no painel.

O endereço é um só, para qualquer app compatível com MCP:

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

> [!NOTE]
> MCP (Model Context Protocol) é o padrão aberto que os apps de IA usam para
> conversar com outros serviços. O app guarda o endereço, faz o login com você
> pelo painel da Hystore e passa a ter as ferramentas do tema.

## Antes de começar

- O plano da loja precisa incluir **Tema em código** com a opção **Conectar a
  IA**. Sem ela, o painel recusa a autorização e uma conexão já feita para de
  responder.
- Quem autoriza é alguém da loja com permissão no tema (veja
  [Permissões](/pt/code-theme/#permissoes)). A IA nunca faz mais do que essa
  pessoa pode.
- Cada conexão vale para **uma loja**. Para editar outra loja, conecte de novo
  e escolha a outra loja na tela de autorização.

## O caminho, em qualquer app

1. Adicione o endereço `https://mcp.hystore.com.br/mcp` no app, como servidor
   MCP remoto (HTTP). Os passos de cada app estão logo abaixo.
2. O app abre o navegador na tela **Conectar uma IA à sua loja**, no painel da
   Hystore. Se você não estiver logado, entre primeiro.
3. Confira o nome do app, escolha a loja e o que a IA pode fazer e clique em
   **Autorizar**.
4. Volte para o app. A conexão aparece como ativa, com as ferramentas da
   Hystore.
5. Peça alguma coisa, por exemplo: *"Use a Hystore e me diga qual loja você
   está editando."*

## Claude (site e aplicativo)

Vale para [claude.ai](https://claude.ai) e para o aplicativo do Claude no
computador e no celular: os conectores ficam na sua conta.

1. Abra **Configurações > Conectores**.
2. Clique em **Adicionar conector personalizado**.
3. Preencha o nome `Hystore` e a URL `https://mcp.hystore.com.br/mcp`.
4. Clique em **Adicionar** e depois em **Conectar**. O navegador abre o painel
   da Hystore: autorize (veja [a tela de autorização](#a-tela-de-autorizacao)).
5. Numa conversa nova, abra o menu de ferramentas da conversa e confira que
   **Hystore** está ligado.

> [!TIP]
> Na primeira mensagem, peça: *"Leia o guia do tema da Hystore e me mostre os
> arquivos do meu tema."* Assim a IA aprende o formato antes de editar.

Os conectores personalizados dependem do plano da sua conta no Claude. Em
contas de empresa (Team, Enterprise), quem administra a organização adiciona o
conector nas configurações da organização, e cada pessoa conecta a própria
conta depois.

## Claude Code

No terminal, uma vez:

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

Para ter a Hystore em todos os projetos, e não só na pasta atual, acrescente
`--scope user`:

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

Depois:

1. Rode `claude` na pasta onde você trabalha.
2. Digite `/mcp`, escolha **hystore** e depois **Authenticate**.
3. O navegador abre o painel: autorize e volte para o terminal.
4. Peça: *"Use a hystore para listar os arquivos do meu tema."*

> [!TIP]
> Prefere o tema como arquivos no seu computador, com git? Use a
> [ferramenta hystore](/pt/code-theme/cli/): o Claude Code lê o `CLAUDE.md` que
> ela cria e edita os arquivos direto na pasta.

## Cursor

1. Abra **Cursor Settings > MCP** (em versões novas, *Tools & Integrations*) e
   clique em **New MCP Server**. O Cursor abre o arquivo `mcp.json`.
2. Cole:

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

3. Salve. A Hystore aparece na lista pedindo login: clique em **Connect** (ou
   *Login*) e autorize no navegador.
4. No chat do Cursor (modo Agent), peça: *"Use a hystore para ler o arquivo
   layout/theme.liquid."*

Para valer só num projeto, use `.cursor/mcp.json` dentro da pasta do projeto,
com o mesmo conteúdo.

## VS Code (GitHub Copilot)

1. Crie o arquivo `.vscode/mcp.json` no projeto (ou rode o comando **MCP: Add
   Server...** e escolha HTTP):

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

2. Clique em **Start**, que aparece em cima de `"hystore"` no arquivo. O VS Code
   pede para entrar: aceite e autorize no navegador.
3. Abra o chat do Copilot em modo **Agent**, clique no ícone de ferramentas e
   confira que as ferramentas da hystore estão marcadas.

## Windsurf

Em **Windsurf Settings > Cascade > MCP Servers**, abra o arquivo de
configuração e cole:

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

Atualize a lista de servidores e conecte; o login abre no navegador.

## Outros apps

Procure no app por *conector personalizado*, *servidor MCP remoto* ou *MCP por
HTTP* e use o mesmo endereço. Não precisa de chave nem de cabeçalho: o app
descobre sozinho onde fazer login (pelos documentos em
`https://mcp.hystore.com.br/.well-known/`) e abre o painel. Se o app só aceita
servidores locais (por linha de comando), use a
[ferramenta hystore](/pt/code-theme/cli/) no lugar do MCP.

## A tela de autorização

Quando o app pede acesso, o painel mostra **Conectar uma IA à sua loja**:

- **Nome do app**, do jeito que ele mesmo se apresenta. Confira se é o app que
  você está conectando.
- **Para onde o acesso vai.** Quando é um programa no seu computador (Claude
  Code, Cursor, VS Code), a tela avisa: só autorize se você acabou de pedir
  isso.
- **A loja** que a IA vai editar.
- **O que a IA pode fazer**, com caixas para desmarcar:

| Na tela | A IA pode |
|---|---|
| Ler os arquivos do tema | ler os arquivos, as versões, as imagens e o catálogo público |
| Mudar os arquivos do rascunho | criar, mudar e apagar arquivos e imagens do rascunho |
| Pedir publicação | mandar o rascunho para alguém aprovar no painel |

Clique em **Autorizar** e volte para o app. **Recusar** não dá acesso nenhum.

> [!WARNING]
> Se a tela abrir sem você ter pedido nada, clique em **Recusar**. Ninguém da
> Hystore pede para você autorizar apps.

## Exemplos de pedidos

Escreva como falaria com uma pessoa. Alguns que funcionam bem:

- *"Leia o guia do tema e me explique como o meu tema está organizado."*
- *"Na página inicial, troca o título do topo por 'Temporada 5 chegou' em
  português, inglês e espanhol."*
- *"Cria uma seção de Black Friday com contagem regressiva até 28/11 às 23:59 e
  um botão para a categoria vips. Põe ela no topo da home."*
- *"Mostra os 8 produtos mais recentes da categoria kits em cartões com botão
  de comprar."*
- *"Muda a cor de destaque para dourado e deixa os botões mais arredondados."*
- *"Me manda o link da prévia."*
- *"Confere o tema todo e corrige os erros."*
- *"Pede a publicação com a nota 'Banner da Black Friday'."*

Depois do pedido de publicação, abra **Personalização > Tema em código >
Pedidos de publicação**, veja o que mudou e clique em **Aprovar e publicar** (ou
**Recusar**).

## O que a IA pode fazer

| Ferramenta | Faz |
|---|---|
| `read_theme_guide` | lê o [guia do tema](/pt/code-theme/guide/), inteiro ou uma parte |
| `get_store` | nome e endereço da loja, permissões da conexão |
| `list_theme_files`, `read_theme_file` | lê o rascunho |
| `write_theme_files` | cria, muda ou apaga arquivos do rascunho, até 100 de uma vez |
| `check_theme` | confere o rascunho inteiro |
| `get_preview_link` | link de 24 horas do rascunho no endereço da loja |
| `request_publish` | pede a publicação; alguém aprova no painel |
| `list_versions`, `read_version_file`, `restore_version` | versões publicadas e voltar uma para o rascunho |
| `list_assets`, `upload_asset`, `delete_asset` | imagens e fontes do tema |
| `read_catalog` | categorias e produtos ativos, só o que um visitante vê |

Os parâmetros e exemplos de cada uma estão na
[referência do MCP](/pt/code-theme/mcp-reference/#ferramentas).

Cada arquivo passa pela mesma conferência do painel: um arquivo com erro volta
para a IA com a linha e o motivo, e nada é gravado. Se alguém mudou o arquivo no
painel enquanto isso, a gravação é recusada em vez de apagar a mudança.

A IA **não** chega em pedidos, pagamentos, saldo, jogadores, cupons nem
configurações, e não publica sozinha.

## Desconectar

A conexão dura 30 dias e se renova sozinha enquanto o app é usado. Ela aparece
em **Personalização > Acesso ao tema > Sessões conectadas**, marcada como *App
de IA*, com o nome do app. **Desconectar** corta o acesso na hora.

A cada app conectado, o dono da loja recebe um e-mail com o link para
desconectar. Cada mudança feita pela IA fica no histórico do tema com a origem
MCP.

## Problemas comuns

| O que acontece | O que fazer |
|---|---|
| O painel diz que a loja não tem a opção | O plano precisa de **Tema em código** com **Conectar a IA**; confira também Configurações > Módulos |
| O botão **Autorizar** não aparece | Seu cargo precisa de permissão no tema; peça ao dono da loja |
| O app diz que a conexão expirou | Desconecte e conecte de novo; uma conexão parada por 30 dias deixa de valer |
| A IA editou, mas a loja não mudou | Ela edita o **rascunho**. Veja a prévia e aprove o pedido de publicação |
| A IA diz que um arquivo foi recusado | A mensagem traz a linha e o motivo; peça para ela corrigir. Veja [Problemas comuns](/pt/code-theme/faq/) |
| A IA está editando a loja errada | Desconecte em Sessões conectadas e conecte de novo escolhendo a loja certa |

Para quem cria apps e integrações, o login, as rotas e as mensagens estão na
[referência do MCP](/pt/code-theme/mcp-reference/).