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 (campo 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 armazenados juntos, cifrados, em uma única credencial; header_map indica qual valor vai em qual header. Use isso em vez de duas credenciais separadas, pois cada servidor MCP aceita uma credencial.
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 uma única credencial — existe justamente para providers como a Superlógica, que exigem dois valores ao mesmo tempo.

Headers enviados ao servidor MCP

Conforme o tipo de autenticação, a plataforma envia estes headers nas chamadas ao seu servidor MCP:

Tipo	Header enviado
bearer	Authorization: Bearer {segredo}
header	{header}: {scheme}{segredo} (sem prefixo quando scheme é vazio)
headers	Um header por entrada de header_map, sem prefixo: {header}: {valor da chave correspondente}. O segredo da credencial deve ser um JSON no formato {"chave": "valor", ...}.

Um servidor MCP usa um único formato de autenticação, nunca dois ao mesmo tempo.

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.