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.

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