Cómo conectar Activepieces con MCP paso a paso

Conectar Activepieces con MCP permite utilizar un asistente de inteligencia artificial para crear, revisar y probar automatizaciones mediante lenguaje natural. En lugar de construir manualmente cada paso desde el editor visual, puedes pedirle al asistente que examine las integraciones disponibles, configure un borrador y detecte errores antes de publicarlo.

Activepieces incorpora su propio servidor compatible con el Model Context Protocol. Este servidor funciona como una interfaz estandarizada entre la plataforma de automatización y clientes como Claude Desktop, Claude.ai, Cursor o Windsurf.

La integración actual va bastante más allá de exponer unas cuantas acciones. El asistente puede consultar la estructura de los flujos, buscar acciones y disparadores, administrar tablas, analizar ejecuciones fallidas y, si le concedes los permisos correspondientes, modificar o publicar automatizaciones completas.

Qué permite hacer el servidor MCP de Activepieces

El servidor MCP de Activepieces permite que un asistente compatible trabaje sobre un proyecto de la plataforma. Su función principal no es sustituir el motor de automatización, sino proporcionar al modelo un conjunto controlado de herramientas para examinar y administrar flujos mediante una conversación.

Por ejemplo, puedes pedirle que haga lo siguiente:

• Enumere los flujos existentes y compruebe cuáles están habilitados.
• Lea la estructura y la configuración de una automatización.
• Busque una acción adecuada para una tarea determinada.
• Cree un flujo completo con su disparador y sus acciones.
• Añada condiciones, bucles o ramas a un flujo existente.
• Valide la configuración antes de publicarla.
• Pruebe pasos individuales y examine sus resultados.
• Revise ejecuciones fallidas y explique el error encontrado.
• Cree y modifique tablas o registros de Activepieces.

También puede descubrir acciones pertenecientes a las diferentes Pieces de la plataforma. Una Piece es la integración que reúne los disparadores y las acciones disponibles para un servicio, como Gmail, Slack, Google Sheets o HubSpot.

Esto no debe confundirse con los agentes nativos de Activepieces. Un agente creado dentro de la plataforma forma parte de una automatización y utiliza un modelo para tomar decisiones durante la ejecución. El servidor MCP, en cambio, permite que un asistente externo construya, inspeccione o administre el proyecto.

Qué necesitas para conectar Activepieces con MCP

Antes de comenzar, comprueba que dispones de los siguientes elementos:

• Una cuenta de Activepieces Cloud o una instalación autogestionada actualizada.
• Un proyecto sobre el que tengas permisos suficientes.
• Un cliente compatible con servidores MCP remotos.
• Una dirección pública con HTTPS si Activepieces está alojado en tu servidor.
• Las conexiones necesarias configuradas dentro del proyecto.

No necesitas instalar Node.js ni ejecutar un servidor MCP independiente. Activepieces ya incorpora el endpoint necesario y proporciona una dirección similar a esta:

https://tu-instancia.example.com/mcp

Si utilizas aplicaciones como Slack, Google Drive o un CRM, configura primero sus conexiones desde la interfaz de Activepieces. El asistente podrá seleccionar una conexión existente, pero no recibirá su contraseña, clave de API ni token OAuth.

Cómo activar el servidor MCP de Activepieces

El servidor se activa desde la configuración del proyecto:

1. Inicia sesión en Activepieces.
2. Abre el proyecto que quieres conectar.
3. Entra en Settings.
4. Selecciona MCP Server.
5. Activa el servidor mediante el interruptor correspondiente.
6. Revisa las categorías de herramientas permitidas.
7. Copia la dirección mostrada en Server URL.

Las autorizaciones se aplican por proyecto. Esto permite conectar un asistente a un espacio de pruebas sin concederle acceso a los flujos utilizados en producción.

Para una primera conexión, resulta prudente dejar habilitadas solamente las herramientas de consulta. Podrás activar la creación, las pruebas o la publicación cuando hayas comprobado cómo se comporta el cliente.

Cómo conectar Claude Desktop, Cursor o Windsurf

Los clientes que admiten servidores MCP remotos pueden utilizar directamente la URL proporcionada por Activepieces. La estructura general de configuración es la siguiente:

{
  "mcpServers": {
    "activepieces": {
      "url": "https://tu-instancia.example.com/mcp"
    }
  }
}

La ubicación del archivo o del ajuste depende del cliente:

Cliente	Ubicación de la configuración
Cursor	.cursor/mcp.json para el proyecto o ~/.cursor/mcp.json globalmente
Claude Desktop en Windows	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop en macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windsurf	Ajustes MCP dentro de las preferencias del editor
Claude.ai	Organization Settings > Connectors > Add > Custom connector

Después de guardar la configuración, reinicia el cliente si fuera necesario. Durante la primera conexión se abrirá una ventana del navegador para completar la autorización OAuth con Activepieces.

Inicia sesión, selecciona el proyecto correcto y concede el acceso solicitado. El cliente almacenará un token de autorización; no es necesario copiar manualmente una clave de API en el archivo de configuración.

Las guías antiguas pueden mostrar un comando parecido a npx mcp-remote y una dirección terminada en /sse. Esa configuración correspondía a una implementación anterior. En los clientes actuales compatibles debes utilizar directamente la URL terminada en /mcp.

Qué herramientas puede utilizar el asistente

Activepieces organiza sus herramientas MCP en varias categorías. Las herramientas de Discovery son de solo lectura y permanecen siempre disponibles. Las categorías capaces de modificar datos se pueden habilitar o deshabilitar en cada proyecto.

Categoría	Qué permite hacer
Discovery	Consultar flujos, conexiones, Pieces, tablas, ejecuciones y errores de validación.
Flow Management	Crear, duplicar, renombrar, publicar, habilitar, deshabilitar o eliminar flujos.
Flow Building	Añadir, actualizar y eliminar disparadores o acciones.
Router & Branching	Crear y modificar ramas condicionales.
Annotations	Añadir y administrar notas dentro del lienzo.
Tables	Crear tablas, campos y registros, además de modificarlos o eliminarlos.
Testing & Runs	Probar flujos, ejecutar acciones, revisar resultados y reintentar ejecuciones fallidas.

Algunas operaciones tienen consecuencias importantes. La herramienta para eliminar un flujo borra también sus versiones y no permite deshacer la operación. Del mismo modo, ejecutar una acción puede enviar un correo, modificar un registro o publicar contenido utilizando una conexión real.

Por este motivo, no conviene habilitar todas las categorías automáticamente. Concede únicamente las capacidades que necesita el asistente para la tarea actual.

Cómo crear un flujo de Activepieces mediante lenguaje natural

Una vez establecida la conexión, puedes describir la automatización que necesitas. Cuanto más precisa sea la instrucción, menos decisiones ambiguas tendrá que tomar el modelo.

Por ejemplo:

Crea un borrador deshabilitado que se ejecute de lunes a viernes a las 9:00, consulte los registros pendientes de una tabla de Activepieces y envíe un resumen a Slack. Utiliza solamente las conexiones existentes. Valida y prueba el flujo, pero no lo publiques.

El proceso habitual debería seguir este orden:

1. Examinar el proyecto: el asistente consulta los flujos, tablas y conexiones disponibles.
2. Buscar las herramientas: identifica el disparador y las acciones que mejor encajan.
3. Revisar sus propiedades: obtiene los campos obligatorios y las opciones admitidas.
4. Crear el borrador: construye el disparador y los pasos en el orden adecuado.
5. Validar la estructura: comprueba referencias, ramas vacías y campos incompletos.
6. Realizar una prueba: ejecuta el flujo o determinados pasos con datos controlados.
7. Revisar los resultados: muestra las entradas, salidas, tiempos y posibles errores.
8. Publicar y habilitar: realiza estas acciones únicamente después de tu confirmación.

Activepieces puede crear un flujo completo mediante una sola operación, pero eso no significa que debas publicarlo sin revisarlo. Abre el enlace devuelto por el asistente y comprueba visualmente las conexiones, las expresiones y los campos utilizados.

Si falta una conexión, el asistente puede indicarte dónde configurarla, pero tendrás que completar la autorización desde la interfaz de Activepieces. Este diseño ayuda a conectar agentes de IA a sistemas internos sin exponer credenciales.

Cómo funciona la búsqueda de acciones y disparadores

La función Tool Search permite que el asistente describa una tarea, como “enviar un mensaje a un canal de Slack”, y reciba las acciones más relevantes del catálogo.

El flujo de descubrimiento tiene tres fases:

1. Descubrir: busca acciones o disparadores mediante una descripción natural.
2. Inspeccionar: obtiene el esquema completo y los campos de la opción elegida.
3. Ejecutar o construir: utiliza la acción una vez o la incorpora a un flujo persistente.

Tool Search se encuentra habilitado en Activepieces Cloud. En instalaciones autogestionadas debes activarlo mediante esta variable:

AP_TOOL_SEARCH_ENABLED=true

El cambio se lee dinámicamente y no requiere reiniciar la instancia. Para obtener resultados semánticos, Activepieces necesita además un modelo de embeddings y una base de datos PostgreSQL con la extensión pgvector.

Puedes proporcionar la clave utilizada para los embeddings mediante:

AP_OPENAI_API_KEY=tu_clave

También puedes configurar OpenAI como proveedor desde la administración de la plataforma. Si no existe un modelo de embeddings disponible o falla la indexación semántica, Tool Search continúa funcionando mediante coincidencias por palabras clave.

Cómo proteger el acceso MCP de Activepieces

El servidor utiliza OAuth, limita las operaciones al proyecto autorizado y no devuelve al cliente las claves o tokens almacenados. Sin embargo, proteger los secretos no elimina todos los riesgos: un asistente con herramientas de ejecución puede usar indirectamente esas credenciales para realizar acciones reales.

Aplica estas medidas antes de utilizar MCP con automatizaciones importantes:

• Crea un proyecto independiente para las primeras pruebas.
• Activa solamente las categorías de herramientas imprescindibles.
• Utiliza cuentas de aplicación con permisos mínimos.
• No permitas publicar, borrar o habilitar flujos si no resulta necesario.
• Solicita confirmación antes de enviar mensajes o modificar datos externos.
• Comprueba manualmente la estructura antes de publicar un borrador.
• Revisa las ejecuciones y los registros después de cada cambio importante.
• Revoca la autorización OAuth si el dispositivo o el cliente deja de utilizarse.

Para procesos financieros, cambios en CRM, comunicaciones externas o eliminación de información, conviene añadir aprobación humana al flujo de IA. El modelo puede preparar la operación, pero una persona debe autorizar el último paso.

El autoalojamiento permite mantener Activepieces dentro de tu infraestructura, pero no garantiza automáticamente el cumplimiento normativo. La seguridad final también depende del proxy, la base de datos, los permisos, las copias de seguridad y las políticas de la organización.

Cómo configurar MCP detrás de un proxy inverso

En una instalación autogestionada, la dirección pública de Activepieces debe ser accesible desde el cliente MCP y disponer de HTTPS válido. Si la instancia se publica en la raíz de un dominio, el endpoint habitual será:

https://automatizacion.example.com/mcp

Cuando Activepieces se encuentra bajo una subruta, debes incluirla en AP_FRONTEND_URL:

AP_FRONTEND_URL=https://automatizacion.example.com/activepieces

En este caso, el servidor MCP quedará disponible en:

https://automatizacion.example.com/activepieces/mcp

El proxy debe reenviar tanto el tráfico de Activepieces como los endpoints utilizados durante la autorización OAuth. Algunos clientes buscan las rutas /.well-known/oauth-* directamente en la raíz del dominio. Si el cliente ignora la cabecera de descubrimiento, tendrás que crear una regla adicional para reenviar esas rutas.

No expongas directamente un contenedor de pruebas mediante HTTP. Utiliza un dominio estable, TLS y una configuración correcta de AP_FRONTEND_URL, ya que una discrepancia entre la dirección interna y la pública puede romper la redirección OAuth.

Errores frecuentes al conectar Activepieces con MCP

El cliente intenta utilizar mcp-remote o una dirección terminada en /sse

Estás siguiendo una guía correspondiente a una versión anterior. El servidor actual se configura mediante su URL remota terminada en /mcp. Elimina el comando antiguo y vuelve a registrar el servidor.

La opción MCP Server no está activada

Entra en Settings > MCP Server, activa el servicio y copia nuevamente la dirección. Comprueba también que estás trabajando en el proyecto correcto.

La autorización OAuth entra en un bucle

Verifica que la dirección pública coincida exactamente con AP_FRONTEND_URL. Si utilizas una subruta, revisa las reglas del proxy y los endpoints de descubrimiento OAuth.

El asistente solamente puede leer los flujos

Las herramientas de Discovery son de solo lectura. Habilita expresamente Flow Management, Flow Building u otra categoría necesaria desde la configuración MCP del proyecto.

No aparecen las herramientas de búsqueda de acciones

En una instancia autogestionada, comprueba que AP_TOOL_SEARCH_ENABLED=true. Si la búsqueda funciona pero solo encuentra coincidencias literales, revisa el proveedor de embeddings y la disponibilidad de pgvector.

El asistente encuentra una acción, pero no puede ejecutarla

La integración puede necesitar una conexión que todavía no existe o que se encuentra en estado de error. Abre Activepieces, configura la conexión desde la interfaz y vuelve a solicitar la ejecución.

El asistente trabaja sobre el proyecto equivocado

Pídele que muestre los proyectos disponibles y establezca explícitamente el contexto correcto. Las operaciones posteriores quedarán limitadas a ese proyecto.

El flujo está creado, pero no se ejecuta

Comprueba si permanece como borrador, si ha sido publicado y si su estado es Enabled. Revisa también que el disparador tenga una muestra válida y que todas las conexiones estén activas.

Una prueba funciona, pero la ejecución real falla

Consulta el historial de ejecuciones y abre el resultado de cada paso. La prueba puede haber utilizado datos de ejemplo diferentes a los recibidos posteriormente por el disparador real.

El asistente ha preparado una acción demasiado arriesgada

No la ejecutes directamente. Reduce las categorías permitidas, modifica el prompt para exigir confirmación y añade una etapa de aprobación humana antes de cualquier operación irreversible.

Conectar Activepieces con MCP convierte al asistente en una interfaz para construir y mantener automatizaciones, pero no le concede acceso ilimitado por defecto. El servidor separa las herramientas de consulta de las capacidades de escritura y mantiene las credenciales dentro del proyecto.

La configuración recomendada consiste en activar el servidor MCP, copiar su URL, autorizar el cliente mediante OAuth y comenzar únicamente con herramientas de lectura. Después puedes habilitar progresivamente la construcción, las pruebas y la publicación, revisando cada flujo antes de utilizarlo con datos o cuentas reales.