Erste Schritte mit KI-Coding-Agents
Am schnellsten verbinden Sie sich direkt in PlaidCloud: Öffnen Sie das Avatar-Menü (Benutzermenü), wählen Sie Ihre KI verbinden, wählen Sie den Client, den Sie verwenden, und folgen Sie den angezeigten Schritten – einschließlich der MCP-Server-URL Ihres Workspace, die bereits eingetragen ist. Das steht zur Verfügung, sobald in Ihrem Workspace die KI-Berechtigung aktiviert ist. Der Rest dieser Seite und die darauf folgenden Seiten zu den einzelnen Clients bleiben die Referenz – lesen Sie weiter, wenn Sie nicht in der Weboberfläche sind oder sich ein vollständiges Bild von der Authentifizierung und dem Funktionsumfang des Servers machen möchten.
Was ist der MCP-Server?
Abschnitt betitelt „Was ist der MCP-Server?“Das Model Context Protocol ist ein offener Standard, mit dem KI-Agents mit externen Werkzeugen und Daten kommunizieren können. PlaidCloud betreibt in jedem Workspace einen MCP-Server, der dieselben Kernfunktionen kapselt wie die REST-API – gruppiert nach Absicht (find, describe, upsert, run, organize), sodass sich ein Agent in der Oberfläche zurechtfindet, ohne über 1.000 Namen von RPC-Methoden auf niedriger Ebene laden zu müssen.
Der Server befindet sich unter:
https://<your-workspace>.plaid.cloud/mcpErsetzen Sie <your-workspace> durch die Subdomain Ihres Workspace (die, mit der Sie sich an der PlaidCloud-Oberfläche anmelden).
Was er bereitstellt
Abschnitt betitelt „Was er bereitstellt“Der Katalog deckt den größten Teil dessen ab, was ein Agent im Tagesgeschäft braucht:
- Projekte, Workflows, Schritte – find/describe/upsert/run/organize, einschließlich erneuter Ausführung einzelner Schritte und Versionsverlauf.
- Tabellen, Ansichten, Abfragen – Schema-Introspektion, Abfrageausführung, Exporte, Snapshots, Branches. Ansichten sind dieselben, die Sie in PlaidCloud sehen, ob Sie sie im Tabellen-Explorer erstellt haben oder ein Workflow sie erzeugt hat.
- Dimensionen – beschreiben, finden, upsert, versionieren, Elemente/Aliasse/Eigenschaften verwalten.
- Verbindungen – Verbindungen zu externen Systemen finden/upsert/testen.
- Lakehouse – Branches, Snapshots, Optimierungs-/Vacuum-Vorgänge.
- Identität – Mitglieder, Gruppen, Sitzungen, Verteiler.
- Dokumente, Dashboards, UDFs, Editoren, Agents, Veröffentlichungen – domänenspezifische Werkzeuge.
- Workflow-Migration – wandeln Sie in Document bereitgestellte Exporte von Alteryx (
alteryx_convert), KNIME (knime_convert), Prophecy (prophecy_convert) und Savant (savant_convert) in PlaidCloud-Workflows um und koordinieren Sie Migrationsarbeiten im Portfolio. - PlaidCloud-Dokumentation –
docs_searchfindet Seiten in der PlaidCloud-Dokumentation per Stichwort, unddocs_fetchliest eine Seite vollständig, sodass Ihr Agent prüfen kann, wie eine Funktion arbeitet, bevor er damit baut. - Workflow-Protokolle und Ausführungsverfolgung –
workflow_logs,workflow_run_status,workflow_job_track.
Jedes Werkzeug gibt einen einheitlichen Umschlag {ok, data, next_cursor?, total?} zurück; Fehler verwenden {ok: false, error: {code, retryable, message, hint?}}. Verändernde Vorgänge akzeptieren dry_run=True für eine Validierung als Planung ohne Schreiben.
Ergebnisse klein halten
Abschnitt betitelt „Ergebnisse klein halten“Werkzeugergebnisse sind der größte einzelne Verbraucher des Kontexts eines Agents, daher liefern die Werkzeuge find und describe standardmäßig einen bescheidenen Ausschnitt und lassen Sie ihn erweitern:
- Zeilen. Ein find liefert 25 Treffer pro Seite (
step_findliefert 50). Eine begrenzte Seite setztnext_cursor, und die find-Werkzeuge nennen zusätzlich die gekürzte Liste intruncated– beides bedeutet „es gibt mehr“, nicht „das waren alle“.totalmeldet immer die vollständige Anzahl. Erhöhen Sielimitoder blättern Sie mit dem Cursor. - Spalten. Übergeben Sie
fields=['id', 'name', 'update_time'], um nur diese Spalten zurückzubekommen. Ein Feldname, der in keinem Datensatz vorkommt, ist ein Fehler, der die verfügbaren Felder auflistet, keine stille Auslassung – ein Tippfehler schlägt also laut fehl, statt stillschweigend weniger zurückzugeben, als Sie angefordert haben. Werkzeuge, die kuratierte Sets anbieten, akzeptieren auchfield_set='minimal' | 'default' | 'full'; rufen Siemcp_introspectauf, um zu sehen, welche Parameter ein bestimmtes Werkzeug akzeptiert. - Anzahlen.
count_only=Truebemisst eine Ergebnismenge, ohne sie abzurufen.
Unbekannte Felder werden abgelehnt
Abschnitt betitelt „Unbekannte Felder werden abgelehnt“Die spec, die ein Werkzeug entgegennimmt, etwa die für project_upsert oder workflow_upsert, akzeptiert nur die aufgelisteten Felder. Ein nicht erkanntes Feld wird mit einem Fehler abgelehnt, der das Feld nennt, statt ignoriert zu werden und Sie erst später merken zu lassen, dass es nichts bewirkt hat. Korrigieren Sie den Namen und senden Sie die Anfrage erneut. workflow_upsert nimmt die Beschreibung eines Workflows als memo entgegen und akzeptiert description als anderen Namen dafür.
Anfragen bündeln
Abschnitt betitelt „Anfragen bündeln“mcp_batch bündelt mehrere Werkzeugaufrufe in einer Anfrage. Es nimmt höchstens 100 Aufrufe entgegen, führt eine begrenzte Anzahl davon gleichzeitig aus und kann nicht in einem anderen mcp_batch oder einem Rezept verschachtelt werden – listen Sie die Aufrufe stattdessen in einem flachen Batch auf, was beim Senden nicht mehr kostet. Ein Batch über dem Limit wird mit einer Meldung abgelehnt, die das Limit nennt, statt stillschweigend gekürzt zu werden; das Limit begrenzt die Arbeit, die eine einzelne Anfrage starten darf, nicht die Gesamtmenge, die Sie erledigen dürfen, teilen Sie eine größere Aufgabe also auf mehrere Batches auf.
Das Rezept paginate_through_listing stoppt nach 200 Seiten, egal wie hoch Sie max_pages setzen, und meldet partial: true, wenn es vorzeitig stoppt. Zusammen mit seinem Limit max_items endet ein einzelner Paginierungsaufruf damit immer.
Ein Rezept lehnt einen params-Schlüssel ab, den es nicht kennt, und die Meldung listet die Schlüssel auf, die das Rezept akzeptiert – ein falsch geschriebener optionaler Parameter schlägt also laut fehl, statt verworfen zu werden, wodurch der Aufruf stillschweigend eine andere Frage beantworten würde als die, die Sie gestellt haben. Rufen Sie mcp_recipes(name=...) auf, um die Schlüssel eines bestimmten Rezepts zu erhalten.
Spaltenorientierte Ergebnisse
Abschnitt betitelt „Spaltenorientierte Ergebnisse“Ein großes Ergebnis, dessen Zeilen alle dieselben Felder tragen, kommt spaltenorientiert zurück statt als Liste von Objekten, sodass die Feldnamen einmal gesendet werden statt einmal pro Zeile:
{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}Zeile i ist dict(zip(cols, rows[i])). Kleine Ergebnisse und jedes Ergebnis, dessen Zeilen nicht dieselben Felder teilen, bleiben gewöhnliche Arrays von Objekten – beide Formen kommen also vor, und Code, der diese Antworten direkt liest, sollte beide verarbeiten. Der Umschlag darum bleibt unverändert, und kein Wert wird unterwegs umgewandelt oder gerundet. Agents erfahren von dieser Form beim Verbinden und lesen sie ohne weiteres Zutun von Ihnen; die Ersparnis beträgt etwa 30 % der Zeichen und etwa 15 % des Lesebudgets eines Agents bei typischem Listenverkehr, also Kontext, der für Ihre eigentliche Frage übrig bleibt. (Die beiden Zahlen unterscheiden sich, weil sich wiederholende Feldnamen für ein Modell günstig zu lesen sind – die Zeichenersparnis ist immer die größere der beiden.)
Für den aktuellen Katalog richten Sie Ihren Agent auf den Server und rufen mcp_introspect ohne Argumente auf – das liefert die aktuelle Anzahl der Werkzeuge, Zusammenfassungen pro Domäne und Parametersignaturen. Verwenden Sie mcp_recipes für gängige Playbooks mit mehreren Werkzeugen (große Listen paginieren, Snapshot-dann-ändern, einen fehlgeschlagenen Schritt erneut ausführen usw.).
Labels und Ansichten
Abschnitt betitelt „Labels und Ansichten“Jedes Upsert-Werkzeug, das Labels setzt – für Tabellen, Workflows, Schritte, Projekte, Dimensionen, Ansichten, Editoren, UDFs, Verbindungen und Warehouses –, nimmt zwei Parameter entgegen: labels fügt Labels hinzu, und remove_labels entfernt sie. Andere Labels des Objekts bleiben bestehen. Entfernungen werden vor Ergänzungen angewendet, sodass ein Aufruf ein Label umbenennen kann:
{"remove_labels": ["01"], "labels": ["001"]}Das Entfernen eines Labels, das das Objekt nicht hat, bewirkt nichts.
Die Ansichtswerkzeuge arbeiten mit den Ansichten, die Sie in PlaidCloud sehen:
view_findlistet Ansichten auf, undview_describegibt eine anhand von ID oder Name zurück.view_upserterstellt eine Ansicht oder aktualisiert eine an Ort und Stelle. Eine Aktualisierung behält ID und Labels der Ansicht, und Sie können nur ihre Labels ändern, ohne die Abfrage erneut zu senden.view_organizelöscht, benennt um, dupliziert und verschiebt Ansichten.- Schreiben Sie Abfrageparameter als Platzhalter
%(name)s.
Ansichten teilen sich den Tabellenordnerbaum, verwenden Sie daher table_organize, um ihre Ordner zu verwalten.
Workflows aus nativen Schritten erstellen
Abschnitt betitelt „Workflows aus nativen Schritten erstellen“Sobald Ihre Daten in PlaidCloud liegen, wird Ihr Agent dazu angeleitet, jede Transformation aus nativen Tabellenschritten aufzubauen – Table Extract, den Join-Schritten, Table Melt, Table Union All und Table Lookup –, statt aus SQL extrahieren. Ein nativer Schritt setzt Ihre Variablen in seinen Filtern und Ausdrücken ein, und PlaidCloud erzeugt sein SQL für das Warehouse Ihres Projekts. Ein Schritt SQL extrahieren sendet seine Abfrage unverändert an das Warehouse: Er setzt keine Variablen ein, und sein SQL ist für ein einziges Warehouse geschrieben.
Ihr Agent kann eine Table-Extract-Konfiguration mit query_run(mode='config') ausprobieren – die Konfiguration, die er mit step_upsert speichern würde – und ihre Zeilen sehen, bevor er den Schritt speichert. Speichert er einen Schritt SQL extrahieren, liefert step_upsert in config_warnings einen Eintrag prefer_native_steps zurück, der die stattdessen zu verwendenden nativen Schritte nennt, und describe_step_operation enthält denselben Hinweis. SQL extrahieren bleibt verfügbar für alles, was kein nativer Schritt ausdrücken kann.
Aufgabenstarter
Abschnitt betitelt „Aufgabenstarter“Der Server liefert eine kleine Menge an Startern für die Aufgaben, nach denen Benutzer namentlich fragen. Ein Client, der MCP-Prompts unterstützt, listet sie auf und bietet sie als Menü an – in der Dokumentation Ihres Clients steht, wo er sie ablegt –, sodass Sie die Aufgabe auswählen, statt die Abfolge der Werkzeugaufrufe zu beschreiben:
| Starter | Was Sie angeben |
|---|---|
| CSV-Datei in eine Tabelle importieren | Die Datei und optional das Projekt, den Ordner mit der Datei und einen Namen für die neue Tabelle |
| Kostenänderung erklären | Die Ergebnistabelle und optional das Projekt und die beiden Perioden |
| Fehlgeschlagenen Workflow debuggen | Den Workflow und optional das Projekt |
| Projektdaten erkunden | Wonach Sie suchen, und optional das Projekt |
Jeder ist eine Startnachricht, kein Befehl: Ihr Agent liest sie und steuert dann die Werkzeuge selbst, sodass Sie sie bearbeiten oder das Gespräch von dort aus fortsetzen können.
Eine Datei importieren, ohne das Objektmodell zu kennen
Abschnitt betitelt „Eine Datei importieren, ohne das Objektmodell zu kennen“Der Import-Starter spart am meisten Arbeit, denn der naive Weg erfordert vier Werkzeuge in der richtigen Reihenfolge – das Dokumentenkonto finden, zur Datei navigieren, die Zieltabelle erstellen, dann den Import ausführen –, und eine falsche Vermutung bei einem davon beendet den Ablauf mehrere Aufrufe später.
Er liest getrennten Text – CSV, TSV und Ähnliches. Eine Excel-Arbeitsmappe oder eine Parquet-Datei wird abgelehnt, statt falsch gelesen zu werden; bringen Sie diese stattdessen mit dem passenden Import-Schritt in einem Workflow ein.
Stattdessen nimmt das Playbook bulk_import_csv das Konto anhand seines Namens und die Datei anhand ihres Namens oder Pfads entgegen:
mcp_recipe_run(name='bulk_import_csv', params={ 'project_id': '<project>', 'document_path': 'sales_2026.csv', 'document_account': 'Demo Data',})Es löst das Konto zu seiner Kennung auf, findet die Datei, erstellt die Tabelle mit den aus der Datei selbst gelesenen Spalten und Typen und lädt sie – Sie geben also weder eine Konto-ID noch eine Spaltenspezifikation an. table_name ist standardmäßig der Dateiname ohne Endung und table_path das Projektstammverzeichnis.
Geben Sie den Ordner an, wenn Sie ihn kennen – 'document_path': 'raw/sales_2026.csv' –, und die Suche wird darauf beschränkt. Eine in einem Ordner benannte Datei wird nur in diesem Ordner gefunden: Eine gleichnamige Datei weiter unten wird als Auswahl angeboten, statt anstelle der gewünschten importiert zu werden.
Ist ein Argument mehrdeutig, fragt das Ergebnis nach, statt zu raten:
{ "needs_choice": "document_account", "question": "More than one document account is named 'Archive'. Which one?", "candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]}Zeigen Sie die Kandidaten der Person, der Sie helfen, und rufen Sie das Playbook dann erneut mit ihrer Antwort auf, wobei Sie den Kandidaten genau so zurückgeben, wie er geliefert wurde. Wenn die Datei nicht gefunden werden kann, listet die Antwort stattdessen die nächstliegenden Namen auf und meldet, wie viele Dateien durchsucht wurden, sodass „nicht vorhanden“ von „nicht dort, wo ich gesucht habe“ unterschieden werden kann.
Authentifizierung
Abschnitt betitelt „Authentifizierung“Der MCP-Server von PlaidCloud akzeptiert zwei Authentifizierungswege:
- OAuth 2.1 + PKCE über Dynamic Client Registration (DCR). Das verwendet die Custom-Connector-Oberfläche von Claude.ai, und es ist auch der Standard der MCP-Brücke von Claude Code. Der Client registriert sich selbst und leitet Sie zur Keycloak-Anmeldung von PlaidCloud weiter. Nach der Anmeldung zeigt PlaidCloud eine Seite Application Access Request an, die die Anwendung und den Redirect-URI nennt, an den Anmeldedaten gesendet werden – genehmigen Sie sie einmal pro Autorisierung, um Ihr Token zu erhalten. Das ist eine Sicherheitskontrolle, keine Formalität: Prüfen Sie, dass Anwendungsname und Redirect-URI zu dem Client passen, mit dem Sie sich tatsächlich verbinden, und genehmigen Sie keine Anfrage, die Sie nicht selbst gestartet haben.
- Statisches Bearer-Token in einem
Authorization-Header. Für Agent-Laufzeiten, die keine nutzbare Browser-Weiterleitung haben oder ein langlebiges Token in einer Konfigurationsdatei wünschen. PlaidCloud stellt eine Hilfsseite bereit, die eines für Sie erzeugt (siehe unten).
Ein statisches Bearer-Token abrufen
Abschnitt betitelt „Ein statisches Bearer-Token abrufen“Öffnen Sie diese URL in einem Browser-Tab, in dem Sie bereits bei PlaidCloud angemeldet sind:
https://<your-workspace>.plaid.cloud/mcp/setup/tokenDie Seite liefert ein JSON-Snippet, das Sie direkt in die MCP-Konfiguration Ihres Agents einfügen können. Jeder Workspace hat sein eigenes Snippet.
Die Lebensdauer des Tokens wird von der Richtlinie für die Lebensdauer von Zugriffstoken Ihres Keycloak-Realms bestimmt (typischerweise einige Stunden bis ein Tag). Zum Aktualisieren laden Sie dieselbe URL neu – Ihre Browsersitzung erzeugt das Token automatisch neu.
Einen Client auswählen
Abschnitt betitelt „Einen Client auswählen“Der Rest dieses Abschnitts führt durch die Einrichtung für bestimmte KI-Agent-Clients:
- Claude Code – der Coding-Agent von Anthropic (CLI, VSCode-Erweiterung, JetBrains-Plug-in).
- Claude Desktop und Claude.ai – die Claude-App für Verbraucher (Desktop) und Web (
claude.ai) mit „Custom Connectors“. - Cursor – der KI-native Code-Editor.
- GitHub Copilot – der Copilot-Agent-Modus in VSCode.
- Google Gemini CLI –
gemini-cliund Gemini Code Assist. - ChatGPT – aktueller Unterstützungsstatus und empfohlene Umgehungslösung.
- Grok – Anbindung der Custom Connectors von Grok.
- Fehlerbehebung – häufige Fehler und ihre Behebung.