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. monta imediatamente os schemas básicos, sem aguardar dropdowns autenticados;

5. retorna uma tool separada para cada combinação conexão + action;

6. em background, enriquece dropdowns e campos dinâmicos usando a conexão vinculada e guarda esses schemas em cache local.

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

Related MCP server: Composio MCP Server

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.

Na primeira descoberta, campos dinâmicos podem aparecer sem uma lista completa de opções. O enriquecimento continua em background; depois de concluído, um novo mapeamento reutiliza os schemas enriquecidos persistidos e inclui as opções resolvidas sem colocá-las no caminho crítico da requisição.

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 básicos 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.

• ENRICHMENT_CONCURRENCY: opcional; quantidade de schemas autenticados enriquecidos em paralelo, padrão 4.

• ENRICHED_SCHEMA_TTL_SECONDS: opcional; validade dos schemas enriquecidos persistidos, padrão 86400 (24 horas).

• SCHEMA_CACHE_PATH: opcional; arquivo do cache local, padrão .cache/ipaas-schema-cache.json.

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.

O cache persiste somente metadados de schema, incluindo possíveis nomes e IDs de opções pertencentes às conexões. Ele não contém tokens nem argumentos usados em actions, fica ignorado pelo Git e pelo Docker e deve permanecer protegido no host do serviço.

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.