Pipefy MCP server, CLI, and agent skills

Overview • Installation • Repository layout • MCP server • CLI • Agent skills • Documentation • Development • Contributing • Legal

---

Overview

Component	Package / path	Purpose
MCP server	pipefy-mcp-server	Exposes the full local catalog to MCP clients (Cursor, Claude Desktop, Claude Code, and others). The hosted URL that the Cursor Marketplace plugin and Hosted MCP use serves the remote-safe floor instead; see MCP server.
CLI	pipefy-cli	Terminal commands aligned with MCP capabilities; see docs/parity.md.
SDK	pipefy	Vendor GraphQL client, services, and models shared by MCP and CLI.
Skills	skills/	Markdown playbooks (Anthropic Skills format) for common Pipefy workflows.

Feedback and issues: GitHub Issues · dev@pipefy.com

---

Installation

Six ways to use the toolkit — pick one based on your client and whether you need the full tool set:

• In Cursor and want the fastest start with no local setup? → Cursor Marketplace plugin.
• In Claude Code and want the fastest start with no local setup? → Hosted MCP.
• In Claude Code and want the CLI, /pipefy:* slash commands, or the few local-only tools? → Claude Code plugin.
• On Cursor, Claude Desktop, or Codex and need the local-file tools, the CLI, or one command for everything? → Quick-install script.
• Terminal, scripting, or CI, with no agent? → CLI only.
• Just want the workflow playbooks in any agent? → Skills only.

Install path	MCP server runs on	Tools available	Auth	Also installs	Best for
Cursor Marketplace plugin	Pipefy cloud (HTTPS)	Remote-safe surface; local-file tools withheld	In-client OAuth	skills	Fastest start in Cursor; zero local Python
Hosted MCP	Pipefy cloud (HTTPS)	Remote-safe surface: all but the few local-file tools	In-client OAuth	nothing else	Fastest start in Claude Code; zero local Python
Claude Code plugin	Your machine (uvx stdio)	Full tool surface	pipefy CLI OAuth	slash commands + skills + CLI	Claude Code users who want the CLI, slash commands & the local-only tools
Quick-install script	Your machine (stdio)	Full tool surface	pipefy auth login	CLI + skills, wired into your client config	Local-file tools, CLI, Claude Desktop / Codex, or one-command full setup
CLI only	— (no MCP)	CLI commands (parity)	login or service account	—	Terminal use, scripting, CI
Skills only	—	—	—	markdown playbooks	Adding playbooks to any agent

Claude Code is the recommended client and the most complete, best-tested path today. In Cursor, prefer the Marketplace plugin over the Quick-install script unless you need the local-file tools or the CLI. The Marketplace listing tracks main. Contributors can always load a checkout as a local plugin (section 6). Claude Desktop and Codex still use the script.

Register exactly one Pipefy MCP server — do not mix the hosted HTTP server with a local stdio or plugin server, whatever they are named. To check a machine, including one this repository never installed for you:

curl -LsSf https://raw.githubusercontent.com/pipefy/ai-toolkit/main/uninstall.sh | sh -s -- --scan

That reports every registration and how each one is reached. It removes nothing, edits nothing, and exits 0 when it finds nothing, 1 when findings remain, 2 when a source could not be inspected. A registration is matched on what it runs — the pipefy-mcp-server command, a known runner invoking it, or the host mcp.pipefy.com — so one registered under any other name is still found. First-time setup checklist to hand your agent: skills/onboarding/pipefy-toolkit-setup/SKILL.md. Removing a path, or moving between them: Uninstalling and docs/uninstall.md.

Too many tools for your client? The local paths can expose a subset instead of the whole catalog — by subject domain, by persona profile, or as four catalog meta-tools the agent searches on demand. See Choosing a tool surface. That selection (PIPEFY_MCP_TOOLSETS) applies to the local stdio path only. Any client on the hosted URL always receives the remote-safe floor.

Authentication (for the local paths; the hosted server uses its own in-client OAuth):

• Human OAuth (interactive): pipefy auth login runs the browser flow and stores a session in your OS keychain. Pipe access is whatever the signed-in user already has.
• Service account (unattended / CI): provision one in Pipefy Admin (Admin → Service Accounts), add it to every pipe the tools should touch, and set PIPEFY_SERVICE_ACCOUNT_CLIENT_ID / PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET.

Full env-var reference and config.toml precedence: docs/config.md.

Pre-1.0 note: builds ship as pre-releases to PyPI on every tag (uvx and uv tool install resolve them automatically; the stable default lands at v1.0). Current line: v0.3.0-beta.* (latest tag). Installing pipefy-cli pulls pipefy and pipefy-auth transitively. To pin a version use the PEP 440 form pipefy-cli==0.3.0b1; do not pass a global --prerelease allow (it lets transitive deps jump to their own pre-releases and can pull a broken build).

1. Hosted MCP (Claude Code)

Pick this when: you're in Claude Code and want the fastest start with zero local Python. The server runs on Pipefy's infrastructure and exposes the remote-safe surface: reads, create / update / delete, and the raw GraphQL escape hatch — everything your own API permissions allow. Withheld are only the tools whose input is a file on your machine (knowledge-base document upload, custom LLM-provider credential files); attachment uploads still work from a URL or a presigned upload target instead of a local path.

claude mcp add --transport http --scope user --client-id pipefy-mcp pipefy https://mcp.pipefy.com/mcp

Complete the browser login when prompted (claude mcp login pipefy if the client reports Needs authentication). If a local or plugin Pipefy MCP server is already registered, remove it first — under whatever name it carries, since a second registration shadows this one and a plugin-provided server ranks below user scope. ./uninstall.sh --scan names them; the switch is in docs/uninstall.md. Need the CLI and slash commands too? Use the Claude Code plugin instead. Hand-wired local stdio: packages/mcp/README.md.

2. Claude Code plugin

Pick this when: you're in Claude Code and want the full local surface — every tool (including the local-file ones the hosted server withholds), the /pipefy:* slash commands, and the skill catalog. The MCP server runs locally via uvx.

/plugin marketplace add pipefy/ai-toolkit
/plugin install pipefy
/pipefy:install
/pipefy:pipefy-login

Type the slash commands in order (the model cannot invoke /plugin … for you). /plugin install pipefy registers the local MCP server plus the /pipefy:install and /pipefy:pipefy-login commands; /pipefy:install runs uv tool install once to put pipefy on PATH (idempotent); /pipefy:pipefy-login runs the OAuth browser flow. Hand-wired setups, the macOS errSecInvalidOwnerEdit keychain note, and the contributor local-clone alternative: packages/mcp/README.md. To run a local branch as the plugin, see Test the plugin from a local checkout.

3. Quick-install script

Pick this when: you need the local-file tools or the CLI, or you're on Claude Desktop or Codex — one command installs the CLI + local MCP server, optionally adds skills, and registers the server in your client config. In Cursor, prefer the Marketplace plugin unless you need that local surface.

curl -fsSL https://raw.githubusercontent.com/pipefy/ai-toolkit/main/install.sh \
  | sh -s -- --client cursor

Replace --client cursor with one of claude-code, claude-desktop, codex, or none (prints the snippet to paste). Useful flags: --yes (skip prompts), --no-skills (skip npx skills add), --version vX.Y.Z (pin a Release), --dry-run (print commands without executing), --allow-root (opt-in; refused by default). After install, run pipefy auth login (--device on headless systems). The installer puts pipefy-mcp-server on PATH, so each client's config collapses to {"command": "pipefy-mcp-server"}.

Production / shared environments: pin an explicit release with --version vX.Y.Z (and prefer fetching install.sh from that same Release tag, not the floating main branch). Untagged/@latest-style installs are fine for local experiments; they are not the default practice for reproducible or corporate rollouts.

4. CLI only

Pick this when: you want terminal commands, scripting, or CI — no agent or MCP.

uvx --from pipefy-cli pipefy --help        # ad-hoc, no install

uv tool install pipefy-cli                 # permanent install
pipefy --install-completion bash           # or zsh, fish
pipefy auth login                          # browser OAuth, session in OS keychain

CLI deep-dives (auth precedence, --token / PIPEFY_TOKEN, parity matrix): packages/cli/README.md and docs/cli/.

5. Skills only

Pick this when: you just want the workflow playbooks in any Markdown-aware agent (Cursor, Claude Code, Codex, and others).

npx skills add pipefy/ai-toolkit                           # all skills
npx skills add pipefy/ai-toolkit --skill pipefy-pipes-and-cards

Catalog and authoring guide: skills/README.md.

6. Cursor Marketplace plugin

Pick this when: you're in Cursor and want the hosted MCP server with browser sign-in and no local Python. The plugin ships the skill catalog and points Cursor at https://mcp.pipefy.com/mcp. Cursor runs the OAuth flow. The surface is the hosted deployment's remote-safe floor. Withheld are the tools whose input is a file on your machine; attachment uploads still work from a URL or a presigned upload target. Toolset selection (PIPEFY_MCP_TOOLSETS) does not apply to the hosted URL — use the Quick-install script when you need that, or the local-file tools.

Install Pipefy from the Cursor Marketplace (the listing tracks main). Complete the browser sign-in when Cursor prompts, then fully restart Cursor before the first tool call. No uv, no CLI, no token paste. This path has no /install or /pipefy-login commands (those files belong to the Claude Code plugin, where they surface namespaced as /pipefy:install and /pipefy:pipefy-login). Skills may appear in the slash palette as /pipefy-*.

This path and any user-config Pipefy MCP entry (including one written by install.sh --client cursor) both occupy Cursor's MCP list. They are mutually exclusive — the same rule as mixing hosted HTTP with local stdio. The registration key is free text: delete the matching key from ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json) and keep the Marketplace plugin. ./uninstall.sh --scan prints the name it found; the switch is in docs/uninstall.md.

To load this checkout as a local plugin (contributors): Cursor rejects a symlink whose target is outside ~/.cursor/plugins/local (it logs loadUserLocalPlugin pipefy rejected). Copy the plugin files into that directory as a real folder, then fully restart Cursor. If ~/.cursor/plugins/local/pipefy is already a symlink to this checkout, rm the link first - that does not delete the repo. Copying commands/ is optional: the Cursor manifest declares "commands": [], so neither a local copy nor a Marketplace tarball of this repo surfaces /install or /pipefy-login. Include it if you want the copy to match what ships.

dest="$HOME/.cursor/plugins/local/pipefy"
if [ -L "$dest" ]; then rm "$dest"; fi
mkdir -p "$dest/assets"
cp -R .cursor-plugin skills LICENSE NOTICE README.md mcp.json "$dest/"
cp assets/logo.svg "$dest/assets/"

Remove a copy with rm -rf ~/.cursor/plugins/local/pipefy. Remove only a leftover symlink with rm ~/.cursor/plugins/local/pipefy.

Uninstalling, and switching between paths

uninstall.sh sits beside install.sh and reverses the script, CLI, hosted-user-config, and Claude Code plugin paths, including one this repository never installed for you. It does not uninstall the Cursor Marketplace plugin (that lives in Cursor's plugin UI). --scan still reports a competing ~/.cursor/mcp.json registration if one exists (including install.sh --client cursor).

# Report only: what is on this machine, across every channel and client.
curl -LsSf https://raw.githubusercontent.com/pipefy/ai-toolkit/main/uninstall.sh | sh -s -- --scan

# Then remove what you approve. Approval is asked in three tiers.
curl -LsSf https://raw.githubusercontent.com/pipefy/ai-toolkit/main/uninstall.sh | sh

--scan changes nothing and exits 0 clean / 1 findings remain / 2 a source could not be inspected. A registration is matched on what it runs — the pipefy-mcp-server command, a known runner invoking it, or the host mcp.pipefy.com — so an entry registered under any other name is still found, and removed under that name. Useful flags: --dry-run, --yes, --keep-credentials, --keep-config, --client <id>.

Switching paths is remove-then-add: register exactly one Pipefy MCP server at a time, since a plugin-provided server ranks below user scope and a leftover entry silently wins. Full teardown reference, the per-channel switching recipes, and what is never removed by design: docs/uninstall.md.

Post-1.0 (PyPI, preview)

Once the stable line lands, the MCP server and CLI resolve straight from PyPI by name:

uvx pipefy-mcp-server
uv tool install pipefy-cli

Deprecation and semver (post-1.0): docs/DEPRECATION.md.

---

Repository layout

uv workspace with three Python packages and a skills catalog. pipefy is the vendor GraphQL layer; MCP and CLI depend on it and do not import each other.

Path	Distribution	Role
packages/sdk/	pipefy	GraphQL transport, services, queries, Pydantic models. Package README
packages/mcp/	pipefy-mcp-server	MCP tool registration and server lifecycle. Package README
packages/cli/	pipefy-cli	Typer CLI (pipefy command). Package README
skills/	—	Agent skill playbooks. Catalog

---

MCP server

The local server registers the full catalog. Canonical names: PIPEFY_TOOL_NAMES in packages/mcp/src/pipefy_mcp/tools/registry.py. The hosted URL (Marketplace plugin and Hosted MCP) serves the remote-safe floor instead: it withholds the tools whose input is a file on your machine.

Tool descriptions and Args: blocks come from Python docstrings (what MCP clients show to models). Per-area reference docs cover parameters, edge cases, and cross-cutting behavior.

Shared conventions (pagination, IDs, permissions, error shape): docs/mcp/tools/cross-cutting.md.

Domain	Summary	Reference
Pipes & cards	Pipes, phases, fields, labels, cards, field conditions, attachments. Phase inventory (get_phase_cards, get_phase_cards_count), move discovery (get_phase_allowed_move_targets), and create_card(phase_id=…) reduce raw GraphQL for agent seeding.	docs
Database tables	Tables, records, schema, table-record attachments.	docs
Relations	Pipe and card relations.	docs
Reports	Pipe and organization reports, async exports.	docs
Automations & AI	Automations, AI automations, AI agents, validators.	docs
LLM providers	Discovery reads (custom + Pipefy-managed providers, vendor model lists, owner defaults, dependencies, read-access probe) plus custom-provider writes: create/update/delete, active-status toggle, and organization default set/reset.	docs
Knowledge bases	Pipe-scoped AI knowledge bases: list all items, plain text / document (one-shot PDF upload) / data lookup CRUD, and a read-access probe. Attach sources to agents/behaviors via dataSourceIds.	docs
iPaaS	Lazy discovery, invocation, and app-connection setup for a pipe's iPaaS (Advanced Automations) workspace (get_ipaas_tools, call_ipaas_tool, plus the connection meta-tools).	docs
Observability	Logs, usage, credits, execution metrics, job exports.	docs
Members, email & webhooks	Membership, inbox email, webhooks.	docs
Service accounts	Create and delete organization service accounts (OAuth2 machine identities); attach them to pipes with add_service_account_to_pipe.	docs
Organization	Organization metadata and discovery.	docs
Portals	Portal read/CRUD, pages, elements, sub-portals (publish/unpublish).	docs
Introspection	Schema discovery and raw GraphQL.	docs

Choosing a tool surface

Not every client wants every tool. Three independent controls decide what tools/list returns:

Control	Set with	Effect
Launch profile	--profile local / remote	The security floor. local registers every tool; remote serves only the remote-safe surface and validates an inbound bearer per request.
Toolset selection	--toolsets / PIPEFY_MCP_TOOLSETS	Narrows within that floor — by subject domain (workflow, database, interfaces, automation, intelligence, analytics, governance, integration) or by persona profile (requester, operator, manager, builder, admin, auditor), unioned. Selection never widens past the floor.
Power discovery	--toolsets power	Replaces the curated tools with four catalog meta-tools (get_tool_categories, search_tools, describe_tool, execute_tool) plus the raw-GraphQL tools, so the working set stays small no matter how large the catalog grows.

The toolset names are a different grouping from the table above: that table is organized by documentation area (the reference docs you read), while subject domains partition tools by the job they serve — card relations land in workflow, table relations in database. Passing an unrecognized name is a startup error that prints the full list of valid ones. --toolsets / PIPEFY_MCP_TOOLSETS is a process-level switch: it applies to the local stdio server only, not to the hosted URL.

Per-name definitions and precedence: docs/config.md. Taxonomy rationale (why subject domains, why personas overlap): packages/mcp/AGENTS.md.

---

Command-line interface

The pipefy CLI mirrors shipped MCP capabilities where parity is defined in docs/parity.md. Conventions: Rich output by default, --json for scripts, --yes on destructive commands.

pipefy pipe list --json
pipefy card get 123456789
pipefy introspect query --name getPipe

CLI-specific guides: docs/cli/ (including introspect-then-execute).

---

Agent skills

The skills/ directory holds workflow playbooks: prerequisites, tool tables (MCP + CLI), steps, and success criteria. Compatible with any agent that reads Markdown (Cursor, Claude Code, Codex, and others). Distribution is via skills.sh (55+ agent targets); install commands are under Installation above.

Full catalog: skills/README.md. Authoring: skills/AGENTS.md. Contributions: CONTRIBUTING.md.

Card & phase agent ergonomics: use skills/pipes-and-cards/pipefy-pipes-and-cards/SKILL.md (workflow Seed pipe across phases; prefer dedicated tools over execute_graphql).

---

Documentation

Document	Description
docs/README.md	Index by surface (MCP, CLI, SDK).
docs/config.md	PIPEFY_* environment variables, config.toml schema and path, precedence chain.
docs/parity.md	MCP tool ↔ CLI command matrix.
docs/MIGRATION.md	Notes for existing MCP users.
AGENTS.md	Repository guidelines for contributors and agents.
RELEASE.md	Versioning and release process.

---

Development

Install uv if you don't have it, then from the repository root:

uv sync
[[ -f .env ]] || cp .env.example .env   # first-time setup; then fill in PIPEFY_SERVICE_ACCOUNT_*
uv run pytest -m "not integration"    # unit tests (no live API)
uv run pytest -m integration -v     # live API (requires PIPEFY_*)
uv run ruff chec