Conector MCP da Hapee

Use a Hapee no seu assistente de IA. Você faz login com seu próprio usuário e o assistente trabalha com exatamente as suas permissões: vê o que você vê e altera apenas o que você pode alterar.

O que é

O conector é um servidor MCP (Model Context Protocol, o padrão aberto com o qual os assistentes de IA se conectam a ferramentas externas). Ao adicioná-lo a um assistente compatível —Claude, ChatGPT, Grok Bot ou outro que aceite conectores MCP remotos— você pode pedir em linguagem natural coisas como «mostre os negócios abertos desta semana», «crie um contato com estes dados» ou «agende um compromisso para amanhã às 10».

O conector não guarda seus dados da Hapee: cada ferramenta é uma chamada à API v1 da Hapee feita com a sua própria sessão. Não há chaves compartilhadas nem URLs secretas: cada pessoa se conecta com seu usuário da Hapee.

A URL do conector

https://mcp.hapee.ai/mcp

É o único endereço de que você precisa. Ele não leva nenhuma credencial: o login acontece depois, em uma tela da Hapee.

É o endereço oficial desde 12 de outubro de 2026. Se você conectou o conector com o endereço anterior (em mcp-oauth.hapee.ai), adicione-o novamente com este. Se você usava uma URL pessoal terminada em /c/…, essa é a forma de conexão anterior: substitua-a por esta.

Requer que seu plano inclua a conexão com assistentes de IA (disponível a partir do plano Pro). Se seu plano não a inclui, a tela da Hapee avisa ao conectar e o conector não funciona.

Conectar ao seu assistente

Cada assistente coloca a opção em um lugar diferente de suas configurações, e esses menus mudam com frequência, então aqui estão os passos genéricos. Em todos o procedimento é o mesmo:

Nas configurações do seu assistente, adicione um conector MCP personalizado (ou remoto) com a URL acima. Se ele pedir um nome, use «Hapee».
Se ele perguntar o tipo de autenticação, escolha OAuth. Não é preciso digitar nenhum client ID nem segredo: o assistente se registra sozinho.
O assistente abre uma janela da Hapee. Faça login com seu usuário e aprove a conexão (veja o ponto seguinte).
Você volta ao assistente com o conector ativo. Peça, por exemplo, «quem sou eu na Hapee?» para conferir com qual usuário e subconta você está conectado.

Claude: adicione um conector personalizado com a URL do conector.
ChatGPT: adicione um conector MCP remoto com a URL do conector.
Grok Bot: adicione um conector MCP remoto com a URL do conector.

Se sua organização administra os conectores de forma centralizada, talvez a pessoa administradora precise adicioná-lo primeiro.

A janela que o assistente abre é a do beta.hapee.ai, a mesma em que você entra na Hapee todos os dias. Ali você faz login como sempre:

com seu e-mail e senha, mais sua verificação em duas etapas se estiver ativa, ou
com o Google, se é assim que você costuma entrar.

O assistente nunca vê sua senha: ele só recebe uma permissão temporária que a Hapee emite quando você a aprova. Depois do login aparece a tela de consentimento, que mostra qual aplicativo pede acesso, para qual endereço você será devolvido, com qual conta e agência você está se conectando e o que ele poderá fazer. Ali você pode remover a permissão de escrita se quiser que o assistente só possa consultar.

O que ele pode fazer

A conexão pede estas permissões (scopes):

Permissão	O que permite
`hapee:read`	Consultar as informações que você pode ver na Hapee. Sempre é incluída: sem ela a conexão não serve.
`hapee:write`	Além disso, criar, editar e apagar onde seu perfil permitir. Se você a remover na tela de consentimento, as ferramentas que modificam dados não aparecem e a API rejeita qualquer escrita.
`offline_access`	Manter a conexão sem que você precise fazer login a cada hora (veja quanto dura a conexão). Hoje a Hapee entrega a permissão de renovação em toda conexão aprovada, o aplicativo a peça ou não.

As permissões só subtraem, nunca somam. Acima dos scopes vale seu usuário real da Hapee: seu papel, seu perfil de permissões, os módulos ativos e, se seu perfil é «somente o atribuído», apenas o que está atribuído a você. Se seu administrador alterar as permissões do seu perfil, elas valem a partir da chamada seguinte; se atribuir a você outro papel ou outro perfil, a conexão é desconectada e você precisa conectar de novo. Nenhuma conexão pode fazer algo que você não possa fazer pela tela.

A lista de ferramentas que o assistente vê também é montada para você: só aparecem as que suas permissões permitem usar, e as de escrita somente se você aprovou hapee:write.

Agências e subcontas

O conector trabalha sobre uma subconta por vez: o negócio com o qual você opera na Hapee.

Usuário de uma subconta (cliente): a conexão fica atrelada à sua subconta. Se você tem acesso a mais de uma, escolhe qual na tela de consentimento; para trocá-la, conecte de novo.
Equipe de uma agência (dono, administrador ou membro da equipe): você escolhe a subconta em cada conversa com a ferramenta select_subaccount. Sem argumentos, ela lista as subcontas que você pode ver; com um id, fixa essa subconta para o resto da conversa. Só aceita subcontas que seu usuário já pode ver na Hapee. A administração interna da agência (subcontas, equipe, tarefas internas) não está neste conector.
Os acessos de administração da plataforma não se estendem ao conector.

Ferramentas

O conector oferece 240 ferramentas sobre a API da Hapee: 85 de consulta e 155 que modificam dados. Quantas você vê depende das suas permissões. Os nomes delas estão em inglês, como exige o padrão dos diretórios de assistentes; seu assistente responde e escreve o conteúdo no seu idioma.

Família	Total	Consulta	Modificam
CRM: contatos, empresas, negócios, funis de vendas, etapas, etiquetas e tarefas	62	19	43
Sites, landing pages, funis, domínios, imagens e blog	52	18	34
Produtos, categorias e cotações	25	8	17
Automações (workflows) e agentes de IA	24	8	16
Email marketing: campanhas, modelos e públicos	22	10	12
Formulários, propriedades e objetos personalizados	22	8	14
Calendários e compromissos	15	5	10
Conversas e WhatsApp	13	4	9
Relatórios	2	2	0
Identidade (`whoami`, `select_subaccount`) e catálogo de design	3	3	0
Total	240	85	155

Ferramentas que modificam dados

Cada ferramenta declara sua natureza com as anotações padrão do MCP, para que seu assistente possa pedir sua confirmação antes de executar algo:

Consulta (readOnlyHint: true): as 85 de consulta. Não alteram nada (duas delas, validar um workflow e contar um público, usam POST mas não salvam nada).
Criam ou adicionam (readOnlyHint: false, destructiveHint: false): 48 ferramentas, como criar uma nota, uma tarefa, um rascunho de landing ou de campanha.
Editam, apagam ou agem para fora (readOnlyHint: false, destructiveHint: true): 107 ferramentas que alteram ou eliminam algo que já existe, publicam ou enviam.
Chegam fora da Hapee (openWorldHint: true): 38 delas, como enviar uma mensagem, uma cotação ou uma campanha de e-mail, publicar uma página ou apontar um domínio. O conector instrui seu assistente a pedir sua confirmação antes de usá-las.

O que o assistente faz com hapee:write fica feito na sua conta real. Uma mensagem enviada chega ao contato e um registro apagado é apagado. Revise o que seu assistente propõe antes de confirmar, e se você só precisa consultar, conecte-o sem a permissão de escrita.

Quanto dura a conexão

A permissão de acesso que o assistente usa dura 1 hora.
O assistente a renova sozinho com uma permissão de renovação que dura 30 dias desde o último uso e muda a cada renovação (a anterior deixa de valer). Se alguém tentasse reutilizar uma já usada, a Hapee corta a conexão inteira.
Aconteça o que acontecer, 90 dias depois de você aprová-la a conexão expira e você precisa fazer login de novo.

Desconectar

Você tem várias formas de cortar o acesso:

Pela Hapee: no seu Perfil, a seção «Assistentes de IA conectados» lista cada assistente que você conectou, com sua subconta e seu último uso; «Desconectar» corta o acesso dele na hora.
Pelo seu assistente: remova ou desconecte o conector nas configurações dele. Se o assistente avisa a Hapee ao desconectar, a conexão é revogada na hora; se não, ela deixa de ser usada e expira sozinha nos prazos acima.
Trocando sua senha ou sua verificação em duas etapas: desconecta automaticamente todas as suas conexões de assistentes.
Mudanças no seu usuário: se seu administrador mudar seu papel, o perfil de permissões, a agência ou a subconta, ou desativar seu usuário, suas conexões se desconectam sozinhas.
A pessoa dona da agência pode revogar qualquer conexão da sua agência pela tela de API keys da Hapee: elas aparecem como «OAuth: <nome do aplicativo>».
Se você precisar de ajuda para cortar um acesso, escreva para info@hapee.ai.

Limites

Cada conexão tem o mesmo limite que qualquer credencial da API: 100 chamadas por minuto. Se seu assistente o ultrapassar, recebe um erro temporário e basta esperar alguns segundos.
O registro automático de aplicativos é limitado a 20 registros por hora a partir de um mesmo endereço IP.
As listas retornam até 100 elementos por página, igual à API.

Detalhes técnicos

Para quem integra um cliente MCP próprio ou revisa o conector:

Transporte: MCP sobre Streamable HTTP na URL do conector.
Descoberta: um request sem token recebe 401 com WWW-Authenticate: Bearer resource_metadata=…, que aponta para /.well-known/oauth-protected-resource no mesmo host (RFC 9728).
Servidor de autorização: https://beta.hapee.ai, com seus metadados em /.well-known/oauth-authorization-server (RFC 8414).
OAuth 2.1: registro dinâmico de clientes públicos (RFC 7591), PKCE obrigatório apenas com S256, rotação da permissão de renovação com detecção de reutilização, revogação (RFC 7009) e audiência vinculada ao recurso (RFC 8707). Os endereços de retorno precisam ser https, ou http apenas para a própria máquina.
Sessões: cada sessão MCP fica atrelada à pessoa que a abriu; um token de outra pessoa na mesma sessão é rejeitado.

Privacidade

O conector só acessa o que suas próprias permissões deixam você ver, e o servidor MCP não guarda seus dados da Hapee: o que ele consulta passa para seu assistente e fica sujeito à política de privacidade desse assistente. O detalhe do que é guardado, onde e por quanto tempo está na seção «Conector MCP para assistentes de IA» da nossa política de privacidade.

Dúvidas, ou algo que não funciona como descrito aqui? Escreva para info@hapee.ai.