What Activepieces MCP Actually Does
Model Context Protocol (MCP) is the open standard for connecting AI clients (like Claude Desktop, Cursor, and Windsurf) to external tools and data. Activepieces supports MCP by acting AS an MCP server: it exposes its own capabilities -- your flows, plus tools for building, managing, and testing automations -- so that any MCP-compatible AI client can call them. In other words, the AI client is the caller and Activepieces is the tool provider.
This matters because it inverts a common assumption. Activepieces does not (today) ship an MCP client piece that reaches out and runs arbitrary external MCP servers as subprocesses inside a flow -- that is a separate, unshipped feature request. What it does ship is the reverse and arguably more useful direction: your Activepieces instance becomes a hub of ready-to-use tools that your AI assistant can invoke over MCP.
Direction check: You add the Activepieces MCP server URL to your AI client. The AI client then calls Activepieces. You are not adding external MCP servers inside Activepieces flows.How It Works
Activepieces publishes a single MCP server endpoint for your instance. Once an AI client is connected, the model can discover and call the tools that endpoint exposes -- for example, listing and running your flows, creating or editing flows, working with tables, and inspecting run history. Because Activepieces already ships 700+ pieces (connectors), the flows you build on top of those pieces become callable, reusable tools for your AI assistant without you writing a single custom integration for the model.
The practical upside: instead of wiring bespoke tool definitions into every AI client, you build a flow once in Activepieces and expose it to Claude Desktop, Cursor, or any other MCP client through the same endpoint.
Enabling the MCP Server and Getting Your URL
- In Activepieces, open Settings and select MCP Server.
- Toggle the MCP server on.
- Copy the Server URL. On Activepieces Cloud this looks like https://cloud.activepieces.com/api/v1/mcp; on a self-hosted instance it is https://your-instance.com/mcp.
- Keep this URL handy -- you will paste it into your AI client's MCP configuration.
Copy the exact URL from the Settings screen rather than hardcoding one from a tutorial. Cloud and self-hosted instances (and subpath deployments) can differ, and the UI shows the correct endpoint for your setup.Connecting Claude Desktop
Add the endpoint to Claude Desktop's config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"activepieces": {
"url": "https://cloud.activepieces.com/api/v1/mcp"
}
}
}Restart Claude Desktop. On first use the client opens a browser to authenticate against your Activepieces account via OAuth -- your credentials are never pasted into the config file. After you approve, Activepieces' tools appear in the client and Claude can call them.
Some client versions cannot yet speak to a remote (HTTP/SSE) MCP server directly and need a local bridge such as npx mcp-remote <url>. If the plain url form above is not picked up, check your client's docs for its current remote-server syntax.Connecting Cursor
Cursor reads MCP servers from .cursor/mcp.json (per project) or ~/.cursor/mcp.json (global). Add the same endpoint, or use Cursor Settings > Features > MCP > Add New MCP Server and paste the URL:
{
"mcpServers": {
"activepieces": {
"url": "https://cloud.activepieces.com/api/v1/mcp"
}
}
}Windsurf and Claude.ai custom connectors follow the same pattern: point the client at the Activepieces MCP URL and authenticate via the OAuth browser prompt on first use.
Example: An AI Client Running an Activepieces Flow
Suppose you build a flow in Activepieces called "Post to Slack" that takes a channel and a message and posts it using the Slack piece (with the Slack connection stored in Activepieces). Once your MCP server is enabled and Claude Desktop is connected, the interaction looks like this:
- You ask Claude: "Post a summary of today's incidents to #ops."
- Claude discovers the available Activepieces tools over MCP and selects the flow that posts to Slack.
- Claude calls the tool, passing channel = "#ops" and the message it composed.
- Activepieces runs the flow using its stored Slack connection and returns the run result to Claude.
- Claude confirms the message was posted, quoting the flow's output.
Notice what did not happen: Claude never touched your Slack token. The credential lives in the Activepieces connection; the model only sees the tool's inputs and outputs. The same pattern works for any flow you build on top of the 700+ pieces -- database lookups, CRM updates, document generation, and so on.
Example: A Read-Only Data Lookup Flow
For a safer, read-only tool, build a flow that queries a data source and returns rows -- for instance a flow that looks up a customer by email in your database and returns their plan and status. Expose that flow through MCP and your AI assistant can answer "What plan is jane@acme.com on?" by calling the flow, without the model ever holding your database credentials or being able to write to the database. Scoping each flow to a single, well-defined action is how you keep an AI client useful and contained.
What Tools Get Exposed
The Activepieces MCP server groups its tools into categories. The exact set evolves, but current documentation describes roughly the following:
| Category | What the AI client can do |
|---|---|
| Discovery | Always available; lets the client enumerate what other tools and flows exist. |
| Flow management | List, enable, disable, and inspect existing flows. |
| Flow building | Create and edit flows programmatically. |
| Router & branching | Add conditional logic and branches to flows. |
| Annotations | Attach notes/metadata to flow steps. |
| Tables | Read from and write to Activepieces Tables. |
| Testing & runs | Test flows and inspect run history and outputs. |
Whether each individual flow appears as its own callable tool versus being triggered through the flow-management tools can depend on your Activepieces version. Confirm the exposed tool list in your AI client after connecting, and treat the categories above as a guide rather than a fixed contract.Authentication and Security
- Auth is OAuth-based: the client authenticates against your Activepieces account through a browser prompt on first connect, so no long-lived secret sits in a plaintext config file.
- Credentials for the underlying services (Slack, your database, etc.) stay inside Activepieces connections. The AI client only ever sees flow inputs and outputs.
- Treat the MCP server URL as sensitive -- anyone who can connect to it and authenticate can invoke your tools. Only enable it for accounts and instances you trust.
- Prefer narrowly scoped, single-purpose flows for anything an AI client will call. A read-only lookup flow is far safer to expose than a general "run any SQL" flow.
Because flow-building tools let a connected client create and edit flows, only connect AI clients you control. A prompt-injected agent with write access to your flows is a real risk -- consider a dedicated, limited Activepieces account for MCP access.Realistic Use Cases
- Give a coding assistant (Cursor/Windsurf) the ability to trigger your deployment or notification flows without leaving the editor.
- Let Claude Desktop run internal operations flows -- create a ticket, post a status update, kick off a report -- from a natural-language request.
- Expose read-only lookup flows so an AI assistant can answer questions from your CRM, database, or internal tables without direct credential access.
- Prototype an agent's toolset in Activepieces (where connections and retries are handled for you), then expose the finished flows to any MCP client.
When to Use Activepieces MCP vs a Custom Tool Definition
Use the Activepieces MCP server when:
- You already build the underlying automation in Activepieces and want to reuse it across multiple AI clients.
- You want credentials and OAuth handling to stay inside Activepieces rather than in each client.
- You want the same tool available to Claude Desktop, Cursor, and Windsurf from one endpoint.
Write a custom, in-client tool definition instead when:
- The action is trivial and does not justify a flow (a single local function is simpler).
- You need the tool to run entirely offline or inside the client's own process with no round trip to Activepieces.
- You require behavior that Activepieces pieces cannot express and would be awkward to model as a flow.
For most teams already invested in Activepieces, exposing existing flows over MCP is the fastest way to give an AI assistant real, credential-safe capabilities across 700+ integrations.