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.

Atenção

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.

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.

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:

{
  "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).

Atenção

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.

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.

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 — fluxo completo de cadastro e ativação.
• Usar tools no fluxo — o nó mcp.call_tool no canvas.
• O que é um Plugin / MCP — visão geral do protocolo e dos tipos de servidor.