# Ferramentas externas (MCP)

> Assistente de IA · Conecte um servidor MCP e o assistente pode chamar as ferramentas dele no meio da conversa.

**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.

> **Dica:** Ninguém criou um servidor MCP para você? Pule esta página — o assistente é completo sem isso. Se você tem uma API, mas não um servidor MCP, [Data Actions](/docs/ai-assistant/data-actions) é o caminho mais curto.

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](/docs/coding-agents/connect-your-agent), e os dois não têm nada em comum além do nome.

![A página API Connections com a janela Add MCP Server: nome do servidor, URL do servidor, transporte e cabeçalhos personalizados](/docs/docs-mcp.png)

*API Connections — um nome, um endereço e os cabeçalhos de que seu servidor precisa. O Pommy descobre as ferramentas sozinho.*

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

> **Atenção:** **Endereços internos são recusados.** O Pommy chama seu servidor a partir dos próprios servidores, não de dentro da sua rede, então o endereço precisa ser acessível pela internet pública. Não é possível salvar `localhost` e `127.x`, as faixas privadas `10.x`, `172.16–172.31.x` e `192.168.x`, o link-local `169.254.x`, o endereço de metadados da nuvem e os equivalentes em IPv6 — você recebe **Invalid MCP server URL** e o motivo. Um servidor rodando na sua máquina ou na rede do escritório precisa ser publicado, ou exposto por um túnel em um endereço público, antes que o Pommy possa usá-lo.

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

> **Atenção:** Uma ferramenta que o assistente pode chamar é uma ferramenta que ele pode chamar **em nome de um cliente**, com as credenciais que você deu ao servidor e sem aprovação de ninguém no meio. Comece com ferramentas somente leitura e não exponha nada que grave, reembolse, cancele ou exclua até ver as de leitura funcionando bem. E note que o token nos seus cabeçalhos é o mesmo para todos os visitantes — seu servidor não consegue distinguir um cliente de outro, então nenhuma ferramenta aqui deve retornar dados pessoais só a partir de um identificador. Para respostas que pertencem a um cliente específico, use [Data Actions](/docs/ai-assistant/data-actions): lá, um grupo pode exigir um visitante verificado.

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

### Adicionei o servidor, mas o assistente nunca chama as ferramentas dele.

Duas coisas, nesta ordem. O servidor está marcado na etapa MCP Tools desse assistente? Um servidor recém-adicionado não pertence a nenhum assistente. Se estiver marcado, leia a descrição da ferramenta como o assistente leria: se ela não diz claramente qual pergunta a ferramenta responde, o assistente não vai recorrer a ela.

### A contagem de ferramentas caiu para zero.

Uma atualização substitui a lista guardada pelo que o servidor respondeu — e um servidor que não pôde ser alcançado não responde nada. As ferramentas voltam na próxima atualização bem-sucedida, e até lá o assistente fica sem elas.

### Mudei o endereço ou um token e nada mudou.

Editar a linha muda o que a página mostra, mas o assistente continua usando a conexão feita quando o servidor foi adicionado. Exclua o servidor e adicione de novo com os novos valores.

### Adicionar o servidor falhou com "Invalid MCP server URL".

O endereço aponta para algo interno — localhost, uma faixa de rede privada ou link-local. O Pommy faz as chamadas pela internet pública e recusa esses endereços. Publique o servidor em um endereço público ou exponha-o por um túnel.

### O cliente vê o que a ferramenta retornou?

Não. O resultado vai para o assistente, que responde com as próprias palavras; o resultado bruto nunca aparece no chat. Sua equipe pode vê-lo no Agent console.

---

Leia esta página na web: [Ferramentas externas (MCP)](/pt/docs/ai-assistant/external-tools-mcp)
