Schritt-für-Schritt-Anleitung zum Verbinden von Activepieces mit MCP

Durch die Verbindung von Activepieces mit MCP können Sie einen KI-Assistenten verwenden, um Automatisierungen mithilfe natürlicher Sprache erstellen, überprüfen und testen.Anstatt jeden Schritt manuell im visuellen Editor zu erstellen, können Sie den Assistenten bitten, die verfügbaren Integrationen zu prüfen, einen Entwurf einzurichten und Fehler vor der Veröffentlichung zu erkennen.

Activepieces verfügt über einen eigenen Server, der mit dem ModellkontextprotokollDieser Server fungiert als standardisierte Schnittstelle zwischen der Automatisierungsplattform und Clients wie Claude Desktop, Claude.ai, Cursor oder Windsurf.

Die aktuelle Integration geht weit über die bloße Bereitstellung einiger weniger Aktionen hinaus. Der Assistent kann die Ablaufstruktur abfragen, nach Aktionen und Auslösern suchen, Tabellen verwalten, fehlgeschlagene Ausführungen analysieren und, sofern Sie ihm die entsprechenden Berechtigungen erteilen, vollständige Automatisierungen modifizieren oder veröffentlichen.

Was ermöglicht Ihnen der Activepieces MCP-Server?

Der Activepieces MCP-Server ermöglicht es einem kompatiblen Assistenten, innerhalb der Plattform an einem Projekt zu arbeiten. Seine Hauptfunktion besteht nicht darin, die Automatisierungs-Engine zu ersetzen, sondern dem Modell einen kontrollierten Satz von Werkzeugen bereitzustellen. Abläufe im Gespräch untersuchen und steuern.

Sie können es beispielsweise bitten, Folgendes zu tun:

• Listen Sie die vorhandenen Abläufe auf und prüfen Sie, welche aktiviert sind.
• Lesen Sie die Struktur und Konfiguration einer Automatisierung.
• Finden Sie die passende Vorgehensweise für die jeweilige Aufgabe.
• Erstellen Sie einen vollständigen Ablauf mit Auslöser und Aktionen.
• Fügen Sie einem bestehenden Ablauf Bedingungen, Schleifen oder Verzweigungen hinzu.
• Überprüfen Sie die Konfiguration, bevor Sie sie veröffentlichen.
• Probieren Sie die einzelnen Schritte aus und überprüfen Sie Ihre Ergebnisse.
• Überprüfen Sie fehlgeschlagene Ausführungen und erläutern Sie den aufgetretenen Fehler.
• Erstellen und Bearbeiten von Activepieces-Tabellen oder -Datensätzen.

Sie können auch Aktien entdecken, die verschiedenen Unternehmen gehören. Stücke der Plattform. Ein Piece ist die Integration, die die für einen Dienst wie Gmail, Slack, Google Sheets oder HubSpot verfügbaren Trigger und Aktionen zusammenführt.

Dies sollte nicht verwechselt werden mit dem/der/dem native Agenten von ActivepiecesEin innerhalb der Plattform erstellter Agent ist Teil eines Automatisierungsprozesses und nutzt ein Modell, um während der Ausführung Entscheidungen zu treffen. Der MCP-Server hingegen ermöglicht es einem externen Assistenten, das Projekt zu erstellen, zu überprüfen oder zu verwalten.

Was Sie benötigen, um Activepieces mit MCP zu verbinden

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgende Dinge haben:

• Ein Activepieces Cloud-Konto oder eine aktualisierte, selbstverwaltete Installation.
• Ein Projekt, für das Sie über ausreichende Berechtigungen verfügen.
• Ein Client, der mit entfernten MCP-Servern kompatibel ist.
• Eine öffentliche Adresse mit HTTPS, falls Activepieces auf Ihrem Server gehostet wird.
• Die notwendigen Verbindungen wurden innerhalb des Projekts konfiguriert.

Sie müssen weder Node.js installieren noch einen separaten MCP-Server betreiben. Activepieces enthält bereits den erforderlichen Endpunkt und stellt eine Adresse bereit, die in etwa so aussieht:

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

Wenn Sie Anwendungen wie Slack, Google Drive oder ein CRM-System verwenden, konfigurieren Sie deren Verbindungen zunächst über die Activepieces-Oberfläche. Der Assistent kann eine bestehende Verbindung auswählen, aber Sie erhalten weder Ihr Passwort noch Ihren API-Schlüssel oder Ihr OAuth-Token..

So aktivieren Sie den Activepieces MCP-Server

Der Server wird über die Projekteinstellungen aktiviert:

1. Melde dich bei Activepieces an.
2. Öffnen Sie das Projekt, mit dem Sie eine Verbindung herstellen möchten.
3. Eingeben Einstellungen.
4. Wählen MCP-Server.
5. Aktivieren Sie den Server mit dem entsprechenden Schalter.
6. Überprüfen Sie die Kategorien der zulässigen Werkzeuge.
7. Kopieren Sie die angegebene Adresse in Server-URL.

Berechtigungen werden pro Projekt vergeben. Dadurch kann sich ein Assistent mit einer Testumgebung verbinden, ohne Zugriff auf die in der Produktion verwendeten Arbeitsabläufe zu erhalten.

Für die erste Verbindung empfiehlt es sich, nur die Abfragetools aktiviert zu lassen. Sie können das Erstellen, Testen oder Veröffentlichen aktivieren, sobald Sie das Verhalten des Clients überprüft haben.

So verbinden Sie Claude Desktop, Cursor oder Windsurf

Kunden, die Remote-MCP-Server unterstützen, können die von Activepieces bereitgestellte URL direkt verwenden. Die allgemeine Konfigurationsstruktur ist wie folgt:

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

Der Speicherort der Datei oder Einstellung hängt vom Client ab:

Kunde	Speicherort der Konfiguration
Cursor	.cursor/mcp.json für das Projekt oder ~/.cursor/mcp.json global
Claude Desktop unter Windows	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop auf macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windsurf	MCP-Einstellungen in den Editor-Voreinstellungen
Claude.ai	Organisationseinstellungen > Konnektoren > Hinzufügen > Benutzerdefinierter Konnektor

Nach dem Speichern der Einstellungen starten Sie den Client gegebenenfalls neu. Beim ersten Verbindungsaufbau öffnet sich ein Browserfenster, um die Einrichtung abzuschließen. OAuth-Autorisierung mit Activepieces.

Melden Sie sich an, wählen Sie das richtige Projekt aus und erteilen Sie die angeforderten Zugriffsrechte. Der Client speichert ein Autorisierungstoken; ein manuelles Kopieren eines API-Schlüssels in die Konfigurationsdatei ist nicht erforderlich.

Ältere Anleitungen enthalten möglicherweise einen ähnlichen Befehl wie npx mcp-remote und eine Adresse, die mit /sseDiese Konfiguration entsprach einer früheren Implementierung. Auf aktuellen kompatiblen Clients müssen Sie die folgende verwenden: URL endet mit /mcp.

Welche Hilfsmittel kann der Assistent verwenden?

Activepieces gliedert seine MCP-Tools in verschiedene Kategorien. Die Tools von Entdeckung Sie sind schreibgeschützt und bleiben stets verfügbar. Kategorien, die Daten ändern können, lassen sich in jedem Projekt aktivieren oder deaktivieren.

Kategorie	Was es Ihnen ermöglicht
Entdeckung	Ablaufdiagramme, Verbindungen, Komponenten, Tabellen, Ausführungen und Validierungsfehler anzeigen.
Durchflussmanagement	Flows erstellen, duplizieren, umbenennen, veröffentlichen, aktivieren, deaktivieren oder löschen.
Flow-Gestaltung	Trigger oder Aktionen hinzufügen, aktualisieren und löschen.
Router & Verzweigung	Bedingte Verzweigungen erstellen und bearbeiten.
Anmerkungen	Notizen innerhalb der Leinwand hinzufügen und verwalten.
Tabellen	Tabellen, Felder und Datensätze erstellen sowie diese ändern oder löschen.
Testläufe	Testabläufe, Aktionen ausführen, Ergebnisse überprüfen und fehlgeschlagene Ausführungen wiederholen.

Manche Vorgänge haben weitreichende Konsequenzen. Das Tool zum Löschen eines Workflows löscht beispielsweise auch dessen Versionen. Es erlaubt keine Rückgängigmachung des Vorgangs.Ebenso kann die Ausführung einer Aktion das Versenden einer E-Mail, das Ändern eines Datensatzes oder das Veröffentlichen von Inhalten über eine echte Verbindung ermöglichen.

Daher ist es nicht ratsam, alle Kategorien automatisch zu aktivieren. Gewähren Sie dem Assistenten nur die Berechtigungen, die er für die aktuelle Aufgabe benötigt.

Wie man einen Activepieces-Workflow mit natürlicher Sprache erstellt

Sobald die Verbindung hergestellt ist, können Sie die benötigte Automatisierung beschreiben. Je präziser die Anweisung, desto weniger mehrdeutige Entscheidungen muss das Modell treffen.

Zum Beispiel:

Erstellen Sie einen deaktivierten Entwurf, der von Montag bis Freitag um 9:00 Uhr ausgeführt wird, ausstehende Datensätze aus einer ActivePieces-Tabelle abfragt und eine Zusammenfassung an Slack sendet. Verwenden Sie ausschließlich bestehende Verbindungen. Validieren und testen Sie den Ablauf, veröffentlichen Sie ihn aber nicht.

Der übliche Ablauf sollte in dieser Reihenfolge erfolgen:

1. Untersuchen Sie das Projekt: Der Assistent prüft die verfügbaren Datenflüsse, Tabellen und Verbindungen.
2. Finden Sie die Werkzeuge: Identifizieren Sie den Auslöser und die am besten passenden Maßnahmen.
3. Überprüfen Sie die Eigenschaften: Ruft die erforderlichen Felder und die zulässigen Optionen ab.
4. Entwurf erstellen: Bauen Sie den Auslöser und die Schritte in der richtigen Reihenfolge auf.
5. Struktur prüfen: Überprüfen Sie Referenzen, leere Zweige und unvollständige Felder.
6. Machen Sie einen Test: führt den Ablauf oder bestimmte Schritte mit kontrollierten Daten aus.
7. Ergebnisse prüfen: Es zeigt die Eingaben, Ausgaben, Zeiten und mögliche Fehler an.
8. Veröffentlichen und aktivieren: Führen Sie diese Aktionen erst nach Ihrer Bestätigung durch.

ActivePieces kann einen kompletten Flow in einem einzigen Vorgang erstellen. Das bedeutet jedoch nicht, dass Sie ihn ohne vorherige Überprüfung veröffentlichen sollten. Öffnen Sie den vom Assistenten generierten Link und überprüfen Sie die Verbindungen, Ausdrücke und verwendeten Felder visuell.

Falls eine Verbindung fehlt, zeigt Ihnen der Assistent an, wo Sie diese konfigurieren können. Sie müssen den Autorisierungsprozess jedoch weiterhin über die Activepieces-Oberfläche abschließen. Dieses Design trägt dazu bei, Verbinden Sie KI-Agenten mit internen Systemen, ohne Anmeldeinformationen preiszugeben..

Wie die Aktions- und Auslösersuche funktioniert

Die Funktion Werkzeugsuche Es ermöglicht dem Assistenten, eine Aufgabe zu beschreiben, zum Beispiel „eine Nachricht an einen Slack-Kanal senden“, und die relevantesten Aktionen aus dem Katalog zu erhalten.

Der Entdeckungsprozess umfasst drei Phasen:

1. Entdecken: Suche nach Aktionen oder Auslösern mithilfe einer natürlichen Beschreibung.
2. Überprüfen: Es ruft das vollständige Schema und die Felder der gewählten Option ab.
3. Ausführen oder erstellen: Verwenden Sie die Aktion einmalig oder integrieren Sie sie in einen fortlaufenden Ablauf.

Die Werkzeugsuche ist in Activepieces Cloud aktiviert. Bei selbstverwalteten Installationen müssen Sie sie über diese Variable aktivieren:

AP_TOOL_SEARCH_ENABLED=true

Die Änderung wird dynamisch eingelesen und erfordert keinen Neustart der Instanz. Um semantische Ergebnisse zu erhalten, benötigt Activepieces außerdem ein Einbettungsmodell und eine PostgreSQL-Datenbank mit der entsprechenden Erweiterung. pgvector.

Sie können den für die Einbettungen verwendeten Schlüssel wie folgt angeben:

AP_OPENAI_API_KEY=tu_clave

Sie können OpenAI auch über die Plattformadministration als Anbieter konfigurieren. Falls kein Einbettungsmodell verfügbar ist oder die semantische Indizierung fehlschlägt, funktioniert die Werkzeugsuche weiterhin. Übereinstimmungen mit Schlüsselwörtern.

Wie man den Zugriff auf Activepieces MCP schützt

Der Server verwendet OAuth, beschränkt Operationen auf das autorisierte Projekt und gibt keine gespeicherten Schlüssel oder Token an den Client zurück. Der Schutz von Geheimnissen beseitigt jedoch nicht alle Risiken: Ein Assistent mit Ausführungswerkzeugen kann Diese Anmeldeinformationen können indirekt verwendet werden. um konkrete Handlungen durchzuführen.

Wenden Sie diese Maßnahmen an, bevor Sie MCP mit umfangreichen Automatisierungen verwenden:

• Erstellen Sie ein separates Projekt für erste Tests.
• Aktivieren Sie nur die wichtigsten Werkzeugkategorien.
• Verwenden Sie App-Konten mit minimalen Berechtigungen.
• Das Veröffentlichen, Löschen oder Aktivieren von Abläufen sollte nur dann erlaubt werden, wenn dies unbedingt erforderlich ist.
• Vor dem Senden von Nachrichten oder dem Ändern externer Daten ist eine Bestätigung anzufordern.
• Die Struktur sollte vor der Veröffentlichung eines Entwurfs manuell überprüft werden.
• Überprüfen Sie die Ausführungen und Protokolle nach jeder größeren Änderung.
• Die OAuth-Autorisierung sollte widerrufen werden, wenn das Gerät oder der Client nicht mehr verwendet wird.

Bei Finanzprozessen, CRM-Änderungen, externer Kommunikation oder Datenlöschung ist es ratsam Fügen Sie dem KI-Workflow eine menschliche Genehmigung hinzu.Das Modell kann die Operation vorbereiten, aber eine Person muss den letzten Schritt autorisieren.

Durch Self-Hosting können Sie Activepieces innerhalb Ihrer Infrastruktur betreiben, aber garantiert nicht automatisch die Einhaltung gesetzlicher BestimmungenDie ultimative Sicherheit hängt auch von Proxy, Datenbank, Berechtigungen, Backups und Organisationsrichtlinien ab.

Wie konfiguriert man MCP hinter einem Reverse-Proxy?

Bei einer selbstverwalteten Installation muss die öffentliche Adresse von Activepieces vom MCP-Client aus erreichbar sein und über gültiges HTTPS verfügen. Wenn die Instanz im Stammverzeichnis einer Domäne veröffentlicht ist, lautet der typische Endpunkt:

https://automatizacion.example.com/mcp

Wenn Activepieces unter einer Unterroute liegt, müssen Sie es einbeziehen in AP_FRONTEND_URL:

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

In diesem Fall ist der MCP-Server unter folgender Adresse erreichbar:

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

Der Proxy muss sowohl den Activepieces-Datenverkehr als auch die während der OAuth-Autorisierung verwendeten Endpunkte weiterleiten. Einige Clients suchen nach Routen. /.well-known/oauth-* direkt im Stammverzeichnis der Domain. Wenn der Client den Discovery-Header ignoriert, müssen Sie eine zusätzliche Regel erstellen, um diese Routen weiterzuleiten.

Stellen Sie einen Testcontainer nicht direkt über HTTP bereit. Verwenden Sie eine stabile Domain, TLS und eine korrekte Konfiguration. AP_FRONTEND_URLda eine Diskrepanz zwischen der internen und der öffentlichen Adresse die OAuth-Umleitung unterbrechen kann.

Häufige Fehler beim Verbinden von Activepieces mit MCP

Der Client versucht, mcp-remote oder eine Adresse, die auf /sse endet, zu verwenden.

Sie folgen einer Anleitung für eine ältere Version. Der aktuelle Server ist über seine Remote-URL mit der Endung .com konfiguriert. /mcpEntfernen Sie den alten Befehl und registrieren Sie den Server neu.

Die MCP-Server-Option ist nicht aktiviert.

Eingeben Einstellungen > MCP-ServerAktivieren Sie den Dienst und kopieren Sie die Adresse erneut. Überprüfen Sie außerdem, ob Sie am richtigen Projekt arbeiten.

Die OAuth-Autorisierung gerät in eine Schleife

Überprüfen Sie, ob die öffentliche Adresse exakt übereinstimmt. AP_FRONTEND_URLWenn Sie eine Unterroute verwenden, überprüfen Sie die Proxy-Regeln und die OAuth-Erkennungsendpunkte.

Der Assistent kann nur die Datenflüsse lesen.

Die Erkennungstools sind schreibgeschützt. Sie müssen explizit aktiviert werden. Durchflussmanagement, Flow-Gestaltung oder eine andere Kategorie, die in der MCP-Konfiguration des Projekts vorgesehen ist.

Die Aktiensuchfunktionen werden nicht angezeigt.

Überprüfen Sie in einer selbstverwalteten Instanz Folgendes: AP_TOOL_SEARCH_ENABLED=trueFalls die Suche funktioniert, aber nur wörtliche Übereinstimmungen findet, überprüfen Sie den Einbettungsanbieter und die Verfügbarkeit. pgvector.

Der Zauberer findet eine Aktion, kann sie aber nicht ausführen.

Für die Integration ist möglicherweise eine Verbindung erforderlich, die noch nicht besteht oder fehlerhaft ist. Öffnen Sie Activepieces, konfigurieren Sie die Verbindung über die Benutzeroberfläche und fordern Sie die Ausführung anschließend erneut an.

Der Assistent arbeitet am falschen Projekt.

Lassen Sie sich die verfügbaren Projekte anzeigen und legen Sie den korrekten Kontext explizit fest. Alle nachfolgenden Operationen sind auf dieses Projekt beschränkt.

Der Ablauf wurde erstellt, wird aber nicht ausgeführt.

Prüfen Sie, ob es sich noch um einen Entwurf handelt, ob es veröffentlicht wurde und ob sein Status „…“ lautet. ErmöglichtPrüfen Sie außerdem, ob der Trigger ein gültiges Sample enthält und ob alle Verbindungen aktiv sind.

Ein Test funktioniert, aber die eigentliche Ausführung schlägt fehl.

Überprüfen Sie den Ausführungsverlauf und öffnen Sie das Ergebnis jedes einzelnen Schritts. Der Test hat möglicherweise Beispieldaten verwendet, die sich von den Daten unterscheiden, die der eigentliche Trigger später empfangen hat.

Der Assistent hat eine zu riskante Aktion vorbereitet.

Führen Sie es nicht direkt aus. Reduzieren Sie die zulässigen Kategorien, ändern Sie die Eingabeaufforderung so, dass eine Bestätigung erforderlich ist, und fügen Sie vor jeder irreversiblen Operation eine manuelle Genehmigungsphase hinzu.

Durch die Verbindung von ActivePieces mit MCP wird der Assistent zu einer Benutzeroberfläche für die Erstellung und Wartung von Automatisierungen, allerdings wird standardmäßig kein uneingeschränkter Zugriff gewährt. Der Server trennt Abfragewerkzeuge von Schreibfunktionen und speichert Anmeldeinformationen innerhalb des Projekts.

Die empfohlene Einrichtung umfasst die Aktivierung des MCP-Servers, das Kopieren seiner URL, die Autorisierung des Clients via OAuth und den Start mit Tools im Nur-Lese-Modus. Anschließend können Sie schrittweise die Funktionen zum Erstellen, Testen und Veröffentlichen aktivieren und jeden Workflow überprüfen, bevor Sie ihn mit Live-Daten oder -Konten verwenden.