Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

17.2 KB
Raw Blame
import { isNil, Permission } from '@activepieces/core-utils'
import { FlowStatus, McpOAuthClientKey, McpProperty, McpServer as McpServerSchema, McpToolDefinition, mcpToolNameUtils, McpToolResult, McpTrigger, PopulatedFlow, PopulatedMcpServer, ProjectScopedMcpServer, TelemetryEventName } from '@activepieces/shared'
import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
import { FastifyBaseLogger } from 'fastify'
import { flowService } from '../flows/flow/flow.service'
import { rejectedPromiseHandler } from '../helper/promise-handler'
import { system } from '../helper/system/system'
import { AppSystemProp } from '../helper/system/system-props'
import { instrumentMcpServer, telemetry } from '../helper/telemetry.utils'
import { WebhookFlowVersionToRun, webhookService } from '../webhooks/webhook.service'
import { McpActivityContext, withActivityRecording } from './activity/mcp-activity-recorder'
import { mcpAccess } from './mcp-access'
import { ALLOW_ALL, deny, PermissionChecker, resolveMcpPermissionChecker, resolvePermissionChecker } from './mcp-permissions'
import { mcpProjectSelection, ProjectSelectionScope } from './mcp-project-selection'
import { mcpToolInput } from './mcp-tool-input'
import { McpCallBilling, mcpUsageTracker, withCallBilling } from './mcp-usage-tracker'
import { activepiecesTools, ALL_CONTROLLABLE_TOOL_NAMES, LOCKED_TOOL_NAMES, PLATFORM_LEVEL_TOOL_NAMES } from './tools'
import { apSetProjectContextTool, SET_PROJECT_CONTEXT_TOOL_NAME } from './tools/ap-set-project-context'

const PLATFORM_LEVEL_TOOL_SET = new Set<string>(PLATFORM_LEVEL_TOOL_NAMES)

const MCP_SERVER_INSTRUCTIONS = `## Activepieces MCP Server

### Workflow
0. Project: on the platform server, call ap_set_project_context first — every project tool, including ap_list_connections and ap_list_ai_models, needs a selected project
1. Discover: ap_research_pieces, ap_list_connections, ap_list_ai_models
2. Schema: ap_get_piece_props (get field names/types before configuring)
3. Build: ap_build_flow (one call for new flows) OR ap_create_flow → ap_update_trigger → ap_add_step (granular)
4. Validate: ap_validate_flow with flowId for one flow, or with folderName for a solution of several flows and tables in one folder
5. Publish: ap_lock_and_publish → ap_change_flow_status

### Key patterns
- **Auth**: ap_list_connections → get \`externalId\` → pass as \`auth\` param on ap_update_step/ap_update_trigger.
- **Step refs**: \`{{stepName['output'].field}}\` — a step's data is nested under \`['output']\` (e.g. \`{{trigger['output'].body.email}}\`, \`{{step_1['output'].id}}\`). The trigger follows the same rule: use \`{{trigger['output'].field}}\`, never \`{{trigger.field}}\`. For a continue-on-failure step's error, use \`{{stepName['error'].message}}\`.
- **Step names**: \`trigger\`, \`step_1\`, \`step_2\`, etc. Use ap_flow_structure to see all names.
- **Piece names**: full format (e.g. "@activepieces/piece-slack") for ap_add_step/ap_update_trigger. Short names work for lookup tools.
- **Modifying steps**: use ap_update_step/ap_update_trigger. Never delete+recreate — loses sample data.
- **CODE steps**: export a \`code\` fn; access inputs via \`inputs.key\`.
- **Tables**: use field names, not IDs.`

export async function buildMcpServer({ mcp, userId, platformId, platformDisabledTools, clientKey, clientId, isInAppChat, log, resolveProjectMcp }: {
    mcp: PopulatedMcpServer
    userId?: string
    platformId?: string
    platformDisabledTools: string[]
    clientKey: McpOAuthClientKey | null
    clientId: string
    isInAppChat: boolean
    log: FastifyBaseLogger
    resolveProjectMcp?: (projectId: string) => Promise<McpServerSchema>
}): Promise<McpServer> {
    const projectId = mcp.projectId

    const server = new McpServer({
        name: 'Activepieces',
        title: 'Activepieces',
        version: '1.0.0',
        websiteUrl: 'https://activepieces.com',
        description: 'Automation and workflow MCP server by Activepieces',
        icons: [
            {
                src: 'https://cdn.activepieces.com/brand/logo.svg',
                mimeType: 'image/svg+xml',
            },
            {
                src: 'https://cdn.activepieces.com/brand/logo-192.png',
                mimeType: 'image/png',
                sizes: ['192x192'],
            },
        ],
    }, {
        instructions: MCP_SERVER_INSTRUCTIONS,
        maxToolInputElements: MCP_MAX_TOOL_INPUT_ELEMENTS,
    })

    if (!isInAppChat) {
        instrumentMcpServer({ server, userId, platformId })
    }

    const billing = await mcpUsageTracker(log).resolveCallBilling({ mcp, clientId })

    if (projectId) {
        const resolveChecker = isInAppChat ? resolvePermissionChecker : resolveMcpPermissionChecker
        const permissionChecker = userId
            ? await resolveChecker({ userId, projectId, log })
            : ALLOW_ALL
        const activityContext: McpActivityContext | null = isNil(platformId) || isNil(userId) ? null : { platformId, projectId, userId, clientKey }
        registerFlowTools({ server, mcp, projectId, permissionChecker, billing, log })
        registerStaticTools({ server, mcp, projectId, userId, platformDisabledTools, permissionChecker, activityContext, billing, log })
    }
    else if (!isNil(mcp.platformId) && !isNil(userId) && !isNil(resolveProjectMcp)) {
        registerPlatformTools({ server, mcp, platformId: mcp.platformId, userId, clientKey, selectionScope: { platformId: mcp.platformId, userId, clientId }, resolveProjectMcp, billing, log })
    }
    else {
        registerPlaceholderTools(server)
    }

    registerEmptyResourcesAndPrompts(server)
    return server
}

function registerPlatformTools({ server, mcp, platformId, userId, clientKey, selectionScope, resolveProjectMcp, billing, log }: {
    server: McpServer
    mcp: PopulatedMcpServer
    platformId: string
    userId: string
    clientKey: McpOAuthClientKey | null
    selectionScope: ProjectSelectionScope
    resolveProjectMcp: (projectId: string) => Promise<McpServerSchema>
    billing: McpCallBilling
    log: FastifyBaseLogger
}): void {
    const contextTool = apSetProjectContextTool({ platformId, userId, selectionScope, log })
    server.registerTool(contextTool.title, buildToolConfig(contextTool), (args: Record<string, unknown>) => withMcpReach({ execute: withCallBilling({ execute: contextTool.execute, toolName: contextTool.title, projectId: null, billing }), toolTitle: contextTool.title, platformId, userId, log })(args))

    const templateMcp: ProjectScopedMcpServer = { ...mcp, projectId: platformId }
    const tools = filterEnabledTools({ tools: activepiecesTools(templateMcp, userId, log), disabledTools: mcp.disabledTools })

    tools.forEach((tool) => {
        if (PLATFORM_LEVEL_TOOL_SET.has(tool.title)) {
            server.registerTool(tool.title, buildToolConfig(tool), (args: Record<string, unknown>) => withMcpReach({ execute: withCallBilling({ execute: tool.execute, toolName: tool.title, projectId: null, billing }), toolTitle: tool.title, platformId, userId, log })(args))
            return
        }

        server.registerTool(tool.title, buildToolConfig(tool), async (args: Record<string, unknown>) => {
            const selectedProjectId = await mcpProjectSelection.get(selectionScope)
            if (isNil(selectedProjectId)) {
                return noProjectSelectedResult()
            }
            const activityContext: McpActivityContext = { platformId, projectId: selectedProjectId, userId, clientKey }
            const recordedExecute = withActivityRecording({
                execute: (toolArgs: Record<string, unknown>) => executeInSelectedProject({ toolTitle: tool.title, args: toolArgs, projectId: selectedProjectId, userId, resolveProjectMcp, billing, log }),
                tool,
                resolveContext: () => Promise.resolve(activityContext),
                log,
            })
            return recordedExecute(args)
        })
    })
}

async function executeInSelectedProject({ toolTitle, args, projectId, userId, resolveProjectMcp, billing, log }: {
    toolTitle: string
    args: Record<string, unknown>
    projectId: string
    userId: string
    resolveProjectMcp: (projectId: string) => Promise<McpServerSchema>
    billing: McpCallBilling
    log: FastifyBaseLogger
}): Promise<McpToolResult> {
    const projectMcp = await resolveProjectMcp(projectId)
    const projectScopedMcp: ProjectScopedMcpServer = { ...projectMcp, projectId }
    const permissionChecker = await resolveMcpPermissionChecker({ userId, projectId, log })
    const realTools = activepiecesTools(projectScopedMcp, userId, log)
    const realTool = realTools.find(t => t.title === toolTitle)
    if (isNil(realTool)) {
        return deny(`Tool "${toolTitle}" is not available for this project.`)
    }
    const execute = permissionChecker.wrapExecute({
        execute: isToolEnabled({ toolTitle: realTool.title, disabledTools: projectMcp.disabledTools })
            ? withCallBilling({ execute: realTool.execute, toolName: realTool.title, projectId, billing })
            : async () => toolSwitchedOffResult(realTool.title),
        permission: realTool.permission,
        toolTitle: realTool.title,
    })
    return execute(args)
}

function withMcpReach({ execute, toolTitle, platformId, userId, log }: {
    execute: McpToolDefinition['execute']
    toolTitle: string
    platformId: string
    userId: string
    log: FastifyBaseLogger
}): McpToolDefinition['execute'] {
    return async (args) => {
        const reachesMcp = await mcpAccess.hasMcpReach({ platformId, userId, log })
        if (!reachesMcp) {
            return mcpAccess.noMcpReachResult(toolTitle)
        }
        return execute(args)
    }
}

function filterEnabledTools({ tools, disabledTools }: {
    tools: McpToolDefinition[]
    disabledTools: string[] | null
}): McpToolDefinition[] {
    return tools.filter(tool => isToolEnabled({ toolTitle: tool.title, disabledTools }))
}

function isToolEnabled({ toolTitle, disabledTools }: {
    toolTitle: string
    disabledTools: string[] | null
}): boolean {
    return LOCKED_TOOL_NAMES.includes(toolTitle) || !(disabledTools ?? []).includes(toolTitle)
}

function toolSwitchedOffResult(toolTitle: string): McpToolResult {
    return deny(`Tool "${toolTitle}" is switched off for the selected project by an admin. Do not retry it here. Ask the user to switch it on, or call ${SET_PROJECT_CONTEXT_TOOL_NAME} to select a project where it is on.`)
}

function noProjectSelectedResult(): McpToolResult {
    return deny(`No project selected. Use ${SET_PROJECT_CONTEXT_TOOL_NAME} to select a project first.`)
}

function registerFlowTools({ server, mcp, projectId, permissionChecker, billing, log }: RegisterToolsParams): void {
    const enabledFlows = mcp.flows.filter((flow) => flow.status === FlowStatus.ENABLED)
    for (const flow of enabledFlows) {
        const { toolName: mcpToolNameInput, toolDescription, mcpInputs, returnsResponse } = extractMcpTriggerInput(flow)
        const zodFromInputSchema = mcpToolInput.modelInputShape({ properties: mcpInputs })

        const baseName = (mcpToolNameInput ?? flow.version.displayName) + '_' + flow.id.substring(0, 4)
        const toolName = mcpToolNameUtils.createToolName(baseName)

        const flowPermissionError = permissionChecker.check(Permission.WRITE_RUN, toolName)
        server.registerTool(toolName, { title: toolName, description: toolDescription, inputSchema: zodFromInputSchema, annotations: FLOW_TOOL_ANNOTATIONS }, async (args: Record<string, unknown>) => {
            if (flowPermissionError) {
                return flowPermissionError
            }
            const refusal = await billing.refusalWhenOutOfCredits({ toolName })
            if (!isNil(refusal)) {
                return refusal
            }

            const result = await runFlowAsTool({ flow, properties: mcpInputs, payload: args, returnsResponse, log })

            rejectedPromiseHandler(telemetry(log).trackProject({
                projectId,
                event: {
                    name: TelemetryEventName.MCP_TOOL_CALLED,
                    payload: { mcpId: projectId, toolName },
                },
            }), log)

            return result
        })
    }
}

export function extractMcpTriggerInput(flow: PopulatedFlow): { toolName?: string, toolDescription: string, mcpInputs: McpProperty[], returnsResponse: boolean } {
    const mcpTrigger = flow.version.trigger.settings as McpTrigger
    return {
        toolName: mcpTrigger.input?.toolName,
        toolDescription: mcpTrigger.input?.toolDescription ?? '',
        mcpInputs: mcpTrigger.input?.inputSchema ?? [],
        returnsResponse: mcpTrigger.input?.returnsResponse ?? false,
    }
}

export async function resolveRunnableFlow({ flow, projectId, log }: {
    flow: PopulatedFlow
    projectId: string
    log: FastifyBaseLogger
}): Promise<PopulatedFlow> {
    if (isNil(flow.publishedVersionId) || flow.publishedVersionId === flow.version.id) {
        return flow
    }
    return flowService(log).getOnePopulatedOrThrow({ id: flow.id, projectId, versionId: flow.publishedVersionId })
}

export async function runFlowAsTool({ flow, properties, payload, returnsResponse, log }: {
    flow: PopulatedFlow
    properties: McpProperty[]
    payload: Record<string, unknown>
    returnsResponse: boolean
    log: FastifyBaseLogger
}): Promise<McpToolResult> {
    const flowId = flow.id
    const flowDisplayName = flow.version.displayName
    const response = await webhookService.handleWebhook({
        data: () => Promise.resolve({
            body: {},
            method: 'POST',
            headers: {},
            queryParams: {},
        }),
        logger: log,
        flowId,
        async: !returnsResponse,
        flowVersionToRun: WebhookFlowVersionToRun.LOCKED_FALL_BACK_TO_LATEST,
        saveSampleData: false,
        payload: mcpToolInput.toFlowPayload({ properties, modelArgs: payload }),
        execute: true,
        failParentOnFailure: false,
        timeoutMs: system.getNumberOrThrow(AppSystemProp.FLOW_TIMEOUT_SECONDS) * 1000,
    })
    const isOkay = Math.floor(response.status / 100) === 2

    const text = isOkay
        ? `✅ Successfully executed flow ${flowDisplayName}\n\nOutput:\n\`\`\`json\n${JSON.stringify(response, null, 2)}\n\`\`\``
        : `❌ Error executing flow ${flowDisplayName}\n\nError details:\n\`\`\`json\n${JSON.stringify(response, null, 2) || 'Unknown error occurred'}\n\`\`\``

    return { content: [{ type: 'text', text }], ...(isOkay ? {} : { isError: true }) }
}

function registerStaticTools({ server, mcp, projectId, userId, platformDisabledTools, permissionChecker, activityContext, billing, log }: RegisterStaticToolsParams): void {
    const tools = filterEnabledTools({
        tools: activepiecesTools({ ...mcp, projectId }, userId, log),
        disabledTools: [...(mcp.disabledTools ?? []), ...platformDisabledTools],
    })

    tools.forEach((tool) => {
        const execute = permissionChecker.wrapExecute({
            execute: withCallBilling({ execute: tool.execute, toolName: tool.title, projectId, billing }),
            permission: tool.permission,
            toolTitle: tool.title,
        })
        const recordedExecute = withActivityRecording({ execute, tool, resolveContext: () => Promise.resolve(activityContext), log })
        server.registerTool(tool.title, buildToolConfig(tool), (args: Record<string, unknown>) => recordedExecute(args))
    })
}

function registerPlaceholderTools(server: McpServer): void {
    const lockedToolSet = new Set<string>(LOCKED_TOOL_NAMES)
    const allToolNames = [...LOCKED_TOOL_NAMES, ...ALL_CONTROLLABLE_TOOL_NAMES]
    allToolNames.forEach((toolName) => {
        server.registerTool(toolName, {
            title: toolName,
            description: `${toolName} — requires a project to be selected first.`,
            annotations: lockedToolSet.has(toolName) ? LOCKED_PLACEHOLDER_ANNOTATIONS : CONTROLLABLE_PLACEHOLDER_ANNOTATIONS,
        }, async () => ({
            content: [{ type: 'text' as const, text: `No project selected. Please select a project from the dropdown in the chat input area before using ${toolName}.` }],
        }))
    })
}

function registerEmptyResourcesAndPrompts(server: McpServer): void {
    server.registerResource(
        '_',
        new ResourceTemplate('activepieces://empty', {
            list: async () => ({ resources: [] }),
        }),
        {},
        async () => ({ contents: [] }),
    )
    server.registerPrompt('_', {}, () => ({ messages: [] }))
}

function buildToolConfig(tool: McpToolDefinition): Record<string, unknown> {
    return {
        title: tool.title,
        description: tool.description,
        inputSchema: tool.inputSchema,
        annotations: tool.annotations,
    }
}

export const FLOW_TOOL_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
export const LOCKED_PLACEHOLDER_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
export const CONTROLLABLE_PLACEHOLDER_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
export const MCP_MAX_TOOL_INPUT_ELEMENTS = 50_000

type RegisterToolsParams = {
    server: McpServer
    mcp: PopulatedMcpServer
    projectId: string
    permissionChecker: PermissionChecker
    billing: McpCallBilling
    log: FastifyBaseLogger
}

type RegisterStaticToolsParams = RegisterToolsParams & {
    userId?: string
    platformDisabledTools: string[]
    activityContext: McpActivityContext | null
}