👤 Para administradores de pipe e times de operações
🔐 Disponível para todos os planos
🎯 Para quem quer operar o Pipefy em linguagem natural a partir do assistente de IA que já usa
Seus processos no Pipefy agora podem ser acionados diretamente pelo assistente de IA que você já usa no dia a dia. Em vez de abrir o app para criar um card, mover uma etapa ou consultar um relatório, você digita o que precisa e o assistente executa.
Ao terminar este artigo, você vai saber instalar e configurar o Pipefy AI Toolkit no seu computador e conectá-lo ao seu assistente de IA preferido, pronto para operar o Pipefy em linguagem natural.
📖 O que você vai entender aqui:
O que é o Pipefy AI Toolkit
O Pipefy AI Toolkit é um pacote open source que conecta o Pipefy a assistentes de IA compatíveis com o protocolo MCP (Model Context Protocol). Ele é formado por três componentes:
| Componente | O que faz |
| pipefy-mcp-server | Expõe as ferramentas do Pipefy para o assistente de IA chamar (pipes, cards, automações, AI Agents, relatórios e mais) |
| CLI pipefy | Permite operar o Pipefy pelo terminal com comandos diretos |
| Skills | Playbooks prontos que ensinam o assistente a seguir boas práticas em cada caso de uso |
O toolkit funciona com Cursor, Claude Desktop, Claude Code, Codex e qualquer outro cliente compatível com MCP.
O toolkit não substitui a interface web do Pipefy. Ele automatiza o que você já faria na UI, com confirmação antes de qualquer ação destrutiva.
O que você precisa antes de começar
Conta e permissões no Pipefy
Você precisa ter acesso de administrador nos pipes em que o assistente vai atuar. Se for usar uma conta de serviço (recomendado para manter o MCP sempre conectado sem depender de login no navegador), crie a conta em Admin > Service Accounts no Pipefy e adicione ela como membro dos pipes necessários.
Software no computador
| Requisito | Detalhe |
| Sistema operacional | macOS, Linux ou Windows |
| Python 3.11 ou superior | O instalador resolve isso automaticamente na maioria dos casos |
| Cliente de IA | Cursor, Claude Desktop, Claude Code, Codex ou outro compatível com MCP |
Instalação
O instalador configura o CLI e o servidor MCP em um único comando. Substitua cursor pelo nome do seu cliente:
curl -fsSL https://raw.githubusercontent.com/pipefy/ai-toolkit/main/install.sh \
| sh -s -- --client cursor
Clientes disponíveis: cursor, claude-code, claude-desktop, codex. Use none se quiser instalar sem registrar automaticamente no cliente e colar a configuração depois.
Flags úteis
| Flag | Efeito |
| --yes | Instala sem pedir confirmações |
| --no-skills | Pula a instalação dos playbooks |
| --dry-run | Mostra o que o comando faria, sem executar nada |
| --client none | Só instala; você cola a configuração no cliente depois |
Após a instalação, confirme que os comandos estão disponíveis:
pipefy --help
pipefy-mcp-server --help
Se aparecer command not found, adicione ~/.local/bin ao PATH do seu terminal (o instalador avisa quando isso acontece).
Autenticação
Escolha uma das três opções conforme o seu caso de uso:
Opção A: Login no navegador (recomendada para uso pessoal e CLI)
pipefy auth login
Abre o navegador, faz o OAuth e guarda a sessão no cofre do sistema. É a opção mais simples para quem vai usar o toolkit no próprio computador.
Em ambientes sem interface gráfica (servidor remoto), use:
pipefy auth login --device
Opção B: Conta de serviço (recomendada para MCP sempre conectado)
Ideal quando você quer que o assistente de IA funcione sem depender de uma sessão de navegador aberta. Configure as credenciais no arquivo ~/.config/pipefy/config.toml:
service_account_client_id = "SEU_CLIENT_ID"
service_account_client_secret = "SEU_CLIENT_SECRET"
Ou como variáveis de ambiente:
PIPEFY_SERVICE_ACCOUNT_CLIENT_ID=...
PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET=...
Opção C: Token bearer (para testes pontuais)
pipefy --token "SEU_BEARER" pipe list
Nunca coloque client secret ou token em repositórios Git, prints ou documentos compartilhados.
Precedência: --token > PIPEFY_TOKEN > conta de serviço > sessão do auth login. Se o CLI estiver usando credenciais erradas, verifique se há variáveis de ambiente sobrescrevendo a sessão guardada.
Ativar o MCP no seu assistente de IA
Após a instalação com --client <nome>, o servidor já está registrado. Se preferiu --client none, cole o JSON abaixo no arquivo de configuração do seu cliente:
{
"mcpServers": {
"pipefy": {
"command": "pipefy-mcp-server"
}
}
}
Se estiver usando conta de serviço, adicione as variáveis de ambiente dentro do bloco:
{
"mcpServers": {
"pipefy": {
"command": "pipefy-mcp-server",
"env": {
"PIPEFY_SERVICE_ACCOUNT_CLIENT_ID": "SEU_CLIENT_ID",
"PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET": "SEU_CLIENT_SECRET"
}
}
}
}
Cursor
Arquivo de configuração: ~/.cursor/mcp.json (macOS/Linux) ou %USERPROFILE%\.cursor\mcp.json no Windows.
Após salvar, reinicie o Cursor e confirme em Settings > MCP que o servidor pipefy aparece como Enabled.
Claude Desktop
Arquivo de configuração: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows).
Após salvar, reinicie o Claude Desktop.
Claude Code
No terminal do projeto ou globalmente:
/plugin marketplace add pipefy/ai-toolkit
/plugin install pipefy
/pipefy:install
/pipefy:login
Para usar conta de serviço no Claude Code, edite ~/.claude.json e adicione o bloco env ao servidor pipefy.
Alternativa via terminal:
claude mcp add --scope project pipefy -- pipefy-mcp-server
claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_ID <ID>
claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET <SECRET>
Codex
Adicione em ~/.codex/config.toml:
[mcp_servers.pipefy]
command = "pipefy-mcp-server"
Reinicie o Codex após salvar.
Outros clientes MCP
Use o mesmo padrão: comando pipefy-mcp-server, transporte stdio, variáveis de ambiente para credenciais. Consulte a documentação do seu cliente para o caminho exato do arquivo de configuração.
Como confirmar que está funcionando
Após reiniciar o cliente, peça ao assistente:
"Use a ferramenta search_pipes para listar pipes com nome contendo 'RH'." Se o assistente listar pipes, o MCP está conectado e autenticado.
Se aparecer erro de autenticação, configure a conta de serviço ou refaça o pipefy auth login. Se aparecer PERMISSION_DENIED, adicione a conta de serviço (ou seu usuário) ao pipe alvo.
Problemas comuns no setup
| Sintoma | O que fazer |
| Assistente diz que não tem ferramentas Pipefy | Habilitar o servidor pipefy nas configurações MCP e reiniciar o app |
| command not found após instalação | Adicionar ~/.local/bin ao PATH e abrir novo terminal |
| Config JSON inválida | Verificar vírgulas e chaves em mcp.json ou claude_desktop_config.json |
| Erro 401 ou falha de autenticação | Conferir ID/secret e se a conta de serviço é membro do pipe |
| MCP funciona no Cursor mas não no Claude Desktop | Cada app tem arquivo de config separado; repetir a ativação com --client claude-desktop |
| pipefy auth login falha no macOS | Rodar uma vez no Terminal.app e aprovar o diálogo do cofre do sistema |
Antes de avançar, confirme que você:
☐ Entende que o Pipefy AI Toolkit conecta seu assistente de IA ao Pipefy via protocolo MCP
☐ Escolheu e configurou uma das três opções de autenticação
☐ O servidor pipefy aparece como conectado no seu cliente de IA
☐ Testou com um prompt simples e o assistente retornou dados do Pipefy
