ai-toolkit

<div align="center"> <img src="docs/images/pipefy-developers-banner.png" alt="Pipefy Developers — AI Toolkit (MCP Server, Pipefy CLI, GraphQL SDK, Agent Skills)" width="100%" /> </div> <p align="center"> <a href="https://github.com/pipefy/ai-toolkit/actions/workflows/ci.yml"><img src="https://github.com/pipefy/ai-toolkit/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+" /></a> <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet" alt="uv package manager" /></a> <a href="https://modelcontextprotocol.io/introduction"><img src="https://img.shields.io/badge/MCP-Server-orange" alt="MCP Server" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License" /></a> </p> <p align="center"> <a href="#overview">Overview</a> • <a href="#installation">Installation</a> • <a href="#repository-layout">Repository layout</a> • <a href="#mcp-server">MCP server</a> • <a href="#command-line-interface">CLI</a> • <a href="#agent-skills">Agent skills</a> • <a href="#documentation">Documentation</a> • <a href="#development">Development</a> • <a href="#contributing">Contributing</a> • <a href="#legal">Legal</a> </p>

---

Overview

| Component | Package / path | Purpose | |-----------|----------------|---------| | MCP server | pipefy-mcp-server | Exposes 187 tools to MCP clients (Cursor, Claude Desktop, Claude Code, and others). | | 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

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

• 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 — or want 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 | |---|---|---|---|---|---| | 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 | Cursor / 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. The toolkit also works with Cursor, Claude Desktop, and Codex, but support for non–Claude Code clients is still maturing — expect some rough edges.

Register exactly one MCP server named pipefy — do not mix the hosted HTTP server and a local stdio/plugin server under the same name. First-time setup checklist to hand your agent: skills/onboarding/pipefy-toolkit-setup/SKILL.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.

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 you already have a local/plugin MCP named pipefy, remove it first — claude mcp remove pipefy -s user — since the name must be unique. 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're on Cursor, Claude Desktop, or Codex — or you just want one command that installs the CLI + local MCP server, optionally adds skills, and registers the server in your client config.

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.

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 server registers 187 tools across fourteen domains. Canonical names: PIPEFY_TOOL_NAMES in packages/mcp/src/pipefy_mcp/tools/registry.py.

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 | Tools | Summary | Reference | |--------|:-----:|---------|-----------| | Pipes & cards | 41 | 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 | 17 | Tables, rec