Ferramentas externas (MCP)

MCP (Model Context Protocol) é um padrão aberto para entregar a uma IA um conjunto de ações que ela pode executar. Um programa que fala esse padrão — um servidor MCP — publica suas ações como ferramentas em um único endereço web: consultar estoque, buscar um pedido, ler uma linha de uma tabela. Conecte esse endereço aqui e essas ferramentas passam a ser coisas que seu assistente de atendimento pode chamar enquanto responde a um cliente.

O Pommy está dos dois lados desse padrão, e vale deixar isso claro antes de continuar. Esta página trata do lado em que o Pommy é o cliente: seu assistente de atendimento usa o servidor de outra pessoa. O outro lado — seu agente de programação usando o Pommy como servidor — é Agentes de programação, e os dois não têm nada em comum além do nome.

Antes de começar#

• Um servidor MCP em funcionamento e acessível pela internet pública, no endereço completo do endpoint — algo como https://tools.example.com/mcp, com o caminho.
• Streamable HTTP. É o transporte que o Pommy fala: ele envia uma requisição ao seu endereço e lê a resposta. Um servidor feito no estilo SSE antigo, com dois endpoints, não conecta, qualquer que seja a opção escolhida na lista.
• O que o seu servidor precisar para confiar em quem chama — na prática, um token enviado em um cabeçalho.
• Espaço no seu plano. Quantos servidores MCP um projeto pode ter é um limite do plano, e o plano Free não inclui nenhum. Acima do limite, adicionar um servidor falha com uma mensagem indicando o limite.

Adicionando um servidor#

1. Abra API Connections

   API Connections no menu à esquerda e depois Add MCP Server.

2. Dê um nome e cole o endereço

   O nome é só para você — "API de pedidos" basta. A Server URL é o endpoint que seu servidor documenta, com o caminho completo. Deixe Transport em Streamable HTTP.

3. Adicione os cabeçalhos necessários

   Custom Headers aceita quantos pares nome/valor você quiser, e o Pommy os envia em todas as requisições — um cabeçalho Authorization com um bearer token é o caso mais comum. Não há campo separado para token; é pelo cabeçalho que você se autentica. Os valores ficam mascarados, e o ícone de olho os revela.

4. Add and Discover Tools

   O Pommy conecta na hora e pergunta ao servidor o que ele sabe fazer. Abra a nova linha e você verá as ferramentas encontradas, cada uma com a descrição que seu servidor deu. Uma lista vazia significa que o servidor não pôde ser alcançado ou não expõe nenhuma ferramenta.

5. Entregue a um assistente

   Um servidor novo ainda não está ligado a nenhum assistente, então nada mudou para seus clientes. A próxima seção cuida dessa parte.

Ativando ferramentas para um assistente#

As ferramentas são ativadas por servidor, por assistente. Abra AI Agent, edite o assistente e vá até a etapa MCP Tools: ela lista os servidores do projeto com um indicador de saúde e a contagem de ferramentas. Marque os que este assistente pode usar e salve.

Marcar um servidor dá ao assistente todas as ferramentas dele — não há interruptor por ferramenta. Se um assistente deve alcançar só algumas das suas ferramentas, exponha essas em um segundo servidor e conecte esse no lugar.

Dois interruptores precisam estar ligados para uma ferramenta chegar a uma conversa: o interruptor Active do próprio servidor em API Connections (o botão de pausa na linha dele) e a marcação naquela etapa. Pausar um servidor tira as ferramentas dele de todos os assistentes de uma vez e mantém as atribuições para quando você reativá-lo.

O que o assistente recebe#

Para cada ferramenta, o assistente recebe o nome, a descrição e a lista de parâmetros exatamente como seu servidor informa — o Pommy não acrescenta nenhuma explicação própria. Então a descrição no seu servidor é toda a instrução que o assistente recebe sobre quando usar a ferramenta. Escreva-a como uma frase sobre a situação ("Retorna o status atual de um pedido a partir do número do pedido"), não como referência de API.

O retorno vai para o assistente, não para o cliente: ele lê o resultado e escreve a resposta com as próprias palavras. Sua equipe vê a chamada, o resultado e quanto tempo levou no Agent console enquanto a conversa acontece.

Os nomes precisam ser distintos. Uma ferramenta com o mesmo nome de uma das ferramentas do próprio Pommy — search_knowledge_base, book_calendar_appointment, transfer_to_human e as demais — é descartada sem aviso, e dois servidores conectados que expõem o mesmo nome de ferramenta ficam indistinguíveis para o assistente. Na dúvida, use um prefixo nas suas.

Acompanhando o servidor#

A lista de API Connections dá uma linha a cada servidor: nome com indicador de saúde, endereço, transporte e contagem de ferramentas, status de saúde e a data da última verificação. Clicar na linha abre o servidor — os cabeçalhos (editáveis), os assistentes que o usam, a lista completa de ferramentas descobertas e quatro ações.

• Refresh Tools — pergunta de novo ao servidor o que ele sabe fazer e substitui a lista guardada. É a única coisa que a atualiza: nada redescobre de forma programada, então uma ferramenta que você adiciona do seu lado continua invisível para o Pommy até você clicar aqui.
• Health Check — uma verificação rápida de "você está respondendo?". Não diz nada sobre se uma ferramenta específica funciona.
• Pause — tira as ferramentas do servidor de todas as conversas sem excluir nada.
• Delete — remove o servidor e libera a vaga no seu plano.

Healthy significa que a última verificação alcançou seu servidor e encontrou ferramentas. Unhealthy significa que ela voltou vazia ou falhou. Unknown significa que nada foi verificado ainda. O status nunca é mais detalhado que isso — quando algo está errado, o motivo está do lado do seu servidor, nos logs dele.

Quando algo não funciona#