Conectar um assistente de IA ao Hades (MCP)

O MCP deixa um assistente de IA (Claude, Cursor, um agente do n8n ou o agente do seu próprio sistema) perguntar ao Hades em linguagem natural, por exemplo: "quais reuniões de ontem terminaram em follow-up?" ou "o que o cliente da Acme disse sobre preço?". O assistente consulta o Hades e responde com base no que ele devolveu.

Ele é do plano Semideus pra cima. A chave é a mesma da API e é criada no mesmo lugar (Integrações, seção API e MCP); a API sozinha já funciona no Oráculo, e o MCP é o que o Semideus ganha a mais. No Oráculo, a tela mostra o bloco do MCP com um convite pra passar de plano.

Conectar

1. Crie a chave em Integrações, seção API e MCP: veja criar uma chave de API. Dê um nome que diga qual assistente vai usá-la (por exemplo Claude).
2. Abra o bloco Como conectar um assistente de IA (MCP) na mesma tela. Ele mostra o endereço do MCP da sua conta, que termina em /api/mcp.
3. No seu assistente, cadastre esse endereço e mande a chave no cabeçalho Authorization: Bearer hdk_....
4. No Claude Code é um comando só (troque o hdk_... pela sua chave):

claude mcp add --transport http hades https://hades-copilot.com.br/api/mcp \
  --header "Authorization: Bearer hdk_..."

O comando pronto acima é do Claude Code. Outros programas que falam MCP por HTTP usam o mesmo endereço e o mesmo cabeçalho; cada um tem o próprio lugar para cadastrar isso.

O que o assistente consegue fazer

Sempre, com qualquer chave (só leitura):

• buscar_contatos — acha contatos por nome, e-mail ou telefone.
• ver_contato — a ficha: dados, reuniões, negócios e propostas.
• listar_reunioes — as reuniões com resumo e desfecho.
• ver_reuniao — a análise completa: dores, objeções, decisor, o que faltou, próximos passos. A transcrição só vem se a chave tiver a permissão Pode ler a transcrição das reuniões.
• listar_negocios — os negócios, com etapa, valor e contato.
• listar_pipelines — os pipelines e as etapas (o assistente usa pra saber os nomes antes de filtrar ou mover).

Só se a chave tiver a permissão Pode criar contatos e mover negócios (aí duas ferramentas a mais aparecem):

• criar_contato — cria um contato; se o telefone ou e-mail já existe, devolve o que existe e não duplica.
• mover_negocio — muda a etapa e/ou o valor de um negócio por vez, com as mesmas regras da tela de Negócios.

Nada é apagado. Cada escrita fica registrada em Últimas escritas pela API e pelo MCP (com a marca MCP) na tela de Integrações.

Cuidados

• Uma chave por assistente, com um nome que você reconheça. Se o assistente for trocado ou ficar suspeito, Revogar a chave corta o acesso na hora.
• Deixe a permissão de escrita desligada se você só quer perguntar. Ligue só pra quem vai mexer em contato e negócio.
• O que o assistente lê (nomes, telefones, o resumo das reuniões) sai do Hades e vai pra onde o assistente roda. Use um assistente em que você confia, e só ligue a transcrição se for indispensável.
• Texto que veio de uma reunião ou de um contato é dado, não ordem: o Hades avisa o assistente disso, mas confira o que ele propõe antes de aceitar uma mudança.
• Os pedidos do MCP contam no mesmo limite da chave: 60 por minuto, e 30 escritas a cada 10 minutos.

Se deu erro

• 402 / "O plano desta conta não inclui o MCP" — a empresa está no Oráculo. A chave serve na API; pra usar o MCP é preciso o Semideus. Veja o que cada plano tem.
• 401 — chave errada, revogada ou fora do cabeçalho Authorization.
• Esta chave não tem a permissão "escrita" — o assistente tentou criar contato ou mover negócio com uma chave só de leitura. Crie outra com a permissão marcada.
• 429 — passou de 60 pedidos no minuto. Espere o minuto virar.
• "Não consegui ler agora" — o Hades não conseguiu conferir; tente de novo em instantes. O assistente não deve concluir que "não há dados" com essa resposta.