---
title: 'Guper por IA (MCP)'
description: 'Conecte um assistente de IA à sua organização e opere o Guper conversando, com as permissões que você já tem.'
---

# 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](https://www.rfc-editor.org/rfc/rfc9728)):

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

Ele aponta o authorization server, cujo metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) responde em:

```bash
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](https://www.rfc-editor.org/rfc/rfc7591)) | `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](https://www.rfc-editor.org/rfc/rfc7009)) | `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](https://www.rfc-editor.org/rfc/rfc8252).
- **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](/docs/{lang}/guides/authentication).

## 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

- [Autenticação](/docs/{lang}/guides/authentication) — o caminho `apiKey`/`apiSecret`, para integração de sistema
- [Panorama de integração](/docs/{lang}/guides/integration-landscape) — como as peças se encaixam
