pipefy-toolkit-setup

Imported from pipefy/ai-toolkit (skills/onboarding/pipefy-toolkit-setup/SKILL.md). Install upstream with npx skills add pipefy/ai-toolkit --skill pipefy-toolkit-setup. Copyright stays with the author.

Pipefy toolkit setup (first-time onboarding)

Canonical install snippets live only in the root README.md#installation — there is no second copy of the commands. This skill is the agent checklist — print or run the README blocks verbatim; do not invent alternate commands. The Cursor Marketplace plugin is the exception: it installs from Cursor's plugin UI, so there is no command to print or run.

Edge cases: packages/mcp/README.md. Auth: docs/cli/auth.md. Env: docs/config.md.

When to use

• "Set up Pipefy", "install the MCP", "connect Claude/Cursor to Pipefy"
• User mentions the Cursor Marketplace plugin, /plugin marketplace add, /pipefy:install, or mcp.pipefy.com
• Fresh machine with no pipefy on PATH and no Pipefy MCP server

Do not use once tools already work — switch to a domain skill (pipes, tables, …).

Prerequisites

• User has a Pipefy account (Admin access if they need a service account).
• Cursor Marketplace plugin: Cursor, nothing local.
• Hosted MCP: Claude Code CLI (claude).
• Local toolkit: a shell that can run curl (install.sh can install uv).

Who does what

Tools needed

Setup is outside the Pipefy MCP tool surface. After auth succeeds, verify with:

Steps

1. Choose one path — ask the user; do not pick silently.

   If they only say “Claude Code” (no path), ask a closed question:

   Hosted MCP (zero local Python, mcp.pipefy.com) or the Claude Code plugin (slash commands + local CLI)? If you’re unsure, Hosted is the usual first try.

   If they only say “Cursor” (no path), ask a closed question:

   Cursor Marketplace plugin (hosted server, browser sign-in, no local Python) or the Quick-install script (local CLI, plus the tools that read local files)? If you’re unsure, the plugin is the usual first try.

   Path	README section	Outcome
   Cursor Marketplace plugin	Cursor Marketplace plugin	Hosted mcp.pipefy.com, browser sign-in, no local Python
   Hosted MCP	Hosted MCP	HTTPS mcp.pipefy.com (remote-safe tools)
   Local toolkit	Quick install	install.sh → local server + CLI, including the tools that read local files
   Claude Code plugin	Claude Code plugin	Marketplace + slash install/login
   CLI only	CLI	pipefy on PATH; no MCP

   Never register both a hosted HTTP and a local stdio/plugin Pipefy server, whatever they are named: a second registration shadows the one you meant to use. Switching between paths is remove-then-add — docs/uninstall.md. On Cursor that applies to the Marketplace plugin and any entry in ~/.cursor/mcp.json, including one written by install.sh --client cursor.

2. Execute the chosen README block — run it in the shell, or print it for the user to paste (required for Claude slash commands). Do not reorder the plugin sequence: marketplace → /plugin install pipefy → /pipefy:install → /pipefy:pipefy-login.

   Cursor Marketplace plugin: the user installs Pipefy from Cursor's plugin UI and fully restarts Cursor. Nothing to run, and the /pipefy:… commands do not exist on this path.

3. Auth — Cursor plugin: finish Cursor's own sign-in prompt (Customize / MCP). Hosted: finish the client browser OAuth prompt (claude mcp login <name> if status is Needs authentication). Local/plugin/CLI: pipefy auth login or /pipefy:pipefy-login (see README). Service accounts: docs/config.md.

4. Verify

   • Shell (local / plugin / CLI): pipefy --version. The Cursor plugin installs no CLI, so verify it with the MCP call below instead.
   • MCP: call list_organizations (needs no id — the natural first read; confirms the credential works and surfaces the org ids other tools need) or another read-only tool the user allows
   • Run curl -LsSf https://raw.githubusercontent.com/pipefy/ai-toolkit/main/uninstall.sh | sh -s -- --scan (reports only, removes nothing; ./uninstall.sh --scan from a checkout does the same) and confirm it reports exactly one registration, for the path you chose. A Marketplace-only install writes nothing to ~/.cursor/mcp.json, so the plugin is not a finding: on that path the scan should report none. It matches on what an entry runs — the pipefy-mcp-server command, a known runner invoking it, or the host mcp.pipefy.com — so a server registered under any other name is still found. Exit 0 nothing found, 1 findings remain, 2 a source could not be inspected.

Success criteria

• The --scan above reports one registration, for the chosen path (none for the Cursor plugin, which it cannot see; nothing for CLI-only).
• Auth completed.
• Read-only MCP call or pipefy --version succeeds.

Failure modes

See also

• README.md#installation
• docs/uninstall.md — uninstall.sh --scan, teardown, and switching between hosted, local, and plugin
• skills/README.md