MCP Servers

Connect Activepieces pieces to AI assistants using Model Context Protocol

MCP Servers in Activepieces

Activepieces provides the largest open source MCP (Model Context Protocol) toolkit with all 600+ pieces automatically available as MCP servers. Connect your workflows to AI assistants like Claude Desktop, Cursor, and Windsurf, enabling powerful AI-human-tool collaboration.

What is MCP?

MCP (Model Context Protocol) is a standard protocol that allows Large Language Models (LLMs) to interact with external tools and services. It was developed by Anthropic to enable AI assistants to:

• Access external data sources
• Execute actions in external systems
• Retrieve real-time information
• Perform complex multi-step operations

MCP acts as a bridge between AI assistants and real-world tools, allowing Claude, Cursor, and other LLM-powered applications to use your Activepieces workflows as callable tools.

How Activepieces MCP Works

Every Activepieces piece and flow can be exposed as an MCP server tool. Here’s how it works:

1. MCP Server Configuration

Based on the source code, Activepieces manages MCP servers at the project level:

interface McpServer {
  id: string;
  projectId: string;              // Project this MCP server belongs to
  status: McpServerStatus;        // ENABLED or DISABLED
  token: string;                  // Authentication token (72 chars)
  flows: PopulatedFlow[];         // Flows exposed as MCP tools
}

enum McpServerStatus {
  ENABLED = 'ENABLED',
  DISABLED = 'DISABLED',
}

2. MCP Tool Trigger

Flows use a special MCP trigger to expose themselves as callable tools:

const mcpTrigger = {
  type: 'PIECE',
  settings: {
    pieceName: '@activepieces/piece-mcp',
    triggerName: 'mcp_tool',
    input: {
      toolName: 'search_customers',
      toolDescription: 'Search the customer database by email or name',
      inputSchema: [
        {
          name: 'query',
          type: McpPropertyType.STRING,
          description: 'Search query (email or name)'
        },
        {
          name: 'limit',
          type: McpPropertyType.NUMBER,
          description: 'Maximum number of results'
        }
      ],
      returnsResponse: true  // Return data to the AI assistant
    }
  }
};

3. Tool Execution Flow

When an AI assistant calls an MCP tool:

1. AI makes request: Claude/Cursor calls the tool with parameters
2. MCP server receives: Activepieces MCP server accepts the request
3. Flow executes: The associated flow runs with the provided inputs
4. Response returned: Flow output is sent back to the AI assistant
5. AI uses result: Assistant incorporates the data into its response

Setting Up MCP in Activepieces

1. Enable MCP Server

   In your Activepieces project settings:

   1. Navigate to Project Settings → MCP Server
   2. Click Enable MCP Server
   3. Copy the generated MCP server token
   4. Note the server URL (e.g., https://cloud.activepieces.com/api/v1/mcp)
2. Create an MCP-Enabled Flow

   Create a new flow with an MCP trigger:

   1. Create a new flow
   2. Select MCP Tool as the trigger
   3. Configure the tool:
      • Tool Name: search_database
      • Tool Description: “Search the customer database”
      • Input Schema: Define expected parameters
      • Returns Response: Enable if the AI needs data back
   4. Add action steps to perform the work
   5. Publish the flow
3. Configure Your AI Assistant

   Connect your AI assistant to Activepieces MCP server (see sections below).

4. Test the Integration

   Ask your AI assistant to use the tool:

   "Can you search for customer [e-mail] in the database?"
   

   The AI will automatically call your Activepieces flow and use the results.

Using with Claude Desktop

Claude Desktop is Anthropic’s desktop application that supports MCP servers.

Configuration

Add Activepieces to your Claude Desktop MCP configuration:

macOS/Linux: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "activepieces": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-activepieces"
      ],
      "env": {
        "ACTIVEPIECES_URL": "https://cloud.activepieces.com",
        "ACTIVEPIECES_TOKEN": "your-mcp-server-token"
      }
    }
  }
}

Using MCP Tools in Claude

Once configured, Claude can automatically discover and use your Activepieces tools:

You: "What tools do you have access to?"

Claude: "I have access to the following Activepieces tools:
- search_customers: Search the customer database by email or name
- send_notification: Send a notification to a Slack channel
- create_ticket: Create a support ticket in the system"

You: "Search for customer [e-mail]"

Claude: [Calls the search_customers MCP tool]
"I found the customer Jane Smith with email [e-mail]..."

Using with Cursor

Cursor is an AI-powered code editor that supports MCP servers.

Configuration

Add Activepieces MCP to your Cursor settings:

1. Open Cursor Settings
2. Navigate to AI → MCP Servers
3. Add a new MCP server:

{
  "name": "Activepieces",
  "url": "https://cloud.activepieces.com/api/v1/mcp",
  "token": "your-mcp-server-token"
}

Using in Cursor

Use Cursor’s AI assistant to interact with your Activepieces tools:

You: "@activepieces search for recent orders"

Cursor: [Executes the search_orders tool]
"Found 5 recent orders: ..."

Using with Windsurf

Windsurf is another AI-powered development environment with MCP support.

Configuration

Similar to Cursor, add Activepieces to Windsurf’s MCP configuration:

{
  "mcpServers": [
    {
      "name": "Activepieces",
      "serverUrl": "https://cloud.activepieces.com/api/v1/mcp",
      "apiKey": "your-mcp-server-token"
    }
  ]
}

MCP Tool Input Schema

Define structured inputs for your MCP tools using the input schema:

inputSchema: [
  {
    name: 'email',
    type: McpPropertyType.STRING,
    description: 'Customer email address',
    required: true
  },
  {
    name: 'includeOrders',
    type: McpPropertyType.BOOLEAN,
    description: 'Include order history',
    required: false
  },
  {
    name: 'limit',
    type: McpPropertyType.NUMBER,
    description: 'Maximum results to return',
    required: false
  },
  {
    name: 'filters',
    type: McpPropertyType.OBJECT,
    description: 'Additional filter criteria',
    required: false
  },
  {
    name: 'tags',
    type: McpPropertyType.ARRAY,
    description: 'List of tags to filter by',
    required: false
  }
]

Supported property types:

• STRING: Text input
• NUMBER: Numeric input
• BOOLEAN: True/false
• OBJECT: JSON object
• ARRAY: List of items

Returning Data to AI

When returnsResponse: true, the flow output is sent back to the AI:

// In your flow's final step, return structured data
{
  type: 'CODE',
  settings: {
    sourceCode: {
      code: `
        export async function code(inputs) {
          return {
            customers: inputs.searchResults,
            totalFound: inputs.searchResults.length,
            searchTime: new Date().toISOString()
          };
        }
      `
    }
  }
}

The AI receives this data and can use it in its response to the user.

MCP Server Implementation

Behind the scenes, Activepieces implements a full MCP server using the @modelcontextprotocol/sdk:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const server = new McpServer({
  name: 'Activepieces',
  version: '1.0.0',
});

// Register each enabled flow as an MCP tool
for (const flow of enabledFlows) {
  const mcpTrigger = flow.version.trigger.settings;
  const toolName = mcpTrigger.input.toolName;
  const toolDescription = mcpTrigger.input.toolDescription;
  const inputSchema = mcpTrigger.input.inputSchema;
  
  // Convert input schema to Zod schema
  const zodSchema = buildZodSchema(inputSchema);
  
  // Register tool
  server.tool(toolName, toolDescription, zodSchema, async (args) => {
    // Execute the flow with the provided arguments
    const response = await executeFlow(flow.id, args);
    return response;
  });
}

Real-World Use Cases

Customer Support

Let Claude search your customer database, create tickets, and send notifications - all through natural language.

Code Development

Use Cursor to query your APIs, update configurations, and deploy services using Activepieces workflows.

Data Analysis

Ask AI assistants to fetch, analyze, and visualize data from your connected services.

DevOps Operations

Execute deployment pipelines, check system health, and manage infrastructure through AI commands.

Security Considerations

MCP server tokens provide full access to execute flows in your project. Treat them like API keys:

• Store tokens securely
• Rotate tokens regularly
• Use different tokens for different environments
• Disable MCP when not in use
• Monitor MCP tool executions in the Runs log

Token Management

Rotate your MCP token if compromised:

// Via API
POST /api/v1/mcp/rotate-token
Authorization: Bearer YOUR_API_KEY

// Returns new token
{
  "token": "new-72-character-token",
  "projectId": "your-project-id"
}

Benefits of Activepieces MCP

600+ Tools Ready

Every Activepieces piece is automatically available as an MCP tool - no extra configuration needed.

Type-Safe Integration

Input schemas ensure AI assistants call tools with the correct parameters.

Visual Development

Build complex MCP tools using the visual workflow builder instead of writing code.

Built-in Authentication

Activepieces handles auth for all connected services - AI doesn’t need separate credentials.

Audit & Monitoring

Track every MCP tool execution in the Runs log for debugging and compliance.

Open Source

Full source code available - understand exactly how MCP integration works.

Example: Complete MCP Tool

Here’s a complete example of an MCP-enabled flow that searches a database:

// Flow: "Search Customer Database"
{
  displayName: "Search Customer Database",
  status: FlowStatus.ENABLED,
  version: {
    trigger: {
      type: "PIECE",
      settings: {
        pieceName: "@activepieces/piece-mcp",
        triggerName: "mcp_tool",
        input: {
          toolName: "search_customer_database",
          toolDescription: "Search for customers by email, name, or ID",
          inputSchema: [
            {
              name: "query",
              type: "STRING",
              description: "Search query (email, name, or ID)"
            },
            {
              name: "limit",
              type: "NUMBER",
              description: "Max results (default 10)"
            }
          ],
          returnsResponse: true
        }
      }
    },
    actions: [
      // Step 1: Query database
      {
        name: "query_db",
        type: "PIECE",
        settings: {
          pieceName: "@activepieces/piece-postgres",
          actionName: "execute_query",
          input: {
            query: "SELECT * FROM customers WHERE email LIKE $1 OR name LIKE $1 LIMIT $2",
            params: [
              "{{trigger.query}}",
              "{{trigger.limit ?? 10}}"
            ]
          }
        }
      },
      // Step 2: Format response
      {
        name: "format_response",
        type: "CODE",
        settings: {
          sourceCode: {
            code: `
              export async function code(inputs) {
                return {
                  success: true,
                  customers: inputs.results,
                  count: inputs.results.length,
                  query: inputs.query
                };
              }
            `
          },
          input: {
            results: "{{steps.query_db.output}}",
            query: "{{trigger.query}}"
          }
        }
      }
    ]
  }
}

Now AI assistants can search your database:

User: "Find customer with email [e-mail]"

Claude: [Calls search_customer_database tool]
"I found John Smith with email [e-mail]. He has been a customer since 2023..."

Next Steps

• Build AI Workflows - Create intelligent automations
• Create Custom Pieces - Build your own MCP-enabled tools
• API Reference - Programmatic access to MCP servers
• Workflow Concepts - Understand flows and triggers