> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appreval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conecte Claude e ChatGPT à sua loja (MCP)

> O servidor MCP da Reval permite que Claude, ChatGPT e outros assistentes consultem suas assinaturas, clientes, pedidos, planos, caixas, métricas e configuração. Somente leitura; o assistente entra com a sua loja (OAuth) ou usa uma API key. Guia passo a passo para Claude (web, desktop, Code) e ChatGPT, perguntas de exemplo, dados pessoais e limites.

A Reval publica um **servidor MCP** (Model Context Protocol, o padrão com que Claude, ChatGPT, Cursor e outros se conectam a fontes de dados). Você conecta uma vez, entrando com a sua loja, e depois pergunta ao assistente no seu idioma: «quantas assinaturas ativas eu tenho?», «quais clientes tiveram uma cobrança recusada esta semana?», «quais produtos estão em mais caixas?».

> [!NOTE]
>
> É **somente leitura**. O assistente consulta a sua loja; não pode pausar, cancelar, editar nem mudar a configuração, com nenhuma chave. Para operar assinaturas a partir dos seus próprios sistemas existe a [API](https://docs.appreval.com/pt/desenvolvedores/api.md).

***

## Antes de começar

* Uma loja com a Reval instalada e acesso ao admin (**Reval → Integrações**).
* Um cliente MCP. Este guia cobre o **Claude** (web, desktop, celular e Claude Code) e o **ChatGPT**; qualquer outro cliente que suporte servidores MCP remotos por HTTP funciona com a mesma URL.
* Um plano que permita conectores personalizados. Em **21 de outubro de 2026**: no Claude, os planos Pro, Max, Team e Enterprise; no ChatGPT, Plus, Pro, Business, Enterprise e Edu com o **modo desenvolvedor** ativado. Os menus e requisitos de cada cliente mudam com frequência: se algo não bater, procure «conectores» ou «MCP» na ajuda do cliente.

***

## Passo 1: conecte o assistente

A URL do servidor está em **Reval → Integrações → Assistentes de IA**. Em produção é:

```text theme={null}
https://api.appreval.com/mcp
```

Cole essa URL no assistente como conector personalizado e escolha **entrar**. A Reval pergunta qual é a sua loja, leva você ao seu admin da Shopify (com o seu login de sempre) e lá você confirma o acesso. Não há chave para copiar: o assistente recebe um token vinculado a essa loja, que expira e se renova sozinho, e que você pode cortar quando quiser em **Integrações → Assistentes conectados**.

### Claude (web, desktop e celular)

1. Entre em **Configurações → Conectores** (no claude.ai ou no app de desktop) e clique em **Adicionar conector personalizado**.
2. Nome: `Reval`. URL: `https://api.appreval.com/mcp`. Deixe a autenticação em **Entrar** (o Claude detecta sozinho) e o cliente OAuth na opção recomendada.
3. Clique em **Adicionar** e depois em **Conectar**: a Reval abre, você informa a sua loja (`tu-tienda.myshopify.com`), confirma no seu admin da Shopify com **Autorizar** e volta ao Claude.
4. Em um chat novo, abra o menu **+** (ou o de ferramentas), ative **Reval** e pergunte: «Quantas assinaturas ativas eu tenho?».

Os conectores são compartilhados entre web, desktop e celular, então você configura uma vez só.

### Claude Code

```bash theme={null}
claude mcp add --transport http reval https://api.appreval.com/mcp
```

Depois, numa sessão, `/mcp` mostra o status; escolha **Reval → Authenticate** na primeira vez: o navegador abre com o mesmo fluxo (loja → admin da Shopify → Autorizar). O Claude Code recebe a autorização em um endereço local (`localhost`), por isso a tela avisa.

### ChatGPT

1. Entre em **Configurações → Conectores** (ou **Apps e conectores**), abra **Configurações avançadas** e ative o **modo desenvolvedor**.
2. Clique em **Criar** (conector). Nome: `Reval`. URL do servidor MCP: `https://api.appreval.com/mcp`. Autenticação: **OAuth**.
3. Confirme: o ChatGPT abre a Reval, você informa a sua loja, confirma no seu admin da Shopify com **Autorizar** e o ChatGPT mostra as ferramentas disponíveis.
4. Em um chat, abra **+ → Mais** e escolha **Reval**, ou ative o modo desenvolvedor no chat, e pergunte: «Quantas assinaturas ativas eu tenho?».

> [!TIP]
>
> Qualquer cliente MCP que suporte OAuth (Cursor, MCP Inspector, um agente próprio) conecta do mesmo jeito: a URL, descoberta automática e o mesmo login. A Reval publica os metadados padrão em `/.well-known/oauth-authorization-server` e `/.well-known/oauth-protected-resource/mcp`.

***

## Alternativa: uma API key

Se o seu cliente não sabe entrar (um script, um agente sem navegador), você pode usar uma chave:

1. Em **Reval → Integrações → API keys**, digite o nome do assistente, marque **Somente leitura** e clique em **Gerar chave**. Ela aparece completa uma vez só.
2. Envie no header: `Authorization: Bearer reval_…`, por exemplo no Claude Code com `--header "Authorization: Bearer reval_…"`.

A forma `https://api.appreval.com/mcp/reval_…` (chave no final da URL) continua funcionando para clientes que só aceitam uma URL, mas deixa a chave guardada no cliente e nos registros de acesso. Prefira entrar; se usar essa forma, faça a chave somente leitura e revogue em **Integrações** se a vir exposta.

***

## O que perguntar

* «Quantas assinaturas ativas eu tenho? E pausadas?»
* «Quais clientes tiveram uma cobrança recusada esta semana?»
* «Quanto faturei com assinaturas nos últimos 30 dias em comparação com o período anterior?»
* «Quais são os motivos de cancelamento mais frequentes?»
* «Procure Martín Pérez e me diga o que ele assina e quando é a próxima cobrança.»
* «Quais produtos estão em mais caixas?»
* «Quais assinaturas serão cobradas na semana que vem?»
* «Tenho frete grátis ativado? E o Klaviyo conectado?»
* «Quais pedidos ficaram em espera por falta de estoque?»

O assistente combina as ferramentas de que precisar. Se a resposta parecer incompleta, peça que use uma ferramenta específica («use list\_subscriptions com payment\_failed») ou que busque mais linhas.

***

## O que ele pode consultar

| Ferramenta | Retorna |
| - | - |
| `get_store` | Idioma, moeda, fuso horário, regras do checkout, pedidos e estoque (política de estoque, auto-merge, frete grátis), portal, notificações (Klaviyo, Flow, GTM conectados ou não), status do Mercado Pago, marca e quais dados pessoais este servidor retorna. Nunca credenciais. |
| `get_dashboard_metrics` | O mesmo que você vê em **Início** para um período (hoje, ontem, 7, 30 ou 90 dias): receita, novas, líquidas, unidades, pedidos (com o período anterior e a % de variação), assinaturas por status, MRR, totais históricos, motivos de cancelamento e a série diária. |
| `list_subscriptions` | Assinaturas com filtros: status, cliente, produto, plano, caixa, datas de criação e de próxima cobrança, e **cobrança recusada** (o mesmo filtro do admin). Cada linha traz produtos com nome, valor, cadência, próxima cobrança e status de cobrança. |
| `get_subscription` | Uma assinatura completa: produtos, condições do plano, frete e impostos, cartão mascarado, ciclos cobrados, histórico de status e de preços, últimos pedidos. |
| `search_customers` | Busca por nome, sobrenome ou email (sem distinguir maiúsculas nem acentos). |
| `get_customer` | Um cliente com todas as suas assinaturas e pedidos. |
| `list_orders` / `get_order` | Pedidos gerados pelas assinaturas, com o número do pedido na Shopify, o pagamento do Mercado Pago, motivo de espera e status de envio. |
| `list_plans` | Os **Planos** com cadência, preço, descontos, ciclos mínimos e máximos e os produtos de cada um. |
| `list_boxes` | As **Caixas** com seus planos, tamanhos, produtos elegíveis, add-ons e faixas. |

Os nomes dessas ferramentas são um contrato: não mudam. Valores na moeda da loja; datas em UTC.

***

## Dados pessoais dos seus assinantes

Cada resposta do servidor vai para o provedor do assistente (Anthropic, OpenAI ou outro). Por isso **você decide** quanto dos seus assinantes é compartilhado:

| | O que inclui |
| - | - |
| **Sempre** | Nome, email, ID de cliente da Shopify, cidade, estado, país e bandeira do cartão. |
| **Só se você ativar** | Telefone, endereço completo (rua, complemento, CEP), empresa, documento fiscal e últimos dígitos e validade do cartão. |
| **Nunca** | Credenciais do Mercado Pago, tokens de cartão, API key do Klaviyo, segredos de webhooks e o faturamento da Reval. |

A opção **Compartilhar dados de contato dos assinantes com os assistentes** está em **Reval → Integrações → Assistentes de IA** e vale para todas as chaves da loja. Antes de ativá-la, revise as normas de proteção de dados do seu país (LGPD) e os termos do assistente que usar; a decisão e a responsabilidade são do lojista.

***

## Limites

O servidor compartilha os limites da [API](https://docs.appreval.com/pt/desenvolvedores/api.md#limites) para que uma conversa longa nunca afete o admin, o checkout nem as cobranças:

* **2000 requests por minuto por conexão** (um assistente que entrou, ou uma chave contando API e MCP juntos). Se passar, o assistente recebe uma mensagem clara («Usage limit reached… works again in Ns») e volta a funcionar quando a janela libera.
* Cada listagem retorna até **100 linhas** (25 por padrão) e continua com um cursor.
* Um assistente desconectado ou uma chave revogada recebe «Unauthorized» em toda consulta e não retorna nenhum dado.
* O token de um assistente dura 1 hora e se renova sozinho por 30 dias de uso; depois de 30 dias sem uso, o assistente pede para entrar de novo.

***

## Problemas frequentes

* **O cliente diz que não consegue conectar.** Verifique se a URL é exatamente `https://api.appreval.com/mcp`, sem espaços nem barra final. Se usar chave, ela deve começar com `reval_` e não estar revogada.
* **Ao entrar, diz que a loja não tem a Reval.** Informe o domínio `.myshopify.com` (não o domínio próprio da loja) e confira se a Reval está instalada nessa loja.
* **O assistente pede para entrar de novo.** Passaram 30 dias sem uso, ou você o desconectou em Integrações. Conecte de novo; leva um minuto.
* **O Claude Code avisa que o endereço é local.** É normal: ele recebe a autorização em `localhost`. Autorize só se foi você quem rodou o comando.
* **O assistente não encontra um cliente que existe.** Busque por email ou por parte do nome; se continuar sem aparecer, é de outra loja: cada chave vê só a loja que a gerou.
* **Faltam o telefone ou o endereço.** É a opção de dados pessoais (veja acima): por padrão não são compartilhados.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.