👤 Para times de operações, administradores de pipe e times técnicos
🔐 Disponível para Todos os planos
🎯 Para quem Quer conectar um assistente de IA ao Pipefy ou entender como o MCP funciona
Como conectar o Pipefy ao assistente de IA que a sua equipe já usa, via Model Context Protocol (MCP).
📖 O que você vai entender aqui:
1. O que é o MCP, em uma frase
O MCP (Model Context Protocol) é um protocolo aberto, criado pela Anthropic, que permite que assistentes de IA se conectem a sistemas externos e executem ações reais dentro deles. No Pipefy, o MCP não é um produto separado nem um add-on: é um habilitador da própria plataforma.
Na prática, o MCP permite que o assistente de IA que a sua equipe já usa no dia a dia (Claude, Cursor, Codex, entre outros) converse diretamente com o Pipefy (consultando pipes, cards e relatórios, e, dependendo da configuração, executando ações dentro do processo).
Pense no MCP Server como um "secretário" dentro do seu assistente de IA: ele faz exatamente o que você poderia fazer manualmente na tela do Pipefy, só que a partir de um comando em linguagem natural.
3. Pré-requisitos
Duas formas de conectar: Existe um caminho hospedado, sem nenhuma instalação, que habilita apenas consultas (ler pipes, cards, relatórios). E existe o caminho local (coberto neste guia), que instala o servidor na sua máquina a partir do repositório oficial no GitHub e habilita a superfície completa: consultar e também executar ações (criar/mover cards, criar AI Agents, criar pipes).
| Pré-requisito | Detalhe |
| Assistente de IA compatível com MCP | Claude Desktop, Claude Code, Cursor ou Codex. É necessário ter um agente que interprete as instruções e tome as decisões. |
| Conta Pipefy com acesso à API | Token de acesso pessoal, gerado em Meu Perfil → Token de acesso pessoal. Para uso corporativo/automatizado, uma Service Account provisionada por um Super Admin. |
| Git | Necessário no caminho de instalação via repositório. No Windows, use o Git Bash (instalado junto com o Git para Windows). |
| Python e uv | O servidor MCP é um pacote Python. O gerenciador de pacotes recomendado é o uv, que resolve o Python automaticamente (não é necessário instalar Python à parte). |
4. Instalação passo a passo
A instalação do MCP Server é feita a partir do repositório oficial e open source pipefy/ai-toolkit, disponível no GitHub. O passo a passo abaixo usa o Claude Desktop como exemplo; o princípio é o mesmo para outros clientes compatíveis com MCP.
4.1 Baixar e instalar
Acesse o repositório oficial: github.com/pipefy/ai-toolkit.
Use o instalador oficial (recomendado): rode o script de instalação do repositório no terminal, apontando para o seu cliente de IA (por exemplo, Claude Desktop ou Cursor). O gerenciador uv resolve as dependências automaticamente.
Alternativa manual: acesse o repositório, faça o download do código ("Code → Download ZIP"), extraia e siga as instruções do arquivo README. Essa alternativa é útil se você não usa Git ou tem restrição de rede.
Confirme que o executável pipefy-mcp-server foi instalado na sua máquina antes de seguir para a configuração.
No Windows: O instalador automático cobre macOS e Linux. No Windows, o caminho é instalar o gerenciador uv pelo Git Bash, clonar o repositório manualmente (git clone) e apontar o Claude Desktop para o executável do uv (o guia completo de instalação detalha esse roteiro específico para Windows).
4.2 Gerar o seu token de acesso pessoal
No Pipefy, clique na sua foto de perfil (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 (ex.: "Claude MCP") e copie o token gerado.
Importante: Guarde o token em local seguro. Ele não é exibido de novo depois de gerado, e nunca deve ser colado em conversas de chat, prints ou documentos compartilhados (ele vai direto para o arquivo de configuração, editado localmente na sua máquina).
4.3 Configurar o seu assistente de IA
O arquivo de configuração do cliente de IA precisa apontar para o caminho absoluto do executável instalado, mais o seu token de acesso. Esse caminho varia de máquina para máquina (não reutilize o caminho de outra pessoa).
Estrutura básica do bloco a adicionar (Claude Desktop, com token de acesso pessoal):
{
"mcpServers": {
"pipefy": {
"command": "/caminho/absoluto/para/pipefy-mcp-server",
"env": {
"PIPEFY_TOKEN": "SEU_TOKEN"
}
}
}
}
| Cliente | Onde fica o arquivo de configuração |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\\Claude\\claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json (macOS/Linux) ou %USERPROFILE%\\.cursor\\mcp.json (Windows) |
| Codex | ~/.codex/config.toml |
Atenção ao salvar: Salve como JSON puro, sem aspas "inteligentes" e sem vírgulas extras. Um JSON mal formatado faz o cliente de IA ignorar o servidor silenciosamente, sem exibir mensagem de erro. No Windows, use barras invertidas duplas nos caminhos.
4.4 Reiniciar o assistente de IA
Feche o aplicativo completamente (apenas fechar a janela não é suficiente, pois ele continua rodando em segundo plano). No macOS, use Cmd+Q; no Windows, saia pelo ícone na bandeja do sistema (perto do relógio). Depois, reabra o aplicativo.
5. Testando a conexão
Abra uma conversa nova no seu assistente de IA.
Confirme que o Pipefy aparece na lista de ferramentas/conectores disponíveis (no Claude Desktop: ícone + na caixa de mensagem → Connectors, ou Configurações → Developer → Local MCP Servers).
Peça algo simples, como "liste minhas organizações no Pipefy" ou "quais pipes existem na organização X".
Sinal de que funcionou: Se o assistente retornar organizações, pipes ou cards reais da sua conta, a conexão está funcionando. Se os dados vierem truncados ou incompletos, isso é esperado (é uma proteção para não sobrecarregar a IA com volumes muito grandes). Peça informações mais específicas (por organização ou por pipe) para obter um recorte direto.
6. Erros comuns e como resolver
| Sintoma | O que fazer |
| "Git não encontrado" durante a instalação | O Git não está instalado. Instale pelo site oficial (git-scm.com) ou pelo gerenciador de pacotes do seu sistema, feche e reabra o terminal, e tente novamente. |
| O Pipefy não aparece no assistente após configurar | Duas causas comuns: (1) o caminho do executável no arquivo de configuração está errado (refaça a busca pelo caminho na sua máquina); (2) o Claude foi instalado pela Windows Store, que usa outro arquivo de configuração (use a opção "Editar Config" dentro do app). |
| Erro de login/autenticação em computador corporativo | Redes corporativas costumam bloquear fluxos de autenticação automática. Use o Token de acesso pessoal diretamente no arquivo de configuração (esse método não depende do navegador). |
| Nenhum erro aparece, mas a ferramenta também não aparece | Provável erro de formatação no arquivo JSON (vírgula extra, aspas erradas). Valide o conteúdo em um validador de JSON online antes de salvar. |
| Dados retornam truncados ou incompletos | Comportamento esperado (proteção de contexto contra volumes grandes). Peça um recorte mais específico (uma organização ou um pipe por vez). |
7. Perguntas frequentes
O MCP tem autonomia para alterar o meu ambiente Pipefy sozinho?
Não sem a sua aprovação. O MCP analisa o ambiente e pode sugerir ou até propor a construção de automações, fluxos e agentes, mas sempre mostra antes o que pretende fazer e pede confirmação explícita. Nenhuma ação é executada silenciosamente.
É possível automatizar um processo inteiro, de ponta a ponta, e não só tarefas isoladas?
Sim. É possível configurar múltiplos AI Agents e conexões MCP no mesmo pipe, com gatilhos e regras por fase, para orquestrar o fluxo completo (em vez de automações isoladas).
Qual é o risco de a IA alterar um fluxo que já funciona corretamente?
A principal proteção é que a IA nunca executa uma ação sem mostrar antes o que pretende fazer e pedir confirmação. Como é uma tecnologia probabilística, o risco não é absolutamente zero, mas como o modelo sempre anuncia a ação antes de executá-la, a chance de agir de forma diferente do anunciado é baixa. Ainda assim, a recomendação é testar e homologar mudanças em pipes clonados antes de aplicar em produção (especialmente porque algumas alterações, como excluir uma automação, não podem ser desfeitas automaticamente).
Como funciona o controle de permissões e acesso às informações?
O MCP herda exatamente o mesmo nível de permissão da pessoa (ou do token) que está executando. Se o seu usuário não tem acesso de admin ou não é membro de um determinado pipe, o MCP também não terá esse acesso. Como a conexão depende de um token de acesso pessoal gerado no perfil de cada usuário, é possível liberar o uso apenas para pessoas específicas dentro da sua equipe, mesmo que todas tenham acesso ao mesmo pipe pela interface.
As ações realizadas pelo MCP ficam registradas para auditoria?
Sim. Todas as operações realizadas via MCP Server ficam registradas no histórico de acesso da conta do usuário que executou a ação (o mesmo local onde qualquer outra ação daquele usuário apareceria).
É obrigatório ter uma ferramenta de IA para usar o MCP?
Sim. É pré-requisito ter um cliente de IA compatível com o protocolo MCP (Claude Desktop, Claude Code, Cursor, Codex, entre outros) onde as instruções sejam interpretadas e as decisões, tomadas.
Como o consumo é contabilizado?
Depende da direção do fluxo. Quando uma IA externa consulta ou altera o Pipefy através do MCP Server, cada chamada consome uma API Call, dentro da franquia de chamadas de API já contratada. Quando um AI Agent do Pipefy acessa uma ferramenta externa através do MCP Client, cada chamada consome um crédito de IA. Para uma estimativa de consumo aplicada ao seu volume de uso, o seu time de conta no Pipefy pode ajudar a detalhar os números.
Existe uma versão hospedada, que não exige instalação?
Sim (para consultas, apenas leitura). Ela conecta o seu assistente de IA ao servidor hospedado do Pipefy em poucos comandos, sem instalar nada na sua máquina. Ações de escrita (criar ou mover cards, criar AI Agents, criar pipes) ainda dependem do caminho local coberto neste guia.
Se eu trocar de máquina, preciso instalar tudo de novo?
No caminho local, sim (o servidor MCP roda como um processo na própria máquina, então trocar de computador exige repetir a instalação na máquina nova). Isso não é necessário no caminho hospedado.
