O Model Context Protocol (MCP) é um padrão aberto para conectar IA a ferramentas e dados externos. Adicione um servidor MCP ao seu workspace e suas ferramentas ficam disponíveis para seus agentes — uma forma de integrar serviços para os quais o Zoen não tem integração nativa.
Adicionando um servidor MCP como ferramenta
Servidores MCP fornecem coleções de ferramentas que seus agentes podem usar.
Para adicionar um:
- Vá em Settings → MCP Tools
- Clique em Add para abrir o modal de configuração
- Informe um Server Name e uma Server URL
- Adicione quaisquer Headers necessários (ex.: chaves de API)
- Clique em Add MCP para salvar
Você também pode configurar servidores MCP diretamente pela barra de ferramentas de um bloco Agent para uma configuração rápida.
Opções de configuração do servidor
| Campo | Descrição |
|---|---|
| Name | Nome de exibição do servidor |
| URL | O endpoint do servidor MCP |
| Transport | Atualmente oferece streamable-http |
| Headers | Pares chave-valor para autenticação ou cabeçalhos personalizados |
| Timeout | Timeout de conexão em milissegundos (padrão: 30.000) |
Variáveis de ambiente na configuração
URLs e headers do servidor aceitam substituição de variáveis de ambiente com a sintaxe {{VAR_NAME}}. Isso mantém valores sensíveis como chaves de API fora da configuração do servidor.
URL: https://api.example.com/mcp
Authorization: Bearer {{MCP_API_TOKEN}}Quando você digita {{ nos campos de URL ou header, um dropdown aparece mostrando as variáveis de ambiente disponíveis do workspace.
Teste e validação
Clique em Test Connection antes de salvar para verificar se o servidor está acessível e descobrir as ferramentas disponíveis. A resposta do teste mostra o número de ferramentas encontradas e a versão do protocolo.
Depois de salvar, cada servidor exibe suas ferramentas disponíveis com nomes de parâmetros, tipos e flags de obrigatoriedade. Se as ferramentas de um servidor mudarem (ex.: após uma atualização do servidor), clique em Refresh para buscar os schemas mais recentes. Isso atualiza automaticamente quaisquer blocos Agent que usem essas ferramentas.
Badges de validação de ferramenta aparecem em servidores com problemas — por exemplo, se uma ferramenta foi removida do servidor mas ainda é referenciada em um workflow. Clique no badge para ver quais workflows são afetados.
Allowlist de domínios
Deployments self-hosted podem restringir quais domínios de servidor MCP são permitidos definindo a variável de ambiente ALLOWED_MCP_DOMAINS (lista separada por vírgulas). Quando definida, só servidores em domínios aprovados podem ser adicionados. Quando não definida, todos os domínios são permitidos.
Usando ferramentas MCP em agentes
Depois que os servidores MCP estão configurados, suas ferramentas ficam disponíveis nos blocos Agent:
- Abra um bloco Agent
- Na seção Tools, clique em Add tool…
- Em MCP Servers, clique em um servidor para ver suas ferramentas
- Selecione ferramentas individuais, ou escolha Use all N tools para adicionar todas as ferramentas daquele servidor
- O agente agora pode acessar essas ferramentas durante a execução
Se você ainda não configurou um servidor, clique em Add MCP Server no topo do dropdown para abrir o modal de configuração sem sair do bloco.
Bloco MCP Tool avulso
Para controle mais granular, você pode usar o bloco MCP Tool dedicado para executar ferramentas MCP específicas:
O bloco MCP Tool executa uma ferramenta configurada com parâmetros que você define explicitamente, e sua saída é legível por blocos posteriores como qualquer outra.
Quando usar MCP Tool vs. Agent
| Agent com ferramentas MCP | Bloco MCP Tool | |
|---|---|---|
| Execução | A IA decide quais ferramentas chamar | Determinístico — executa a ferramenta que você escolhe |
| Parâmetros | A IA escolhe em tempo de execução | Você define explicitamente |
| Ideal para | Fluxos dinâmicos e conversacionais | Passos estruturados e repetíveis |
| Raciocínio | Lida com lógica complexa de vários passos | Uma ferramenta, uma chamada |
Requisitos de permissão
A funcionalidade MCP exige permissões específicas do workspace:
| Ação | Permissão necessária |
|---|---|
| Criar ou atualizar servidores MCP | Write ou Admin |
| Excluir servidores MCP | Admin |
| Usar ferramentas MCP em agentes | Write ou Admin |
| Ver ferramentas MCP disponíveis | Read, Write ou Admin |
| Executar blocos MCP Tool | Read, Write ou Admin |
Servidores MCP rodam com as permissões do usuário que os configurou — conecte só servidores em que você confia, e revise as ferramentas de um servidor antes de entregá-las aos agentes.