---
title: Referência MCP
---

# Referência MCP

Consulta rápida de transports, status, limites e proteções de segurança.

## Transports

O campo `transport` define o protocolo de comunicação entre o Atende Direito e o servidor MCP.

| Transport | Descrição | Quando usar |
|-----------|-----------|-------------|
| `http` | HTTP Streamable — requisições HTTP padrão com suporte a streaming de resposta. Stateless. | APIs REST externas, a maioria dos servidores MCP hospedados na nuvem. |
| `sse` | Server-Sent Events — conexão persistente (stateful). O servidor mantém o estado entre chamadas da mesma sessão. | Servidores que precisam de contexto acumulado entre tools calls. |
| `stdio_curated` | Processo local gerenciado pela plataforma. O binário é executado internamente pelo Atende Direito. | Exclusivo para entradas do catálogo curado (ElevenLabs, Firecrawl, ZapSign). Não disponível para servidores customizados. |

<Cuidado>

O transport `stdio_curated` não pode ser informado ao cadastrar um servidor customizado. Ele é reservado para servidores do catálogo oficial e é gerenciado internamente pela plataforma.

</Cuidado>

## Status do servidor

| Status | Significado |
|--------|-------------|
| `pending` | Servidor recém-criado. Conexão ainda não testada. |
| `connected` | Conexão testada com sucesso e tools sincronizadas. |
| `error` | Última tentativa de conexão ou sincronização falhou. |
| `disabled` | Servidor desativado manualmente ou pelo administrador do workspace. |

O status é atualizado automaticamente após as chamadas a `/test` e `/refresh-tools`. Um servidor em `error` ou `disabled` **não pode** ser usado pelo nó `mcp.call_tool` — o canvas exibe um aviso antes da publicação.

## Limites

| Limite | Valor |
|--------|-------|
| Máximo de tools por servidor | **100** |
| Tamanho máximo do `name` da tool | **256 caracteres** |
| Tamanho máximo da `description` da tool | **2048 caracteres** |

<Dica>

Se o servidor retornar mais de 100 tools no `tools/list`, o `refresh-tools` persiste apenas as primeiras 100 (por ordem retornada pelo servidor). Prefira servidores MCP que expõem conjuntos de tools coesos e bem dimensionados.

</Dica>

## SSRF Guard

O **SSRF Guard** (`SsrfGuard::checkUrl`) é uma proteção que bloqueia requisições a endereços privados ou de loopback antes de qualquer chamada ao servidor MCP. Isso impede que um servidor mal configurado (ou malicioso) use o Atende Direito como proxy para acessar recursos internos da infraestrutura.

### Endereços bloqueados

- Loopback: `127.0.0.1`, `::1`, `localhost`
- RFC 1918 (privados): `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
- Link-local: `169.254.0.0/16`, `fe80::/10`
- Outros endereços reservados conforme RFC 6890

### Comportamento

Quando a URL informada resolve para um endereço bloqueado, o servidor retorna:

```json
{
  "status": "error",
  "message": "SSRF blocked: resolved IP is in a private range"
}
```

Esse bloqueio ocorre tanto no cadastro (`POST /mcp-servers`) quanto em cada chamada de teste (`/test`) e sincronização (`/refresh-tools`).

<Cuidado>

Servidores MCP customizados devem estar hospedados em endereços públicos acessíveis pela internet. Servidores em redes internas (VPN, intranet, localhost) não são compatíveis com a plataforma por razões de segurança.

</Cuidado>

## Auth do catálogo (`config_schema.auth`)

Cada entrada do catálogo curado (`mcp_catalog.config_schema.auth`) declara **como** a credencial do usuário é injetada nas chamadas ao servidor MCP. O campo `type` escolhe o mecanismo; os demais campos variam conforme o tipo.

| `type` | Campos | Quando usar |
|--------|--------|-------------|
| `bearer` | `header` (fixo `Authorization`), `scheme` (fixo `Bearer`) | Provider expõe **um único** token de API que a própria doc do vendor já chama de "Bearer token" (AdvBox, Meu Estagiário, Sync, Asaas). |
| `header` | `header` (nome do header), `scheme` (prefixo, geralmente vazio), `connect_url` (opcional, tela de login externa) | Provider expõe **um único** valor (token ou identificador de conta) que vai num header sem o prefixo `Bearer ` (Astrea e Eterno Jurídico usam `X-Account`; Infinitum usa `X-Public-Token`; ClickUp usa `Authorization`, mas sem o prefixo `Bearer `, então também cai neste tipo em vez de `bearer`). |
| `headers` (plural) | `header_map` (mapa `nome do header → chave do secret`) | Provider exige **mais de um** valor simultâneo, cada um num header próprio (Superlógica: `X-App-Token` + `X-Access-Token`). Os dois valores são cifrados juntos como **um único JSON** na mesma `FlowCredential`; `header_map` diz ao engine qual chave do JSON vai em qual header. Use isso — em vez de duas credenciais separadas — porque o `mcp_servers.credential_id` só aponta para **uma** credencial por servidor. |
| `oauth2` | `header`, `scheme`, `provider` (`google`/`calcom`) | Conexão feita pela própria plataforma via OAuth (o usuário nunca digita segredo); o access token é cunhado e renovado automaticamente pelo provider indicado. |

<Dica>

`bearer` e `header` (singular) resolvem para **um** header a partir de **um** secret. `headers` (plural) é a única variante que resolve para **múltiplos** headers a partir de um único `credential_id` — existe justamente para providers como a Superlógica, que exigem duas credenciais ao mesmo tempo sem que a plataforma precise armazenar duas `FlowCredential` distintas por servidor.

</Dica>

### Como o engine aplica cada tipo

Na configuração runtime de um `McpServer` (endpoint engine-facing `GET /api/flow-builder/mcp-servers/{id}`), os tipos acima viram estes campos em `mcp_servers.config`, consumidos tanto pelo `McpToolDiscoveryService` (chamadas de teste/discovery feitas pelo Laravel) quanto pelo flow-engine (Go, `buildAuthHTTPClient`):

| Campo em `config`/resposta do engine | Preenchido quando | Efeito |
|----------------------------------------|--------------------|--------|
| `auth_header` / `auth_prefix` | `auth.type` é `header` (ou `bearer`, com os defaults `Authorization`/`Bearer `) | O secret resolvido de `credential_id` é injetado em **um** header: `{auth_header}: {auth_prefix}{secret}`. |
| `auth_headers` | `auth.type` é `headers` | O secret resolvido de `credential_id` é decodificado como **JSON** (`{"chave": "valor", ...}`); para cada par `header → chave` em `auth_headers`, o engine injeta `{header}: {valor da chave no JSON}`, sem prefixo. |

`auth_header`/`auth_prefix` e `auth_headers` **não coexistem** no mesmo servidor — um `McpServer` usa um formato ou o outro, nunca os dois.

## Endpoints de referência rápida

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `GET` | `/api/v1/mcp-catalog` | Lista servidores curados |
| `POST` | `/api/v1/mcp-servers` | Cria um servidor MCP |
| `GET` | `/api/v1/mcp-servers` | Lista servidores do workspace |
| `GET` | `/api/v1/mcp-servers/{id}` | Detalhe de um servidor |
| `PUT` | `/api/v1/mcp-servers/{id}` | Atualiza configuração |
| `DELETE` | `/api/v1/mcp-servers/{id}` | Remove o servidor |
| `POST` | `/api/v1/mcp-servers/{id}/test` | Testa conectividade |
| `POST` | `/api/v1/mcp-servers/{id}/refresh-tools` | Sincroniza tools via handshake JSON-RPC |
| `GET` | `/api/v1/mcp-servers/{id}/tools` | Lista tools persistidas |
| `POST` | `/api/v1/agents/{id}/mcp-servers` | Vincula servidor ao agent (pivot) |
| `DELETE` | `/api/v1/agents/{id}/mcp-servers/{mcp_server_id}` | Desvincula servidor do agent |

## Saiba mais

- [Cadastrar MCP Server](/dev/cadastrar-mcp-server) — fluxo completo de cadastro e ativação.
- [Usar tools no fluxo](/dev/usar-tools-no-fluxo) — o nó `mcp.call_tool` no canvas.
- [O que é um Plugin / MCP](/dev/o-que-e-plugin) — visão geral do protocolo e dos tipos de servidor.