Entrar
.md

Guper por IA (MCP)

Sua organização tem um endereço que qualquer assistente de IA compatível com MCP (Model Context Protocol) entende. Depois de conectado, você conversa com o assistente e ele usa o Guper por você — consulta cliente, lê saldo, monta público, cria campanha.

https://{organization}.myguper.com/mcp

Funciona no Claude, no Cursor, no ChatGPT e em qualquer cliente que fale MCP.

Não há chave para gerar nem SDK para instalar. O login é o mesmo do painel, feito no navegador — e o assistente recebe exatamente as permissões que você já tem lá.

Conectando

  1. No seu assistente, abra a área de conectores. No Claude: Configurações → Conectores → Adicionar conector personalizado. No Cursor, o campo se chama MCP server URL.
  2. Cole o endereço da sua organização — https://{organization}.myguper.com/mcp.
  3. Uma janela do navegador abre com a tela de login do Guper. Entre com o mesmo e-mail e senha do painel.
  4. Pronto.

O aplicativo se registra sozinho na sua organização. O acesso é seu, individual — não da empresa. Se você sair, seu acesso sai junto, sem ninguém precisar trocar credencial de mais ninguém.

Usa mais de uma organização? Cada uma é um conector separado, com o endereço dela. Um acesso nunca alcança a outra.

O que dá para pedir

O assistente pesquisa no catálogo de operações antes de agir, então vale usar as palavras do dia a dia:

  • "qual o saldo de cashback do cliente 4.482.109?"
  • "quantos pedidos a loja 1838 fez essa semana?"
  • "monta um público de quem comprou na categoria vinhos nos últimos 90 dias"
  • "cria uma campanha de aniversário com 10% de cashback"
  • "por que o cliente fulano não conseguiu resgatar?"

Se ele responder que não encontrou nada, tente os termos do domínio — cashback, resgate, audiência, campanha, pedido — em vez de descrever o problema. A busca é lexical.

O que ele não faz sozinho

Operação que mexe em dinheiro exige confirmação explícita. São 41 operações que movem valor: ajuste de saldo, cancelamento, crédito. O assistente pergunta antes e não executa sem o seu "sim".

Operação que não é idempotente exige uma chave de repetição. Isso impede que uma falha de rede transforme uma campanha em duas.

Você não vê o que não pode ver. As operações fora da sua permissão nem aparecem para o assistente — não é que ele tente e seja negado: elas não existem, do ponto de vista dele. Um perfil de atendimento típico enxerga cerca de um quinto do catálogo.

Para quem administra

Quem pode usar

Qualquer pessoa com login de painel (admin ou staff) e um perfil de acesso atribuído. Login de cliente final não entra.

Usuário sem perfil de acesso recebe um aviso na tela e não conclui a conexão. Um acesso que não pode fazer nada faria o assistente responder "não encontrei" para tudo, que é indistinguível de sistema quebrado.

Como controlar o que a IA faz

Pelos perfis de acesso do painel, os mesmos de sempre. Não existe tela nova nem permissão paralela: o que o assistente pode fazer é literalmente o que está em Configurações → Equipe → Perfis de acesso.

Quem tem Clientes 360 em ver consulta clientes pela IA mas não altera. Quem não tem Cartões de fidelidade não enxerga nada de cashback.

Como cortar o acesso de alguém

Inative o usuário no painel. O login novo é bloqueado na hora, e o acesso existente cai na próxima renovação — no máximo uma hora.

Mudou a permissão? Reflete na próxima renovação, também em até uma hora. O que o assistente pode fazer é reconferido a cada renovação, nunca herdado.

Duração

O acesso vale 1 hora e se renova sozinho por até 30 dias sem novo login. Depois disso, entra de novo.

Tentativas de senha

Oito tentativas erradas bloqueiam aquele e-mail por 15 minutos. A trava é por e-mail, não por rede — o erro de uma pessoa não afeta o escritório.

Para quem integra um cliente próprio

O MCP do Guper segue OAuth 2.1 com PKCE e os padrões que os clientes MCP esperam. Você não precisa cadastrar nada: o registro é dinâmico.

O ponto de partida é o metadata do recurso protegido (RFC 9728):

curl https://{organization}.myguper.com/.well-known/oauth-protected-resource

Ele aponta o authorization server, cujo metadata (RFC 8414) responde em:

curl https://{organization}.myguper.com/.well-known/oauth-authorization-server/api/connect

A partir daí o fluxo é o padrão:

etapa endpoint
registro dinâmico (RFC 7591) POST /api/connect/oauth/register
autorização GET /api/connect/oauth/authorize
troca do code e renovação POST /api/connect/oauth/token
revogação (RFC 7009) POST /api/connect/oauth/revoke
chave pública GET /api/connect/oauth/jwks

Detalhes que o seu cliente precisa respeitar:

  • PKCE é obrigatório, e só S256. plain não é aceito.
  • A redirect_uri é comparada por igualdade exata. Sem prefixo, sem wildcard. https:// sempre; http:// apenas em loopback (127.0.0.1, localhost), como manda a RFC 8252.
  • Cliente público apenas (token_endpoint_auth_method: none).
  • O code vale 2 minutos e serve uma vez. Reapresentá-lo encerra a sessão inteira, por segurança.
  • O refresh rotaciona. Cada uso emite um novo; reapresentar um já usado encerra a sessão inteira.

O token é um JWT assinado em RS256, com aud igual à URI canônica do recurso da sua organização (https://{organization}.myguper.com/mcp). Um token emitido para uma organização falha na validação em outra — o isolamento vem do protocolo.

O scope traz as permissões no formato recurso.nível, as mesmas do painel:

customer.360.edit customer.360.messages.view customer.addBalance.full order.edit

Isso muda algo na minha integração atual?

Não. apiKey/apiSecret → token → chamadas continuam exatamente como estão, e nenhum endpoint mudou. O MCP é um caminho novo, por pessoa, ao lado do que já existe.

Integração servidor-a-servidor continua no caminho de sempre — veja Autenticação.

Problemas comuns

sintoma causa provável o que fazer
"não consegui conectar" endereço da organização errado conferir o subdomínio no endereço
login abre e volta com erro endereço de retorno do cliente mudou remover e adicionar o conector de novo — ele se registra outra vez
"aplicativo não reconhecido" registrado em outra organização normal: cada organização tem seu registro. Adicione o conector nesta
assistente não acha nada a busca é lexical usar termos do domínio, não descrição do problema
pede confirmação sempre operação financeira é o desenho: 41 operações movem valor
some uma operação esperada fora do seu perfil conferir Configurações → Equipe → Perfis de acesso
"muitas tentativas" 8 senhas erradas aguardar 15 minutos

Veja também