👤 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
Comece por aqui: O que é o Pipefy MCP Server e o que ele torna possível
Com o Pipefy conectado ao seu assistente de IA, você passa a operar processos em linguagem natural: consultar pipes, acompanhar cards e, dependendo do caminho escolhido, executar ações dentro do fluxo. Existem duas formas de fazer essa conexão, e a primeira decisão do artigo é justamente qual delas atende o seu caso.
O caminho hospedado leva dois comandos e não exige instalar nada na sua máquina. O caminho local pede mais preparação e libera a superfície completa de ferramentas, incluindo as que escrevem no processo. Ao terminar, você terá o Pipefy conectado e testado no assistente.
📖 O que você vai entender aqui:
O que é o Pipefy AI Toolkit
O Pipefy AI Toolkit é o pacote open source que conecta o Pipefy a assistentes de IA compatíveis com o Model Context Protocol (MCP). Três componentes dele importam para este artigo:
| Componente | O que faz |
|---|---|
| pipefy-mcp-server | Expõe as ferramentas do Pipefy para o assistente chamar: pipes, cards, fases, automações, AI Agents e relatórios |
| CLI pipefy | Permite operar o Pipefy pelo terminal, com comandos alinhados às capacidades do servidor |
| Skills | Playbooks prontos que orientam o assistente a seguir boas práticas em cada caso de uso |
O toolkit não substitui a interface web do Pipefy. Ele automatiza o que você já faria na tela, e ações que não podem ser desfeitas pedem confirmação antes de executar. Para entender o desenho por trás disso, veja "O que é o Pipefy MCP Server e o que ele torna possível".
Passo 1: escolha o caminho de conexão
As duas formas de conectar habilitam superfícies diferentes. Compare antes de começar:
| Caminho hospedado | Caminho local | |
|---|---|---|
| Instalação | Nenhuma. Dois comandos no seu cliente de IA. | Instalador, Python via uv e configuração do arquivo do cliente. |
| O que habilita | Superfície somente leitura: consultar pipes, cards, fases, automações, agentes e consumo de IA. | Superfície completa: tudo do hospedado, mais criar cards, mover cards de fase, alterar fases, criar AI Agents e criar pipes. |
| Sistemas operacionais | Qualquer um em que o seu cliente de IA rode. | macOS e Linux pelo instalador oficial. Windows pelo caminho manual do passo 4. |
| Quando escolher | Você quer consultar processos, acompanhar status e gerar análises. | Você quer que o assistente execute ações dentro dos processos. |
Se a sua dúvida é "por onde começo", comece pelo hospedado. Ele leva dois minutos, prova que a conexão funciona e cobre todas as consultas. Você pode migrar para o local depois, quando precisar executar ações.
Não registre os dois caminhos com o mesmo nome. Escolha um único registro MCP chamado pipefy: misturar o transporte HTTP hospedado e o servidor local sob o mesmo nome quebra a conexão. Para limpar um registro anterior, use claude mcp remove pipefy -s user
Passo 2: caminho hospedado (somente leitura)
Este caminho conecta o assistente ao servidor hospedado do Pipefy. Não requer Python, nem uv, nem edição de arquivo de configuração, nem descobrir caminho de executável.
Conectar
No terminal, com o Claude Code instalado:
claude mcp add --transport http --scope user \
--client-id pipefy-mcp \
pipefy https://mcp.pipefy.com/mcp
Na primeira chamada o assistente pede autenticação e você aprova o acesso com a sua conta Pipefy pelo navegador. A partir daí a conexão vale para todas as conversas.
Testar
Peça ao assistente:
"Use a ferramenta search_pipes para listar pipes com nome contendo 'RH'." Se o assistente listar pipes reais da sua conta, a conexão está funcionando.
Se você tentar um comando de escrita neste caminho (criar card, mover card de fase, criar AI Agent, alterar fase), o assistente vai responder que a ferramenta não está disponível. Não é erro de configuração: essas ferramentas ficam fora da superfície hospedada por design. Para executá-las, siga o passo 3.
Passo 3: caminho local em macOS e Linux (superfície completa)
Este caminho instala o servidor MCP e a CLI na sua máquina, e libera todas as ferramentas do Pipefy AI Toolkit. São quatro etapas: verificar pré-requisitos, instalar, autenticar e configurar o cliente de IA.
3.1 Conta e permissões no Pipefy
Você precisa ser membro dos pipes em que o assistente vai atuar. Não é necessário ser administrador para consultar e operar cards: o assistente opera com exatamente as permissões que a sua conta já tem.
Para uso desassistido (scripts, automações, CI/CD), o caminho é uma Service Account, provisionada por um Super Admin em Admin > Service Accounts, crie a conta e adicione-a como membro de cada pipe que as ferramentas devem alcançar. Isso mantém a conexão independente de um usuário específico.
Algumas operações específicas exigem a habilidade de administrador no pipe: alterar configuração de fase, criar AI Agent e criar pipe. Se você é membro sem essa habilidade, essas ações retornam PERMISSION_DENIED durante a execução.
3.2 Software necessário
| Requisito | Detalhe |
|---|---|
| Sistema operacional | O instalador oficial cobre macOS e Linux. Para Windows, siga o passo 4. |
| uv | O instalador detecta e instala o uv se ele não estiver presente. O uv resolve o próprio Python, então você não precisa instalar Python para o servidor rodar. |
| python3 | Necessário para a etapa em que o instalador mescla o JSON de configuração do cliente. Sem python3, use --client none e configure o arquivo manualmente. |
| Node com npx | Usado apenas para instalar o catálogo de skills. Sem Node, essa etapa é pulada; --no-skills torna isso explícito. |
| Assistente de IA | Claude Code, Claude Desktop, Cursor ou Codex. |
Claude Desktop não tem build para Linux. Em Linux, use Claude Code, Cursor ou configure manualmente com --client none.
No macOS, o instalador prefere deliberadamente o Python do sistema ou do Homebrew ao Python gerenciado pelo uv. O motivo é contraintuitivo e importa: os binários do Python gerenciado não têm as permissões que o macOS exige para escrever no keychain, e sem isso a autenticação falha na última etapa. Se você já tem Python do sistema ou do Homebrew, deixe como está.
Está no Windows? O instalador deste passo não roda no Windows, porque a verificação de sistema aceita apenas macOS e Linux. Vá direto para o passo 4, que cobre a instalação manual de ponta a ponta.
3.3 Instalar
O instalador configura a CLI e o servidor MCP em um comando. Substitua cursor pelo seu cliente:
curl -fsSL https://raw.githubusercontent.com/pipefy/ai-toolkit/main/install.sh \
| sh -s -- --client cursor
3.3 Instalar
O instalador configura a CLI e o servidor MCP em um comando. Substitua cursor pelo seu cliente:
| curl -fsSL https://raw.githubusercontent.com/pipefy/ai-toolkit/main/install.sh \ | sh -s -- --client cursor |
Clientes aceitos: claude-code, claude-desktop, cursor, codex. Use none para instalar sem registrar automaticamente e configurar o arquivo à mão depois.
| Flag | Efeito |
|---|---|
| --yes | Instala sem pedir confirmações |
| --no-skills | Pula a instalação do catálogo de skills |
| --dry-run | Mostra o que o comando faria, sem executar nada |
| --client none | Só instala; você configura o cliente manualmente depois |
| --allow-root | Necessário para rodar como root. Por padrão o instalador recusa e pede para rodar como usuário comum |
| --version vX.Y.Z | Fixa uma release específica em vez de seguir a mais recente |
Depois de instalar, 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 é necessário. Feche e reabra o terminal depois do ajuste.
Sem Git ou com restrição de rede: acesse o repositório pipefy/ai-toolkit no GitHub, baixe o código (Code > Download ZIP), extraia e siga as instruções do README.
3.4 Autenticar
Escolha a opção conforme o seu caso de uso:
Opção A: login no navegador (uso pessoal)
pipefy auth login
Abre o navegador, faz o OAuth e guarda a sessão no cofre do sistema.
Em máquinas corporativas, esse fluxo pode ser bloqueado por política de segurança. Se isso acontecer, use a Opção B ou a Opção C, que não dependem do navegador.
Opção B: Service Account (uso desassistido e servidores)
É o caminho para ambientes sem interface gráfica e para deixar o servidor MCP sempre conectado. Configure em 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=...
Onde fica o config.toml: em macOS e Linux, $XDG_CONFIG_HOME/pipefy/config.toml, com fallback para ~/.config/pipefy/config.toml. Em Windows, %APPDATA%\pipefy\config.toml. Você também pode apontar um caminho absoluto com a variável PIPEFY_CONFIG_FILE, útil em ambiente com múltiplas configurações. O arquivo não é criado automaticamente e a ausência dele não é erro.
Em Linux sem Secret Service disponível, defina PIPEFY_KEYCHAIN_BACKEND=file para guardar a sessão em arquivo, ou PIPEFY_DISABLE_STORED_SESSION=1 para não guardar sessão nenhuma. As duas variáveis existem justamente para ambientes headless.
Opção C: token de acesso pessoal
pipefy --token "SEU_TOKEN" pipe list
Nunca coloque client secret ou token em repositórios Git, prints ou documentos compartilhados.
Precedência de credenciais: --token, depois PIPEFY_TOKEN, depois service account, depois a sessão do auth login. Se a CLI estiver usando a credencial errada, verifique se há variável de ambiente sobrescrevendo a sessão guardada.
3.5 Configurar o cliente de IA
Instalando com --client <nome>, o servidor já fica registrado. Se você usou --client none ou o registro automático não funcionou, configure o arquivo manualmente.
O registro automático do Claude Desktop só calcula o caminho do arquivo no macOS. Em outros sistemas, mesmo passando --client claude-desktop, a configuração precisa ser feita à mão.
Passo crítico: descubra o caminho do executável na sua máquina
O arquivo de configuração precisa do caminho absoluto do executável instalado, e esse caminho varia de máquina para máquina. Não use o caminho de outra pessoa como referência.
Para descobrir, rode which pipefy-mcp-server no terminal. Se o comando não retornar nada, o executável não foi instalado corretamente: volte para o item 3.3 antes de seguir.
Claude Desktop
Localize o arquivo de configuração:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows (instalador direto): %APPDATA%\Claude\claude_desktop_config.json
- Windows (Microsoft Store): o caminho é diferente. Use a opção Editar Config dentro do app para abrir o arquivo correto.
Adicione o bloco abaixo, substituindo o caminho pelo que você descobriu:
{
"mcpServers": {
"pipefy": {
"command": "/caminho/absoluto/para/pipefy-mcp-server"
}
}
}
Usando Service Account ou token, acrescente o campo env. Com token de acesso pessoal:
{
"mcpServers": {
"pipefy": {
"command": "/caminho/absoluto/para/pipefy-mcp-server",
"env": {
"PIPEFY_TOKEN": "SEU_TOKEN"
}
}
}
}
Com Service Account, as duas variáveis entram no mesmo lugar, no lugar do token:
"env": {
"PIPEFY_SERVICE_ACCOUNT_CLIENT_ID": "SEU_CLIENT_ID",
"PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET": "SEU_CLIENT_SECRET"
}
Salve como JSON puro, sem formatação extra e sem aspas tipográficas. Um JSON mal formado faz o Claude Desktop ignorar o servidor silenciosamente, sem exibir mensagem de erro. Em Windows, caminhos dentro de JSON precisam de barras duplas.
Depois de salvar, feche o Claude Desktop por completo. Fechar a janela não basta: o app continua rodando em segundo plano. No macOS use Cmd+Q; no Windows, saia pela bandeja do sistema. Reabra e verifique em Settings > Developer > Local MCP Servers se o servidor pipefy aparece.
Cursor
Arquivo: ~/.cursor/mcp.json em macOS e Linux, %USERPROFILE%\.cursor\mcp.json em Windows. A estrutura do JSON é a mesma do Claude Desktop. Depois de salvar, reinicie o Cursor e confirme em Settings > MCP que o servidor pipefy aparece habilitado.
Claude Code
Pelo plugin:
/plugin marketplace add pipefy/ai-toolkit
/plugin install pipefy
/pipefy:install
/pipefy:pipefy-login
Ou pelo terminal, sem o plugin:
claude mcp add --scope project pipefy -- uvx pipefy-mcp-server
claude mcp add-env pipefy PIPEFY_TOKEN <TOKEN>
Com Service Account, no lugar da linha do token:
claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_ID <ID>
claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET <SECRET>
Escolha um dos dois, não os dois. Registrar o plugin e o servidor local sob o mesmo nome pipefy quebra a conexão. Se precisar trocar, remova o anterior com claude mcp remove pipefy -s user antes.
Se /plugin marketplace add não parecer fazer nada, verifique se o marketplace já está declarado em ~/.claude/settings.json sob extraKnownMarketplaces. Quando está declarado ali, o comando se torna uma operação sem efeito e nada muda, sem mensagem de erro.
Codex e outros clientes MCP
Para Codex, adicione em ~/.codex/config.toml:
[mcp_servers.pipefy]
command = "/caminho/absoluto/para/pipefy-mcp-server"
Para qualquer outro cliente compatível, o padrão é o mesmo: campo command com o caminho absoluto do executável, transporte stdio e variáveis de ambiente para credenciais.
3.6 Testar a conexão local
Depois de reiniciar o cliente, peça ao assistente:
"Use a ferramenta search_pipes para listar pipes com nome contendo 'RH'." Se o assistente listar pipes reais, a conexão está funcionando.
Se a lista vier incompleta, é comportamento esperado: as ferramentas de listagem são paginadas, então o assistente recebe a primeira página e continua pedindo as seguintes conforme precisa. Os dados não foram perdidos, apenas não foram pedidos ainda. Peça de forma mais específica quando quiser um recorte direto.
Passo 4: caminho local no Windows (instalação manual)
No Windows o instalador não roda, então o caminho é manual: você instala o gerenciador uv, baixa o repositório e aponta o Claude Desktop para o executável do uv. A autenticação é por token de acesso pessoal, o que dispensa o fluxo de navegador. São sete etapas curtas.
Este roteiro foi montado e percorrido em uma máquina Windows com o Claude Desktop como cliente. Para outros clientes de IA no Windows, o princípio é o mesmo: apontar o comando para o uv.exe com o parâmetro de diretório.
4.1 Pré-requisitos
- Git para Windows. Baixe em git-scm.com. O que vamos usar é o Git Bash, que é um aplicativo separado incluído no mesmo download, e não o Git comum. Durante a instalação, pode deixar todas as opções padrão marcadas e seguir avançando.
- Claude Desktop. Baixe em claude.ai/download e instale.
- Conta ativa no Pipefy, com membership nos pipes que o assistente vai alcançar.
4.2 Instalar o uv
Confirme que você vai abrir o Git Bash, e não o Git comum. São dois aplicativos diferentes instalados pelo mesmo download, e os comandos deste passo só funcionam no Git Bash. Procure por Git Bash no menu iniciar.
Abra o Git Bash e rode:
curl -LsSf https://astral.sh/uv/install.sh | sh
Feche o Git Bash e abra uma janela nova antes de seguir. A instalação altera variáveis de ambiente, e a janela antiga continua sem reconhecer o comando.
4.3 Baixar o repositório
Na nova janela do Git Bash:
cd ~
git clone https://github.com/pipefy/ai-toolkit.git
cd ai-toolkit
uv sync
O uv sync resolve o Python e as dependências dentro da pasta do projeto, então você não precisa instalar Python separadamente. Como este caminho roda a partir de uma cópia local do repositório, atualizar o servidor significa atualizar essa cópia.
4.4 Gerar um token de acesso pessoal
- No Pipefy, clique na sua foto de perfil, no canto superior direito, e abra Meu Perfil.
- Na seção Token de acesso pessoal, clique em Gerar um novo token.
- Dê um nome que identifique o uso, por exemplo Claude MCP, e copie o token gerado.
Guarde o token em local seguro e não o cole em nenhuma conversa de chat. Ele vai direto para o arquivo de configuração, editado localmente na sua máquina.
4.5 Configurar o Claude Desktop
- Abra o Claude Desktop e clique no ícone de perfil, no canto inferior esquerdo.
- Vá em Configurações e abra a aba Desenvolvedor.
- Clique em Edit Config. O arquivo claude_desktop_config.json abre no seu editor padrão.
Usar o botão Edit Config resolve um problema por conta própria: o caminho do arquivo muda conforme a forma de instalação do app, e por esse botão você nunca precisa descobrir qual é.
Adicione o bloco abaixo, ou substitua o conteúdo por ele:
{
"mcpServers": {
"pipefy": {
"command": "C:\\Users\\SEU_USUARIO\\.local\\bin\\uv.exe",
"args": [
"--directory",
"C:\\Users\\SEU_USUARIO\\ai-toolkit",
"run",
"pipefy-mcp-server"
],
"env": {
"PIPEFY_TOKEN": "SEU_TOKEN"
}
}
}
}
Dois ajustes antes de salvar. Troque os dois campos SEU_USUARIO pelo nome da sua pasta de usuário no Windows: ele aparece duas vezes, no caminho do uv.exe e no caminho da pasta do repositório. Depois troque SEU_TOKEN pelo token do item 4.4.
As barras invertidas são duplas dentro do JSON. Uma barra simples invalida o arquivo, e o Claude Desktop ignora servidores com JSON inválido sem exibir mensagem de erro.
Se ficar em dúvida na formatação, peça ao próprio assistente para revisar a estrutura do JSON. Descreva o formato e omita o token.
4.6 Reiniciar o Claude Desktop
- Feche a janela do Claude Desktop.
- Abra a bandeja do sistema, nos ícones ao lado do relógio, clique com o botão direito no ícone do Claude e escolha Quit.
- Abra o Claude Desktop novamente.
Fechar a janela não encerra o app: ele continua rodando em segundo plano e a configuração nova não é lida. Encerrar pela bandeja é o que faz a diferença.
4.7 Testar
Na caixa de mensagem, confirme que o ícone de ferramentas aparece. Depois peça ao assistente:
"Liste meus pipes do Pipefy" ou "Mostre as informações da minha organização no Pipefy". Se vier dado real da sua conta, a conexão está funcionando.
Erros frequentes e como resolver
| Sintoma | O que fazer |
|---|---|
| macOS: o navegador confirma o login mas a CLI retorna errSecParam (-25244) | O OAuth funcionou; a falha é na etapa final de escrita no keychain. Tente novamente. Se persistir, rode pipefy auth login a partir de uma sessão normal do Terminal e aprove o diálogo do keychain quando ele aparecer. Como alternativa, defina PIPEFY_KEYCHAIN_BACKEND=file. |
| O instalador recusa rodar e menciona root | Por padrão o instalador não roda como root. Rode como usuário comum, sem sudo, ou passe --allow-root se realmente precisar. |
| O instalador para com mensagem sobre sistema não suportado | O instalador oficial cobre macOS e Linux. Em Git Bash ou MSYS no Windows a verificação de sistema falha. No Windows, siga o passo 4 em vez deste. |
| Erro mencionando Git não encontrado | No Windows, o Git é pré-requisito do passo 4, porque o roteiro usa o Git Bash e o git clone. Instale pelo site oficial, feche e reabra o terminal, e tente de novo. Em macOS e Linux, instale pelo gerenciador de pacotes do sistema. |
| Windows: o comando uv não é reconhecido depois de instalar | A janela do Git Bash aberta antes da instalação não reconhece as variáveis de ambiente novas. Feche e abra uma janela nova. |
| Windows: o servidor não aparece e o caminho do uv.exe parece certo | Confira as barras invertidas duplas no JSON e se o nome da pasta de usuário está exato, incluindo pontos, como em nome.sobrenome. Uma barra simples ou um nome de pasta diferente invalidam o caminho sem gerar mensagem. |
| Mensagem sobre python3 não encontrado durante a instalação | O python3 é usado para mesclar o JSON de configuração do cliente. Instale o python3 ou use --client none e configure o arquivo manualmente. |
| command not found depois de instalar | Adicione ~/.local/bin ao PATH do terminal. Feche e reabra o terminal depois do ajuste. |
| Pipefy não aparece no Claude Desktop (Settings > Developer vazio) | Três causas comuns: o caminho no arquivo está errado (refaça o passo crítico do item 3.5); o app foi instalado pela Microsoft Store e o arquivo fica em outra pasta (use "Editar Config" dentro do app); ou o registro automático foi tentado fora do macOS, onde ele não calcula o caminho. |
| Nenhuma mensagem de erro, mas o servidor não aparece | Erro de formatação no JSON: vírgula sobrando, chave faltando ou aspas tipográficas. O Claude Desktop ignora servidores com JSON inválido sem avisar. Valide o arquivo antes de salvar. |
| Funciona no Cursor mas não no Claude Desktop, ou vice-versa | Cada aplicativo tem o próprio arquivo de configuração, e registrar em um não registra no outro. Repita a configuração para o segundo cliente, com --client <nome> ou editando o arquivo dele à mão. |
| A conexão funcionava e parou depois de trocar de método | Provavelmente há dois registros com o nome pipefy. Rode claude mcp remove pipefy -s user e registre apenas um dos caminhos. |
| Erro 401 ou PERMISSION_DENIED ao consultar pipes | Confira as credenciais e, no caso de Service Account, se a conta foi adicionada como membro dos pipes que o assistente precisa alcançar. |
| O assistente diz que a ferramenta não existe | Se você conectou pelo caminho hospedado, ferramentas de escrita não estão disponíveis por design. Siga o passo 3 para a superfície completa. |
Antes de avançar, confirme que você:
- ☐ Escolheu entre o caminho hospedado e o local, e sabe o que cada um habilita
- ☐ É membro dos pipes em que o assistente vai atuar
- ☐ Conectou por apenas um caminho, com um único registro chamado pipefy
- ☐ Autenticou e, no caminho local, confirmou o caminho absoluto do executável (no Windows, o caminho do uv.exe e o da pasta do repositório)
- ☐ Testou com search_pipes e recebeu dados reais do Pipefy
Próximo passo na série
Com a conexão funcionando, veja "Seus primeiros comandos: operando o Pipefy em linguagem natural" para os seis comandos que valem testar primeiro.
