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:

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

   Resposta (200):

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

   

   CAPTURAR: Resposta JSON do GET /mcp-catalog no cliente HTTP (Insomnia/Postman) mostrando a lista de itens curados

2. ·

   Passo 2 — Criar o servidor

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

   Body (servidor curado):

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

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

   Resposta (201):

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

   Atenção

   Não insira credenciais diretamente no campo config.headers como string fixa. Use sempre secret_value para que a plataforma gerencie o segredo com segurança.

3. ·

   Passo 3 — Testar a conexão

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

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

   Resposta de sucesso (200):

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

   Resposta de erro (200 com status de erro):

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

   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:

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

   Resposta (200):

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

   Atenção

   Este endpoint faz uma chamada real ao servidor externo. Execute-o somente quando o servidor estiver acessível (status connected no Passo 3).

5. ·

   Passo 5 — Listar as ferramentas disponíveis

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

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

   Resposta (200):

   [
     {
       "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:

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

   {
     "mcp_server_id": "uuid-server",
     "enabled": true
   }

   Resposta (200):

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

   

   CAPTURAR: Nó mcp.call_tool no canvas com os campos mcp_server_id e tool_name preenchidos e um parâmetro mapeado com expressão do 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