Atende Direito · Docs

Tema

Cadastrar um MCP Server ​

Este guia cobre o fluxo completo de cadastro, teste e ativação de um servidor MCP — do catálogo até o nó no canvas. Siga os 7 passos na ordem; cada um depende do anterior.

  1. Passo 1 — Listar o catálogo

    Consulte os servidores curados disponíveis para o seu workspace:

    http
    GET /api/v1/mcp-catalog
Authorization: Bearer {token}

    Resposta (200):

    json
    [
  {
    "id": "uuid-asaas",
    "name": "asaas",
    "label": "Asaas",
    "category": "Pagamentos",
    "transport": "http",
    "required_secrets": ["ASAAS_API_KEY"]
  }
]

    Use o id retornado como catalog_id no próximo passo. Para um servidor customizado, omita catalog_id.

    Modal 'Catálogo de Ferramentas' no Agent Builder listando os servidores MCP curados disponíveis (AdvBox, Asaas, ElevenLabs, Firecrawl, Google Workspace, Resend, ZapSign)

    Modal 'Catálogo de Ferramentas' no Agent Builder listando os servidores MCP curados disponíveis (AdvBox, Asaas, ElevenLabs, Firecrawl, Google Workspace, Resend, ZapSign)

  2. Passo 2 — Criar o servidor

    http
    POST /api/v1/mcp-servers
Authorization: Bearer {token}
Content-Type: application/json

    Body (servidor curado):

    json
    {
  "catalog_id": "uuid-asaas",
  "name": "Asaas Produção",
  "transport": "http",
  "config": {
    "url": "https://api.asaas.com",
    "headers": {
      "access_token": "$ASAAS_API_KEY"
    }
  },
  "secret_value": "sua_chave_api_aqui"
}

    Body (servidor customizado):

    json
    {
  "name": "API Interna",
  "transport": "http",
  "config": {
    "url": "https://mcp.sua-empresa.com.br",
    "headers": {}
  },
  "secret_value": "token_interno"
}

    Resposta (201):

    json
    {
  "id": "uuid-server",
  "name": "Asaas Produção",
  "status": "pending",
  "credential_id": "mcp-server:Asaas Produção",
  "transport": "http"
}

    O servidor nasce com status: pending. A credencial é armazenada no CredentialVault com o identificador mcp-server:{name} — nunca em texto plano.

    Dialog de criação de novo servidor MCP customizado com campos de URL, headers e credenciais

    Dialog de criação de novo servidor MCP customizado com campos de URL, headers e credenciais

  3. Passo 3 — Testar a conexão

    Verifica se o servidor está acessível (latência + HTTP 2xx):

    http
    POST /api/v1/mcp-servers/{id}/test
Authorization: Bearer {token}

    Resposta de sucesso (200):

    json
    {
  "status": "connected",
  "latency_ms": 142
}

    Resposta de erro (200 com status de erro):

    json
    {
  "status": "error",
  "message": "Connection refused: timeout after 5000ms"
}
    Dialog de instalação do servidor MCP mostrando status de conexão e seleção de ferramentas disponíveis

    Dialog de instalação do servidor MCP mostrando status de conexão e seleção de ferramentas disponíveis

    Dica

    Se receber error, verifique: (1) a URL está correta e acessível pela internet, (2) a credencial foi informada corretamente, (3) o servidor não é um IP privado — o SSRF Guard bloqueia endereços internos. Veja Referência.

  4. Passo 4 — Sincronizar as ferramentas

    Realiza o handshake JSON-RPC (initialize + tools/list) com o servidor e persiste os descritores de tools no banco:

    http
    POST /api/v1/mcp-servers/{id}/refresh-tools
Authorization: Bearer {token}

    Resposta (200):

    json
    {
  "status": "connected",
  "tools_count": 8,
  "synced_at": "2026-06-27T14:30:00Z"
}

    Após este passo, o status do servidor muda para connected e as ferramentas ficam disponíveis para consulta.

  5. Passo 5 — Listar as ferramentas disponíveis

    Lê os descritores persistidos (não faz nova chamada ao servidor):

    http
    GET /api/v1/mcp-servers/{id}/tools
Authorization: Bearer {token}

    Resposta (200):

    json
    [
  {
    "name": "criar_cobranca",
    "description": "Cria uma cobrança no Asaas para um cliente existente.",
    "parameters": [
      {
        "name": "customer_id",
        "type": "string",
        "description": "ID do cliente no Asaas",
        "required": true
      },
      {
        "name": "value",
        "type": "number",
        "description": "Valor da cobrança em reais",
        "required": true
      }
    ]
  }
]

    Os parâmetros são convertidos pelo McpSchemaConverter e expostos como ToolParameter[] — o mesmo formato que o canvas do Flow Builder usa para montar o formulário do nó.

  6. Passo 6 — Vincular ao Agent

    Para que um Agent possa invocar tools deste servidor, vincule-o via pivot agent_mcp_servers:

    http
    POST /api/v1/agents/{agent_id}/mcp-servers
Authorization: Bearer {token}
Content-Type: application/json
    json
    {
  "mcp_server_id": "uuid-server",
  "enabled": true
}

    Resposta (200):

    json
    {
  "agent_id": "uuid-agent",
  "mcp_server_id": "uuid-server",
  "enabled": true
}
    Dica

    Um Agent pode ter múltiplos servidores MCP vinculados. Desative temporariamente um servidor sem desvinculá-lo passando "enabled": false.

  7. Passo 7 — Usar no Flow Builder

    Com o servidor conectado e vinculado, arraste o nó Ferramenta MCP (mcp.call_tool) para o canvas:

    • mcp_server_id → selecione o servidor cadastrado
    • tool_name → selecione a tool (ex.: criar_cobranca)
    • parameters → mapeie cada parâmetro com expressões do fluxo (ex.: {{contact.id}}, {{vars.valor_cobranca}})

    O nó é determinístico: executa a chamada MCP e retorna o resultado, sem envolver um LLM.

    Veja os detalhes de configuração do nó na página Usar Tools no Fluxo.

Resumo do fluxo ​

GET /mcp-catalog
  └─ POST /mcp-servers              (status: pending)
       └─ POST /mcp-servers/{id}/test       (connected/error)
            └─ POST /mcp-servers/{id}/refresh-tools  (sync tools)
                 └─ GET /mcp-servers/{id}/tools       (lê descritores)
                      └─ POST /agents/{id}/mcp-servers  (pivot)
                           └─ nó mcp.call_tool no canvas

Saiba mais ​