Servidor MCP de actions do Pipefy iPaaS

Este serviço expõe as actions das conexões já existentes no Pipefy iPaaS como tools MCP diretas. O upstream real é:

https://ipaas.pipefy.com/mcp

Quando o Pipefy Agent chama tools/list, o servidor:

1. usa a sessão autenticada do pipefy CLI para obter um token iPaaS temporário;
2. lista somente as conexões ativas do pipe configurado;
3. descobre todas as actions de cada conexão;
4. resolve o schema de entrada de cada action usando a respectiva conexão;
5. retorna uma tool separada para cada combinação conexão + action.

Exemplo de tool materializada:

conn_google_calendar_self__create_event__8f42d3a921

O título exibido é semelhante a Google Calendar Self — Create Event. A conexão fica vinculada internamente à tool: o agente fornece somente os campos da action e não pode trocar o connectionExternalId.

As tools genéricas do Activepieces, como ap_list_connections, ap_research_pieces e ap_run_action, não são expostas ao Pipefy Agent. Ao chamar uma tool materializada, o servidor a traduz internamente para uma execução única de ap_run_action. Nenhum flow é criado ou salvo.

Executar localmente

1. Autentique o CLI no host com pipefy auth login.
2. Garanta que uv esteja no PATH e que PIPEFY_TOOLKIT_DIR aponte para o checkout do Pipefy Toolkit.
3. Copie .env.example para .env, escolha o pipe em PIPEFY_IPAAS_PIPE_ID e crie um valor longo e aleatório para PROXY_MCP_TOKEN. No Windows, mantenha PIPEFY_KEYCHAIN_BACKEND=file para usar a sessão já autenticada pelo CLI.
4. Inicie o servidor:

npm run start

O health check é GET /healthz. O endpoint MCP local é:

http://localhost:8080/mcp

Configuração no Pipefy Agent

Cadastre o endpoint MCP e passe o token do proxy no header:

{
  "url": "http://localhost:8080/mcp",
  "headers": {
    "Authorization": "Bearer <PROXY_MCP_TOKEN>"
  }
}

Ao mapear o servidor, o Pipefy verá diretamente as actions agrupadas pelo nome da conexão. Se conexões ou actions mudarem, refaça o mapeamento para atualizar a seleção disponível ao usuário.

Configuração

• PIPEFY_IPAAS_PIPE_ID: pipe que define o workspace iPaaS e suas conexões.
• PIPEFY_TOOLKIT_DIR: checkout local do Pipefy Toolkit, onde a sessão do CLI está autenticada.
• PROXY_MCP_TOKEN: única credencial enviada pelo cliente ao servidor.
• PIPEFY_MCP_URL: opcional; por padrão, https://ipaas.pipefy.com/mcp.
• CATALOG_CONCURRENCY: opcional; quantidade de schemas resolvidos em paralelo, padrão 4.
• CATALOG_TTL_SECONDS: opcional; tempo do catálogo em memória usado para reconhecer chamadas, padrão 300. Cada tools/list sempre faz uma descoberta nova.

O usuário não fornece token do Pipefy no .env. O servidor obtém credenciais temporárias a partir da sessão autenticada do CLI e nunca as retorna ao cliente ou grava em arquivo.

Hospedagem

Este modo deve rodar no mesmo host em que pipefy auth login foi concluído. Para uma hospedagem remota ou multiusuário, use uma identidade própria de serviço e um modelo de autorização por requisição; não compartilhe a sessão pessoal de um desenvolvedor.

Em produção, publique /mcp com HTTPS, mantenha PROXY_MCP_TOKEN obrigatório e nunca exponha credenciais do Pipefy em configuração, logs ou respostas.