---
title: MCP Servers no Agent
description: Como conectar apps do catálogo e servidores MCP personalizados a um Agent, escolher quais ferramentas ele pode usar e o que acontece quando um servidor falha.
---

# MCP Servers no Agent

MCP (Model Context Protocol) é um padrão aberto para ligar um Agent a outros sistemas. Pensa numa tomada universal: um sistema que "fala MCP" publica uma lista de ferramentas (buscar processo, criar cobrança, agendar reunião) e qualquer Agent conectado a ele passa a poder usá-las, sem você precisar cadastrar ferramenta por ferramenta.

No Atende Direito existem três origens de MCP:

| Origem | Exemplos | Como conecta |
|---|---|---|
| **CRM nativo (Atende Direito)** | Negócios, contatos, tags, conversas | Automático, em todo Agent. Você só escolhe quais ferramentas liberar. |
| **Apps do catálogo** | AdvBox, Astrea, ProJuris, ClickUp, Google Calendar, Cal.com | Você conecta a conta em **Conexões → Integrações** e depois clica em **Usar** no Agent. |
| **Servidor personalizado** | Um servidor MCP do seu time ou de um fornecedor | Você informa a URL e a autenticação. |

## Adicionar um app do catálogo

<Passos>
  <Passo>

No Agent, abra o passo **Ferramentas** e clique em **Adicionar ferramenta**. No **Catálogo de Ferramentas**, fique na aba **MCP**.

<Captura legenda="Catálogo de MCP com os servidores agrupados por categoria, cada um com seu botão de ação." src="/img/mcp-catalogo-browser.png" />

  </Passo>
  <Passo>

Encontre o app pela busca ("Buscar MCP por nome ou descrição…") ou pelos filtros de categoria. Cada card mostra um destes botões:

| Botão | Significado |
|---|---|
| **Usar** | A conta do app já está conectada no workspace. Um clique adiciona o servidor ao Agent, reaproveitando a credencial. |
| **Conectar em Integrações** | Ainda não há conta conectada. O botão abre **Conexões → Integrações** numa nova aba, para você não perder o que já preencheu no Agent. Conecte lá, volte e clique em **Usar**. |
| **Remover** | O servidor já está no Agent. Clicar tira do Agent (não apaga o servidor nem a credencial). |

  </Passo>
  <Passo>

Depois de **Usar**, o servidor aparece como card em **Ferramentas do agente**. A plataforma busca a lista de ferramentas do servidor em segundo plano; ela fica disponível em alguns instantes.

  </Passo>
  <Passo>

**Publique o Agent de novo** para valer nas conversas.

  </Passo>
</Passos>

<Dica>

Google Calendar, Google Sheets e Cal.com usam login da conta (OAuth), não token digitado. Se aparecer "Conecte o Google Workspace antes de instalar esta ferramenta", faça a conexão em [Conectar Google Workspace](/guia/conectar/google-workspace) primeiro.

</Dica>

## Adicionar um servidor personalizado

<Passos>
  <Passo>

Na aba **MCP** do catálogo, clique no botão do topo para conectar um MCP. Abre a janela **Adicionar Conexão MCP**.

<Captura legenda="Janela Adicionar Conexão MCP, com nome, transporte, URL do endpoint e tipo de autenticação." src="/img/mcp-adicionar-conexao.png" />

  </Passo>
  <Passo>

Preencha:

| Campo | O que colocar |
|---|---|
| **Nome da conexão** | Um nome para você reconhecer. Ex.: `mcp-juridico`. |
| **Transporte** | **HTTP (Streamable)** na maioria dos casos. **SSE (Server-Sent Events)** só para servidores antigos que exigem esse modo. **Stdio Curado** é para servidores operados pela própria plataforma, escolhidos de uma lista. |
| **URL do endpoint** | O endereço `https://` do servidor. |
| **Tipo de autenticação** | **Nenhuma**, **Bearer Token** ou **API Key**. |
| **Bearer token** / **API key** | O segredo. É guardado criptografado e nunca exibido de novo. |

Em **Configurações avançadas**:

| Campo | O que colocar |
|---|---|
| **Headers adicionais (JSON)** | Cabeçalhos extras, como `{"X-Tenant": "escritorio-01"}`. |
| **Timeout (segundos)** | De 1 a 600. Padrão 30. |

  </Passo>
  <Passo>

Clique em **Conectar**. O servidor é adicionado ao Agent e a lista de ferramentas é buscada em segundo plano.

  </Passo>
</Passos>

<Cuidado>

**Três detalhes da autenticação que pegam muita gente:**

1. **Bearer Token e API Key fazem a mesma coisa:** nos dois casos o valor é enviado como `Authorization: Bearer <valor>`.
2. **Cole só o token, sem a palavra `Bearer`.** Se você colar `Bearer eyJ...`, o servidor recebe `Bearer Bearer eyJ...` e recusa.
3. **Se o servidor exige outro cabeçalho** (ex.: `X-Api-Key`), use **Headers adicionais (JSON)**. Mas saiba que, diferente do campo de token, os headers adicionais **não** são criptografados: ficam gravados em texto na configuração do servidor (a tela só os mascara na exibição).

</Cuidado>

<Cuidado>

O campo **Timeout (segundos)** é salvo, mas hoje não altera os tempos usados na conversa. Na prática, a plataforma usa limites fixos (cerca de 15 a 30 segundos, conforme a operação).

</Cuidado>

### Regras de endereço

Por segurança, a URL precisa ser `https://` e pública. Endereços de rede interna (`localhost`, `10.x`, `192.168.x` etc.) são recusados, assim como portas abaixo de 1024 (exceto 443) e as portas 8080, 8443, 9090, 9200, 5432, 6379 e 11211. Se você precisa liberar um endereço específico, fale com o suporte: essa liberação é feita pela equipe técnica, não por uma tela de configurações.

## Escolher quais ferramentas o Agent pode usar

Um servidor pode ter dezenas de ferramentas. Você pode limitar o que o Agent enxerga.

**No Agent principal**, essa escolha existe para o **CRM nativo**, na seção **Ferramentas do CRM** do passo Ferramentas (card **Atende Direito (CRM)**). Para apps e servidores personalizados ligados ao Agent principal, ele enxerga **todas** as ferramentas que o servidor publicar.

**Em cada sub-agent**, na aba **Ferramentas** de **Configurar sub-agente**, seção **Tools liberadas**, há um card para o CRM e um card para cada servidor MCP atribuído àquele sub-agent.

Como o seletor funciona:

| Estado do interruptor **Selecionar tools** | O que o Agent enxerga |
|---|---|
| **Desligado** (padrão) | Todas as ferramentas, **menos as que apagam dados** (nomes começando com `delete`, marcadas com o selo **destrutiva**). |
| **Ligado** | Só as ferramentas marcadas. Começa com a mesma seleção do padrão; desmarque o que não quiser. Os botões **Todas** e **Nenhuma** agem por grupo. |
| **Ligado e nada marcado** | **Nenhuma** ferramenta daquele servidor. A tela avisa: "o agente fica sem acesso algum a este servidor". |

<Dica>

Para liberar uma ferramenta destrutiva (ex.: excluir um contato), ligue **Selecionar tools** e marque-a explicitamente. Ela nunca entra pelo padrão.

</Dica>

## O que acontece durante a conversa

- **Lista sempre atualizada.** A cada conversa, o Agent busca a lista de ferramentas direto no servidor. Além disso, a lista mostrada na tela é sincronizada todos os dias às 03:00.
- **Servidor fora do ar não derruba o Agent.** Se um servidor não responde ou recusa a credencial, o Agent continua a conversa **sem as ferramentas daquele servidor**, e os outros servidores seguem normais. O cliente não vê erro; o Agent só não consegue fazer o que dependia daquele app.
- **Erro de configuração derruba.** Já um problema de configuração (URL bloqueada pelas regras de segurança, credencial que não existe mais) impede o Agent de ser montado naquela execução.
- **Respostas longas são cortadas.** O que a ferramenta devolve é limitado a cerca de 4 mil tokens antes de chegar ao Agent.
- **Nomes sem prefixo.** O Agent vê cada ferramenta com o nome que o servidor publicou. Se dois servidores do mesmo Agent tiverem uma ferramenta com o mesmo nome, haverá conflito. Evite ligar ao mesmo Agent dois servidores com nomes de ferramenta iguais.

<Cuidado>

Um servidor MCP lento atrasa o início de cada resposta do Agent, porque a lista de ferramentas é buscada antes de o Agent começar. Se um Agent ficou lento depois de ganhar um servidor novo, teste sem ele no [Playground](/guia/agents/playground).

</Cuidado>

## Remover ou excluir

- **Remover** (no card do catálogo) ou a lixeira **Remover ferramenta** (no passo Ferramentas) tira o servidor só daquele Agent.
- Excluir o servidor de vez apaga também a credencial dele, se nenhum outro servidor a usar.

## Importar um app próprio (.adapp)

Se o sistema que você quer conectar não tem servidor MCP, mas tem uma especificação **OpenAPI**, é possível empacotá-lo como um app `.adapp` e importar pelo Flow Builder (**Importar app**). Cada operação da especificação vira uma ferramenta. O formato e os limites estão em [Para Desenvolvedores → Formato .adapp](/dev/adapp/formato).

<Cuidado>

Apps importados a partir de OpenAPI são feitos para o nó **Ferramenta MCP** do Flow Builder. O uso desses apps dentro de um Agent ainda não está validado; confirme com o suporte antes de depender disso em produção.

</Cuidado>

## Permissões

| Ação | Quem pode |
|---|---|
| Ver o catálogo e os servidores | Quem pode ver agents |
| Adicionar, editar, excluir servidores e importar `.adapp` | Workspace Admin e Suporte |
| Vincular um servidor já existente a um Agent | Quem pode editar agents (inclui Manager) |

## Saiba mais

- [Catálogo MCP](/dev/catalogo-mcp) — o que cada app do catálogo sabe fazer
- [Ferramentas do Agent](/guia/agents/ferramentas) — CRM nativo e visão geral
- [Function Tools](/guia/agents/function-tools) — quando o sistema não tem MCP