How to set up the Pipefy AI Toolkit in your AI Assistant

Your Pipefy processes can now be triggered directly from the AI assistant you already use every day. Instead of opening the app to create a card, move a stage, or pull a report, you type what you need and the assistant takes care of it.

By the end of this article, you'll know how to install and configure the Pipefy AI Toolkit on your computer and connect it to your preferred AI assistant, ready to operate Pipefy in natural language.

📖  What you'll learn here:

What is the Pipefy AI Toolkit

The Pipefy AI Toolkit is an open source package that connects Pipefy to AI assistants compatible with the MCP (Model Context Protocol). It has three components:

The toolkit works with Cursor, Claude Desktop, Claude Code, Codex, and any other MCP-compatible client.

What you need before you start

Pipefy account and permissions

You need admin access on the pipes where the assistant will operate. If you plan to use a service account (recommended for keeping the MCP always connected without relying on a browser session), create the account under Admin > Service Accounts in Pipefy and add it as a member of the relevant pipes.

Software on your computer

Installation

The installer sets up the CLI and MCP server in a single command. Replace cursor with your client name:

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

Available clients: cursor, claude-code, claude-desktop, codex. Use none if you want to install without registering automatically in the client and paste the config yourself.

Useful flags

After installation, confirm the commands are available:

pipefy --help
pipefy-mcp-server --help

If you see command not found, add ~/.local/bin to your terminal PATH (the installer warns you when this is needed).

Authentication

Choose one of three options based on your situation:

Option A: Browser login (recommended for personal use and CLI)

pipefy auth login

Opens your browser, completes OAuth, and stores the session in your system keychain. The simplest option for personal use on your own computer.

On headless environments (remote servers), use:

pipefy auth login --device

Option B: Service account (recommended for always-on MCP)

Best when you want the AI assistant to work without depending on an open browser session. Configure credentials in ~/.config/pipefy/config.toml:

service_account_client_id = "YOUR_CLIENT_ID"
service_account_client_secret = "YOUR_CLIENT_SECRET"

Or as environment variables:

PIPEFY_SERVICE_ACCOUNT_CLIENT_ID=...
PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET=...

Option C: Bearer token (for quick one-off tests)

pipefy --token "YOUR_BEARER" pipe list

Precedence: --token > PIPEFY_TOKEN > service account > auth login session. If the CLI is using the wrong credentials, check for environment variables overriding your stored session.

Activating the MCP in your AI assistant

After installing with --client <name>, the server is already registered. If you chose --client none, paste the JSON below into your client's config file:

{
  "mcpServers": {
    "pipefy": {
      "command": "pipefy-mcp-server"
    }
  }
}

If you're using a service account, add the environment variables inside the block:

{
  "mcpServers": {
    "pipefy": {
      "command": "pipefy-mcp-server",
      "env": {
        "PIPEFY_SERVICE_ACCOUNT_CLIENT_ID": "YOUR_CLIENT_ID",
        "PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Cursor

Config file: ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json on Windows.

After saving, restart Cursor and confirm under Settings > MCP that the pipefy server shows as Enabled.

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

After saving, restart Claude Desktop.

Claude Code

In the terminal, for your project or globally:

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

To use a service account with Claude Code, edit ~/.claude.json and add the env block to the pipefy server.

Terminal alternative:

claude mcp add --scope project pipefy -- pipefy-mcp-server
claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_ID <ID>
claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET <SECRET>

Codex

Add to ~/.codex/config.toml:

[mcp_servers.pipefy]
command = "pipefy-mcp-server"

Restart Codex after saving.

Other MCP clients

Use the same pattern: command pipefy-mcp-server, stdio transport, environment variables for credentials. Check your client's documentation for the exact config file path.

Confirming everything works

After restarting your client, ask the assistant:

If you see an authentication error, configure the service account or run pipefy auth login again. If you see PERMISSION_DENIED, add the service account (or your user) as a member of the target pipe.

Common setup issues

Before you move on, confirm that you:

• Understand that the Pipefy AI Toolkit connects your AI assistant to Pipefy via the MCP protocol
• Chose and configured one of the three authentication options
• See the pipefy server as connected in your AI client
• Tested with a simple prompt and got real Pipefy data back

Need help or want to join the group of early customers testing the Pipefy AI Toolkit?