---
title: Cadastrar um MCP Server
outline: [2, 3]
---

# 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.

<Passos>

<Passo>

**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`.

<Captura legenda="Modal 'Catálogo de Ferramentas' no Agent Builder listando os servidores MCP curados disponíveis (AdvBox, Asaas, ElevenLabs, Firecrawl, Google Workspace, Resend, ZapSign)" src="/img/mcp-catalogo-browser.png" />

</Passo>

<Passo>

**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.

<Captura legenda="Dialog de criação de novo servidor MCP customizado com campos de URL, headers e credenciais" src="/img/mcp-novo-server-dialog.png" />

<Cuidado>

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.

</Cuidado>

<Cuidado>

**Permissão requerida:** conectar, registrar, editar ou remover um servidor MCP (`POST`/`PATCH`/`DELETE /mcp-servers`) exige a permissão `agent mcp.connect` **e** que o usuário seja **admin ou owner do workspace** (`admin-or-owner`). Sem isso, a API responde `403`. `agent mcp.*` é um grupo de permissões sensível — não é concedido por padrão a roles comuns como Manager.

</Cuidado>

</Passo>

<Passo>

**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"
}
```

<Captura legenda="Dialog de instalação do servidor MCP mostrando status de conexão e seleção de ferramentas disponíveis" src="/img/mcp-instalar-dialog.png" />

<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](./referencia#ssrf-guard).

</Dica>

</Passo>

<Passo>

**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.

<Cuidado>

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

</Cuidado>

<Cuidado>

**Permissão requerida:** testar a conexão (`POST /mcp-servers/{id}/test`) e atualizar a lista de tools (`POST /mcp-servers/{id}/refresh-tools`) exigem `agent mcp.invoke` **e** `admin-or-owner` — o mesmo requisito de admin/owner do cadastro, já que ambos os endpoints fazem chamadas reais ao servidor externo em nome do workspace.

</Cuidado>

</Passo>

<Passo>

**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ó.

</Passo>

<Passo>

**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`.

</Dica>

</Passo>

<Passo>

**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.: <code v-pre>{{contact.id}}</code>, <code v-pre>{{vars.valor_cobranca}}</code>)

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](./usar-tools-no-fluxo).

</Passo>

</Passos>

## 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

- [Usar tools no fluxo](/dev/usar-tools-no-fluxo) — configuração do nó `mcp.call_tool` no canvas.
- [Referência](/dev/referencia) — transports, status, SSRF Guard e limites.
- [Catálogo MCP](/dev/catalogo-mcp) — apps curados disponíveis para conectar.