👤 For operations teams, pipe admins, and technical teams
🔐 Available on All plans
🎯 For those who Want to connect an AI assistant to Pipefy or understand how MCP works
How to connect Pipefy to the AI assistant your team already uses through the Model Context Protocol (MCP).
📖 What you will understand here:
1. What MCP is, in one sentence
MCP (Model Context Protocol) is an open protocol created by Anthropic, the company behind Claude, that allows AI assistants to connect to external systems and perform real actions in them. In Pipefy, MCP is not a separate product or an add on. It is an enabler built into the platform itself.
In practice, MCP allows the AI assistant your team already uses in its daily work, such as Claude, Cursor, or Codex, to interact directly with Pipefy by querying pipes, cards, and reports and, depending on the configuration, performing actions within the process.
Think of the MCP Server as a "secretary" inside your AI assistant. It does exactly what you could do manually in the Pipefy interface, but from a natural language command.
2. Prerequisites
Two ways to connect: There is a hosted option that requires no installation and enables read only queries, such as reading pipes, cards, and reports. There is also the local option covered in this guide, which installs the server on your machine from the official GitHub repository and enables the full set of capabilities: querying Pipefy and performing actions such as creating or moving cards, creating AI Agents, and creating pipes.
| Prerequisite | Details |
| AI assistant compatible with MCP | Claude Desktop, Claude Code, Cursor, or Codex. You need an agent that can interpret instructions and make decisions. |
| Pipefy account with API access | Personal access token generated in My Profile > Personal access token. For corporate or automated use, use a Service Account provisioned by a Super Admin. |
| Git | Required for the repository based installation path. On Windows, use Git Bash, which is installed with Git for Windows. |
| Python and uv | The MCP server is a Python package. The recommended package manager is uv, which resolves Python automatically, so you do not need to install Python separately. |
3. Step by step installation
The MCP Server is installed from the official open source pipefy/ai-toolkit repository on GitHub. The steps below use Claude Desktop as an example. The same principle applies to other MCP compatible clients.
Download and install
- Go to the official repository: github.com/pipefy/ai-toolkit.
- Use the official installer, which is recommended. Run the repository installation script in the terminal and point it to your AI client, such as Claude Desktop or Cursor. The uv package manager resolves dependencies automatically.
- Manual alternative: open the repository, download the code using "Code > Download ZIP", extract it, and follow the instructions in the README file. This option is useful if you do not use Git or have network restrictions.
- Confirm that the pipefy-mcp-server executable was installed on your machine before continuing to configuration.
On Windows: The automatic installer supports macOS and Linux. On Windows, install the uv package manager through Git Bash, clone the repository manually with git clone, and point Claude Desktop to the uv executable. The complete installation guide explains this Windows specific path in detail.
Generate your personal access token
- In Pipefy, click your profile picture in the upper right corner and open My Profile.
- In the Personal access token section, click Generate a new token.
- Give it a name that identifies its purpose, for example "Claude MCP", and copy the generated token.
Important: Store the token in a secure location. It is not displayed again after it is generated, and it should never be pasted into chat conversations, screenshots, or shared documents. It goes directly into the configuration file, which you edit locally on your machine.
Configure your AI assistant
The AI client configuration file must point to the absolute path of the installed executable and include your access token. This path varies from one machine to another, so do not reuse someone else's path.
| Client | Configuration file location |
| Claude Desktop, macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop, Windows | %APPDATA%\Claude\claude_desktop_config.json (if installed from the Microsoft Store, use the "Edit Config" option in the app to open the correct file) |
| Cursor | ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows) |
| Codex | ~/.codex/config.toml |
Basic structure of the block to add in Claude Desktop with a personal access token:
{
"mcpServers": {
"pipefy": {
"command": "/absolute/path/to/pipefy-mcp-server",
"env": {
"PIPEFY_TOKEN": "YOUR_TOKEN"
}
}
}}
When saving: Save the file as plain JSON, without smart quotation marks or extra commas. Malformed JSON can cause the AI client to ignore the server silently without displaying an error message. On Windows, use double backslashes in paths.
Restart your AI assistant
Close the application completely. Closing only the window is not enough because the application may continue running in the background. On macOS, use Cmd+Q. On Windows, exit from the system tray icon near the clock. Then reopen the application.
4. Testing the connection
- Open a new conversation in your AI assistant.
- Confirm that Pipefy appears in the list of available tools or connectors. In Claude Desktop, use the + icon in the message box and open Connectors, or go to Settings > Developer > Local MCP Servers.
- Ask for something simple, such as "list my organizations in Pipefy" or "which pipes exist in organization X".
Sign that it worked: If the assistant returns real organizations, pipes, or cards from your account, the connection is working. If the data is truncated or incomplete, that is expected. It protects the AI from being overloaded with very large volumes of context. Ask for more specific information, such as one organization or one pipe at a time, to get a more focused result.
Common errors and how to solve them
| Symptom | What to do |
| "Git not found" during installation | Git is not installed. Install it from the official website, git-scm.com, or through your system package manager, close and reopen the terminal, and try again. |
| Pipefy does not appear in the assistant after configuration | Two common causes: (1) the executable path in the configuration file is incorrect. Find the correct path on your machine again. (2) Claude was installed from the Windows Store, which uses a different configuration file. Use the "Edit Config" option in the app. |
| Login or authentication error on a corporate computer | Corporate networks often block automatic authentication flows. Use the Personal access token directly in the configuration file. This method does not depend on the browser. |
| No error appears, but the tool does not appear either | The JSON file is probably malformed because of an extra comma or incorrect quotation marks. Validate the content in an online JSON validator before saving. |
| Returned data is truncated or incomplete | Expected behavior. This protects the context from very large volumes of data. Ask for a more specific scope, such as one organization or one pipe at a time. |
6. Frequently asked questions
Can MCP change my Pipefy environment on its own?
Not without your approval. MCP analyzes the environment and can suggest or propose the creation of automations, flows, and agents, but it always shows what it intends to do first and asks for explicit confirmation. No action is performed silently.
Can I automate an entire process from end to end, rather than only isolated tasks?
Yes. You can configure multiple AI Agents and MCP connections in the same pipe, with triggers and rules by phase, to orchestrate the complete flow instead of relying on isolated automations.
What is the risk of AI changing a flow that is already working correctly?
The main safeguard is that the AI never performs an action without first showing what it intends to do and asking for confirmation. Because this is probabilistic technology, the risk is not absolutely zero. However, because the model announces the action before performing it, the chance of it acting differently from what it announced is low. Even so, the recommendation is to test and validate changes in cloned pipes before applying them in production, especially because some changes, such as deleting an automation, cannot be undone automatically.
How do permissions and information access work?
MCP inherits exactly the same permission level as the person or token executing the action. If your user does not have admin access or is not a member of a specific pipe, MCP will not have that access either. Because the connection depends on a personal access token generated in each user's profile, you can enable usage only for specific people on your team, even if everyone has access to the same pipe through the interface.
Are actions performed through MCP recorded for auditing?
Yes. All operations performed through MCP Server are recorded in the access history of the account that executed the action, in the same place where any other action by that user would appear.
Do I need an AI tool to use MCP?
Yes. You need an AI client that is compatible with the MCP protocol, such as Claude Desktop, Claude Code, Cursor, or Codex, where instructions are interpreted and decisions are made.
How is usage counted?
It depends on the direction of the flow. When an external AI queries or changes Pipefy through MCP Server, each call consumes one API Call within the API call allowance already included in your contract. When a Pipefy AI Agent accesses an external tool through MCP Client, each call consumes one AI credit. For an estimate based on your expected usage volume, your Pipefy account team can help detail the numbers.
Is there a hosted version that does not require installation?
Yes, for read only queries. It connects your AI assistant to Pipefy's hosted server with just a few commands and without installing anything on your machine. Write actions, such as creating or moving cards, creating AI Agents, or creating pipes, still depend on the local path covered in this guide.
If I switch computers, do I need to install everything again?
For the local path, yes. The MCP server runs as a process on the machine itself, so switching computers requires repeating the installation on the new machine. This is not required for the hosted path.
7. Reference links
- Official repository, open source under Apache 2.0
- What the Pipefy MCP Server is and what it enables
- How to configure the Pipefy AI Toolkit in your AI assistant
- How to configure MCP Client in Pipefy
- How to create an AI Agent for your process with MCP Server
