# Pipefy MCP

> Pipefy MCP lets you manage complex business workflows by talking to your AI agent instead of clicking through a dashboard. You can list entire processes, create new records, move items between workflow phases (like 'New' to 'In Progress'), update specific fields on existing requests, and search for cards using criteria like customer email or ID.

## Overview
- **Category:** project-management
- **Price:** Free
- **Tags:** process-management, workflow-automation, task-tracking, business-process-management, data-entry

## Description

Managing business processes usually means opening up a dedicated web portal and navigating through multiple tabs just to get one task updated. This MCP lets your AI agent handle all that complexity through natural conversation. You don't need to remember complex URLs or click through five different screens; you just tell your agent what needs doing.

It acts like a specialized process manager for your company's workflows, allowing you to view the structure of every pipe in your organization, find specific records by their unique ID or customer email, and even duplicate existing items if you need to start a similar request. Need to move a task from 'Draft' to 'Review'? Just tell your agent. You can also change critical data points on a card—like updating the priority level or adding a due date—without ever touching the main Pipefy interface. Because this MCP is hosted and managed by Vinkius, you connect once via any compatible client and gain instant control over all these actions, making it feel like your AI agent genuinely works inside your process management system.

## Tools

### clone_card
Duplicates a current record, keeping all its data intact so you can start a new item as a template.

### create_card
Builds an entirely new record in any defined workflow by providing the required field details.

### delete_card
Permanently removes a card and all associated data from its current workflow.

### get_card
Retrieves the full, detailed information about one specific record using its unique ID.

### get_organization
Shows the high-level structure of your company's account and team details within Pipefy.

### get_phase
Provides detailed information about a specific stage in a workflow, including what fields are required there.

### get_pipe
Maps out the entire structure of a single process, showing all its phases and custom data fields.

### get_user_profile
Checks your logged-in user details and verifies which organizations you have access to.

### list_cards
Lists all records within a specified workflow, optionally filtering by the current phase or status.

### list_phases
Retrieves a list of every stage in a process and counts how many items are currently at each step.

### list_pipes
Shows all available workflows (processes) across your entire organization's account.

### move_card_to_phase
Advances a record from one stage to the next, moving it through the official workflow steps.

### search_cards_by_field
Searches for records across an entire pipe by checking content in a specific field, like email or name.

### update_card_field
Modifies the data stored on a card's record, such as changing a priority level or adding a date.

## Prompt Examples

**Prompt:** 
```
List all pipes in my organization and show me the cards in the 'IT Support' pipe.
```

**Response:** 
```
I've retrieved your organization's pipes. You have 5 active pipes: 'IT Support', 'HR Onboarding', 'Purchase Requests', 'Bug Tracking', and 'Content Approval'. In the 'IT Support' pipe, I found 12 cards: 4 in 'New Requests', 5 in 'In Progress', and 3 in 'Waiting for User'. The oldest card has been waiting 5 days. Would you like the full details of any specific card?
```

**Prompt:** 
```
Create a new purchase request card in the Purchase Requests pipe with these details: Requester: Maria Silva, Item: MacBook Pro 16", Quantity: 2, Justification: Design team replacement.
```

**Response:** 
```
I've successfully created the purchase request card:
- **Card ID**: 12345678
- **Title**: Purchase Request - Maria Silva
- **Current Phase**: New Requests
- **Fields**: Requester: Maria Silva, Item: MacBook Pro 16", Quantity: 2, Justification: Design team replacement

The card is now in the 'New Requests' phase and ready for review. Would you like me to move it to 'Manager Approval' phase?
```

**Prompt:** 
```
Search for all cards in the IT Support pipe where the email field contains 'john@company.com' and show me their current status.
```

**Response:** 
```
I found 3 cards in the IT Support pipe for john@company.com:

1. **Card #12345** — 'Monitor not displaying' — Phase: In Progress — Created: 2024-04-01
2. **Card #12389** — 'Keyboard replacement request' — Phase: Waiting for Parts — Created: 2024-04-03
3. **Card #12401** — 'VPN access issue' — Phase: Resolved — Created: 2024-04-05

Two cards are still active (In Progress and Waiting for Parts), and one is resolved. Would you like the full details of any specific card?
```

## Capabilities

### View Organization Structure
Discover every workflow (pipe) and team member within your company's account.

### Manage Workflow Items
Create, read, update, or delete individual records (cards) flowing through a process.

### Advance Process Steps
Move an item to the next stage of its workflow automatically, like moving a request from 'New' to 'In Review'.

### Update Specific Data Points
Change field values on existing records, such as updating a contact’s email or changing a task's priority.

### Search for Records by Detail
Find specific items across multiple workflows using details like an ID, name, or customer email address.

## Use Cases

### Onboarding a New Client Request
The Ops Manager needs to start tracking a new client relationship. Instead of manually setting up all the fields, they ask their agent to 'Create a card in the Onboarding pipe for John Doe with email john@example.com.' The agent handles the data entry and gets it into the correct starting phase.

### Identifying Workflow Bottlenecks
The Project Coordinator notices that many tasks are stalling. They ask their agent to 'List all cards in the Bug Tracking pipe currently sitting in the Review stage.' This instantly identifies the bottleneck and tells them exactly what needs attention.

### Responding to a Customer Inquiry
A Support Agent receives an email from a customer. They ask their agent to 'Search for cards by field using the email jane@corp.com.' The agent instantly pulls up all related support tickets and updates the status of the oldest one.

### Auditing Process History
The Process Owner needs to review how a specific request evolved over time. They ask their agent to 'Get detailed information about card 9876.' The agent pulls up all historical field values, comments, and the full timeline of moves.

## Benefits

- Stop jumping between tabs. Instead of opening the Pipefy dashboard to update a status, just ask your agent to 'Move card X to In Review.' It handles the entire process in one step.
- Never lose track of processes again. You can use `list_pipes` and `get_pipe` to understand exactly how every workflow is structured before you even create a single record.
- Need to find an old support ticket? Don't manually scroll through hundreds of cards. Use the agent to `search_cards_by_field` by customer email or name, getting instant results.
- Start fresh without repeating work. Instead of recreating fields and data for similar requests, use `clone_card` to duplicate an existing record and just adjust a few details.
- Keep your process clean. When a task is done, tell the agent to move it using `move_card_to_phase`. This ensures every card moves through the official steps, keeping your data accurate.
- Get a full picture of what's happening. With the ability to `list_cards` and check status, you can get an immediate count of items stuck in any given workflow stage.

## How It Works

The bottom line is you use plain English conversation to execute complex, multi-step actions within your project management platform.

1. Subscribe to this MCP and provide your Pipefy API token.
2. Connect the service to your preferred AI client (Claude, Cursor, etc.).
3. Ask your agent to perform a workflow action, like 'Find all cards in the IT Support pipe where the status is pending' or 'Move card 12345 to the Completed phase.'

## Frequently Asked Questions

**How do I get a Pipefy API token and where do I find it?**
Log in to Pipefy, click on your **Profile icon** (top-right), go to **Profile > API Access**, and generate a new token. Alternatively, use **Service Accounts** for team-based access. Copy the token immediately — it starts with `eyJhbG...`. Paste it into the API token field below. This token authenticates all GraphQL API requests to `https://api.pipefy.com/graphql`.

**How do I move a card from one phase to another in a pipe?**
Use the `move_card_to_phase` tool with the card_id (from list_cards or get_card) and the target phase_id (from get_pipe or list_phases). This advances the card through your workflow. For example, moving a card from 'New Requests' to 'In Review' phase. The card retains all its field values after moving. This is the primary way to progress items through your process.

**Can I search for cards by a specific field value like email or customer name?**
Yes! Use the `search_cards_by_field` tool with the pipe_id, field_id (the specific field to search in), and search_value (the text to find). This searches all cards in the pipe where that field contains your search text. It's perfect for finding cards by customer email, name, order number, or any custom field. Results include full card details with all field values.

**How do I create a new card with custom field values?**
Use the `create_card` tool with the pipe_id and a JSON object containing field values. The fields parameter should be a JSON object where keys are field IDs (from get_pipe) and values are the data to store. Example: `{ "name": "John Doe", "email": "john@example.com", "priority": "High" }`. You can also optionally specify a phase_id to start the card in a specific phase instead of the default first phase.