Skip to main content
Activepieces includes a built-in MCP server that lets AI assistants build flows, manage tables, test automations, and more — all through natural language.

​
Quick Start

​
1. Get Your Server URL

  1. Go to Settings → MCP Server
  2. Toggle the server on
  3. Copy the Server URL

​
2. Connect Your Client

Add the URL to your MCP client config. Authentication is handled via OAuth — your client will open a browser to authenticate on first use. 
{
  "mcpServers": {
    "activepieces": {
      "url": "https://your-instance.com/mcp"
    }
  }
}
ClientConfig Location
Cursor.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
WindsurfMCP settings in editor preferences
Claude.aiOrganization Settings → Connectors → Add → Custom connector

​
3. Start Building

Once connected, ask your AI assistant things like:
  • “Create a flow that sends a Slack message when a new row is added to Google Sheets”
  • “Check my flow for any issues before publishing”
  • “Create a Contacts table and add 3 records”
  • “Show me the last failed run and what went wrong”
  • “What Slack triggers are available?”

​
Tool Categories

Tools are organized into categories. Discovery tools are always available. Other categories can be enabled or disabled per-project in the MCP Server settings.
CategoryDescription
DiscoveryRead-only tools for exploring flows, pieces, connections, tables, runs, and validation
Flow ManagementCreate, duplicate, rename, publish, and enable/disable flows
Flow BuildingAdd, update, and delete steps and triggers
Router & BranchingAdd, update, and delete conditional branches
AnnotationsManage canvas notes
TablesFull CRUD for tables, fields, and records
Testing & RunsTest flows, inspect results, retry failures
See the Tools Reference for the complete catalog with input schemas.

​
Self-Hosting Behind a Reverse Proxy

The MCP server and its OAuth endpoints are reachable both at the host root (https://your-instance.com/mcp) and under a path prefix (https://your-instance.com/<prefix>/mcp) when your reverse proxy routes https://host/<prefix>/* to Activepieces. For a subpath deployment to work, set AP_FRONTEND_URL to the full public URL including the prefix (e.g. https://your-instance.com/activepieces). Activepieces then advertises its OAuth issuer, authorization/token endpoints, protected-resource metadata, and the WWW-Authenticate discovery header under that prefix, so the entire handshake stays inside your proxy rule.
Clients that ignore the WWW-Authenticate header and probe the RFC well-known paths at the host root (https://host/.well-known/oauth-*) require an additional proxy rule forwarding those host-root paths to Activepieces — that namespace is anchored to the host root by RFC 8414/9728 and cannot be relocated under the prefix. Header-honoring clients (such as Claude) do not need this.

​
Security

  • OAuth authentication — secure, token-based authentication handled automatically by your MCP client
  • Credentials are never exposed — connection secrets, API keys, and OAuth tokens are never returned by any tool
  • Project-scoped — all operations are scoped to the authenticated project
  • Sensitive setup — ap_setup_guide returns instructions for the user to configure connections in the UI, rather than handling secrets through MCP