Pular para o conteúdo principal
DocumentationAPI ReferenceVideo Tutorials

Servidores MCP

MCP — o Model Context Protocol — é um padrão aberto que permite aos assistentes de IA descobrir e chamar ferramentas externas. Se executa um servidor compatível com MCP (próprio, ou um dos muitos servidores da comunidade), pode ligá-lo à Hanc.AI e os seus agentes irão obter as ferramentas do servidor no momento em que uma chamada começa.

Uma vez ligado, o agente pode chamar essas ferramentas a meio da conversa — puxando dados ao vivo, executando cálculos, iniciando workflows de backend — tal como as integrações nativas de Calendário, HubSpot ou API Tool.

Disponível em todos os planos

Os servidores MCP estão disponíveis em todos os planos, incluindo Free. Não há taxa por servidor — paga apenas pelos minutos de chamada que o seu agente usa ao invocar as ferramentas.

Quando Usar MCP​

CenárioPorque MCP Encaixa
Já executa um servidor interno de ferramentasUma ligação, todas as suas ferramentas disponíveis a cada agente
Quer partilhar ferramentas entre agentesLigue uma vez, anexe a quantos agentes quiser
Usa servidores MCP da comunidadeLigue servidores MCP open-source populares sem escrever código personalizado
A sua superfície de ferramentas muda frequentementeO agente re-descobre ferramentas em cada chamada — adicione/remova ferramentas do lado do servidor sem tocar no painel

Se tem um único endpoint pontual, a API Tool é mais simples. Se tem um conjunto de ferramentas relacionadas, ou já mantém um servidor MCP, esta é a integração certa.

Ligar um Servidor MCP​

1. Abra a página Integrações​

Na barra lateral do painel, vá a Integration. Faça scroll até à secção MCP servers.

2. Clique em "Connect MCP server"​

Abre-se um modal. Preencha:

CampoDescrição
LabelUm nome curto para esta ligação (ex. "Sales Tools", "Internal CRM"). O rótulo é mostrado no seletor de ferramentas do agente e prefixa os nomes de ferramentas apresentados à IA, portanto mantenha-o curto e significativo.
URLO URL HTTPS do seu servidor MCP. Deve ser um endereço acessível publicamente — http:// e endereços privados/internos são rejeitados.
AuthenticationNone se o seu servidor é aberto, ou Bearer token se espera um cabeçalho Authorization: Bearer ….
Token(Apenas Bearer) O seu token de auth. Armazenado encriptado — apenas a sua conta na plataforma o pode desencriptar para uso.

Clique em Save. A Hanc.AI verifica o formato do URL e armazena a ligação. A ligação fica agora disponível para cada agente no seu workspace.

Os rótulos importam

Os nomes de ferramentas de cada servidor MCP são prefixados com o rótulo da ligação, portanto um servidor MCP com uma ferramenta lookup_order ligada como "Shop API" irá aparecer ao agente como Shop_API_lookup_order. Isto evita colisões quando liga vários servidores MCP que por acaso têm ferramentas com nomes semelhantes.

3. Editar, desativar ou eliminar​

A lista de servidores MCP mostra o rótulo, URL, tipo de auth e estado de cada ligação que adicionou. Use as ações de linha para:

  • Editar — mudar rótulo, URL, tipo de auth ou token
  • Eliminar — remover a ligação inteiramente

Remover uma ligação desativa-a para cada agente que a tinha anexada — esses agentes simplesmente perdem o acesso às suas ferramentas na próxima chamada.

Anexar Ferramentas MCP a um Agente​

Uma ligação no seu workspace está disponível para os seus agentes — mas cada agente decide individualmente quais das suas ligações expor. Isto significa que pode ter agentes separados de Vendas e Suporte que puxam de servidores MCP diferentes.

1. Abra a aba Actions do agente​

Escolha o agente. Abra a aba Actions. Clique em Add Action.

2. Escolha "MCP servers" do grupo Live-call​

O dropdown mostra três grupos: Pre fetch, Live call, Post call. Procure no grupo Live-call — é aí que pertence MCP servers, porque o agente invoca ferramentas MCP durante a conversa, não antes ou depois.

3. Ative quais ligações habilitar​

O modal lista cada ligação MCP no seu workspace, cada uma com um toggle on/off. Ative as que este agente deve usar. Também pode escrever uma instrução curta no campo "When to use it" — isto é o que o agente lê para decidir quando recorrer a estas ferramentas durante uma conversa.

Clique em Save. O agente tem agora acesso às ferramentas de cada ligação MCP ativada.

Misturar e combinar

Pode ter uma ligação MCP ativada em cinco agentes e outra ativada em apenas um — cada agente tem a sua própria ferramenta MCP servers com o seu próprio conjunto de toggles.

Como Funciona no Momento da Chamada​

Quando uma chamada começa, o agente liga-se a cada um dos seus servidores MCP ativados e pergunta "que ferramentas oferece?" O que quer que o servidor devolva é exposto à IA como uma ferramenta que pode chamar durante a conversa.

Algumas coisas a saber:

  • As ferramentas são descobertas no início da chamada. Se adicionar ou remover ferramentas no seu servidor MCP, a alteração aparece na próxima chamada — sem necessidade de atualizar nada na Hanc.AI.
  • Os nomes das ferramentas são prefixados com o rótulo da ligação (assim "Shop API" + ferramenta search_products → Shop_API_search_products). As ferramentas integradas do agente e outras ferramentas MCP não vão entrar em conflito.
  • As descrições e schemas de parâmetro das ferramentas vêm do seu servidor MCP. Escreva boas descrições aí — é isso que a IA usa para decidir quando e como chamar a ferramenta.
  • Os erros são reportados de volta ao agente. Se uma chamada de ferramenta falhar, o agente vê a mensagem de erro e pode decidir retentar, pedir desculpa ou tentar uma ferramenta diferente.

Requisitos para o Seu Servidor MCP​

Para funcionar com a Hanc.AI, o seu servidor precisa de:

RequisitoDetalhe
HTTPShttp:// simples não é aceite. Use um certificado TLS real.
URL PúblicoO URL deve resolver para um endereço público — a Hanc.AI não consegue alcançar servidores numa rede privada ou localhost.
Transporte MCP Streamable HTTPO transporte HTTP MCP atual sobre um único endpoint. Os transportes apenas SSE e stdio não são suportados nesta integração.
Bearer auth (opcional)Se o seu servidor requer autenticação, deve aceitar um cabeçalho Authorization: Bearer <token> padrão.

Se está a hospedar o seu próprio servidor atrás de uma firewall, exponha-o via um túnel ou proxy reverso com um endpoint HTTPS público.

Segurança e Privacidade​

Os seus bearer tokens são armazenados encriptados em repouso. Apenas a infraestrutura de chamadas da Hanc.AI os pode desencriptar, e apenas no momento em que uma chamada começa e o agente precisa de se ligar ao seu servidor.

As chamadas de ferramentas fluem agente → Hanc.AI → seu servidor MCP → de volta. Não registamos payloads de chamadas de ferramentas. O seu servidor regista o que escolher registar do seu lado.

Se mudar ou fizer rotação do seu token, edite a ligação no painel — o novo valor tem efeito na próxima chamada.

Disponibilidade por Plano​

PlanoServidores MCP
FreeDisponível
Starter / Pro / Business / EnterpriseDisponível

Não há cobrança por ligação — paga apenas pelos minutos de chamada durante os quais o agente invoca as ferramentas.

Resolução de Problemas​

"A ligação não guarda"​

  • Garanta que o URL começa com https:// e não http://.
  • Garanta que o host é acessível publicamente — localhost, 127.0.0.1 e endereços internos são bloqueados por desenho.
  • Reveja o bearer token se definiu um — espaço extra ou aspas vão quebrar o save.

"O agente não vê as ferramentas"​

  • Verifique se a entrada do servidor MCP na aba Actions do agente tem pelo menos uma ligação ativada on e a entrada está guardada.
  • Garanta que o seu servidor MCP está a responder a um pedido tools/list e não requer um fluxo de auth interativo.
  • Procure no registo de chamadas do agente mensagens da ligação MCP logo no início da chamada.

"A ferramenta falha a meio da chamada"​

  • O agente verá qualquer erro que o seu servidor devolva. Verifique os logs do seu servidor.
  • Ferramentas de longa duração podem fazer timeout — mantenha a execução das ferramentas MCP em poucos segundos por chamada para que o visitante não fique em silêncio.

"Mudei ferramentas no meu servidor mas o agente continua a usar as antigas"​

  • As ferramentas são re-descobertas no início de cada chamada, não em cache entre chamadas. A próxima nova chamada vê o conjunto atualizado de ferramentas. As chamadas em curso mantêm as ferramentas que receberam no início.

Relacionados​