Pierwsze kroki z agentami AI do kodowania
Najszybszy sposób połączenia znajduje się w samym PlaidCloud: otwórz menu awatara (użytkownika) i wybierz Połącz swoją AI, wskaż używanego klienta i postępuj zgodnie z pokazanymi krokami — w tym z adresem URL serwera MCP Twojego obszaru roboczego, który jest już wypełniony. Opcja jest dostępna, gdy w Twoim obszarze roboczym włączono uprawnienie AI. Reszta tej strony oraz następujące po niej strony poszczególnych klientów pozostają dokumentacją referencyjną — czytaj dalej, jeśli nie korzystasz z interfejsu webowego lub chcesz poznać pełny obraz uwierzytelniania i tego, co udostępnia serwer.
Czym jest serwer MCP?
Dział zatytułowany „Czym jest serwer MCP?”Model Context Protocol to otwarty standard umożliwiający agentom AI komunikację z zewnętrznymi narzędziami i danymi. PlaidCloud uruchamia w każdym obszarze roboczym serwer MCP, który opakowuje te same podstawowe funkcje pomocnicze co REST API — pogrupowane według intencji (find, describe, upsert, run, organize), aby agent mógł poruszać się po powierzchni bez ładowania ponad 1000 niskopoziomowych nazw metod RPC.
Serwer znajduje się pod adresem:
https://<your-workspace>.plaid.cloud/mcpZastąp <your-workspace> poddomeną swojego obszaru roboczego (tą, której używasz do logowania w interfejsie PlaidCloud).
Co udostępnia
Dział zatytułowany „Co udostępnia”Katalog obejmuje większość codziennych potrzeb agenta:
- Projekty, przepływy pracy, kroki — find/describe/upsert/run/organize, w tym ponowne uruchamianie na poziomie kroku i historia wersji.
- Tabele, widoki, zapytania — introspekcja schematu, wykonywanie zapytań, eksporty, migawki, gałęzie. Widoki są tymi samymi, które widzisz w PlaidCloud, niezależnie od tego, czy utworzono je w eksploratorze tabel, czy powstały w przepływie pracy.
- Wymiary — describe, find, upsert, wersje, zarządzanie węzłami/aliasami/właściwościami.
- Połączenia — find/upsert/test połączeń z systemami zewnętrznymi.
- Lakehouse — gałęzie, migawki, operacje optimize/vacuum.
- Tożsamość — członkowie, grupy, sesje, listy dystrybucyjne.
- Dokumenty, pulpity, UDF, edytory, agenci, publikacje — narzędzia specyficzne dla domeny.
- Migracja przepływów pracy — konwertuj eksporty Alteryx (
alteryx_convert), KNIME (knime_convert), Prophecy (prophecy_convert) i Savant (savant_convert) umieszczone w Document na przepływy pracy PlaidCloud oraz koordynuj prace migracyjne całego portfolio. - Dokumentacja PlaidCloud —
docs_searchwyszukuje strony dokumentacji PlaidCloud według słów kluczowych, adocs_fetchodczytuje stronę w całości, dzięki czemu agent może sprawdzić, jak działa dana funkcja, zanim zacznie z niej korzystać. - Dzienniki przepływów pracy i śledzenie uruchomień —
workflow_logs,workflow_run_status,workflow_job_track.
Każde narzędzie zwraca jednolitą kopertę {ok, data, next_cursor?, total?}; błędy używają {ok: false, error: {code, retryable, message, hint?}}. Mutacje akceptują dry_run=True w celu weryfikacji planu bez zapisu.
Utrzymywanie małych wyników
Dział zatytułowany „Utrzymywanie małych wyników”Wyniki narzędzi są największym pojedynczym konsumentem kontekstu agenta, dlatego narzędzia find i describe domyślnie zwracają niewielki wycinek i pozwalają go poszerzyć:
- Wiersze. Find zwraca 25 dopasowań na stronę (
step_findzwraca 50). Strona obcięta przez limit ustawianext_cursor, a narzędzia find dodatkowo wskazują obciętą listę wtruncated— każde z nich oznacza „jest więcej”, a nie „to wszystko”.totalzawsze podaje pełną liczbę. Zwiększlimitlub przeglądaj strony za pomocą kursora. - Kolumny. Przekaż
fields=['id', 'name', 'update_time'], aby otrzymać tylko te kolumny. Nazwa pola, która nie występuje w żadnym rekordzie, jest błędem z listą dostępnych pól, a nie cichym pominięciem — dzięki temu literówka kończy się wyraźnym błędem, a nie po cichu zwraca mniej, niż poproszono. Narzędzia oferujące wyselekcjonowane zestawy przyjmują teżfield_set='minimal' | 'default' | 'full'; wywołajmcp_introspect, aby zobaczyć, jakie parametry akceptuje dane narzędzie. - Liczniki.
count_only=Trueokreśla rozmiar zbioru wyników bez jego pobierania.
Nieznane pola są odrzucane
Dział zatytułowany „Nieznane pola są odrzucane”Parametr spec przyjmowany przez narzędzie, na przykład dla project_upsert lub workflow_upsert, akceptuje tylko wymienione pola. Pole, którego nie rozpoznaje, jest odrzucane z błędem wskazującym to pole, zamiast być ignorowane, co zmuszałoby do późniejszego odkrywania, że nic nie zrobiło. Popraw nazwę i wyślij żądanie ponownie. workflow_upsert przyjmuje opis przepływu pracy jako memo i akceptuje description jako inną nazwę tego pola.
Grupowanie żądań
Dział zatytułowany „Grupowanie żądań”mcp_batch łączy kilka wywołań narzędzi w jedno żądanie. Przyjmuje najwyżej 100 wywołań, uruchamia ograniczoną ich liczbę naraz i nie może być zagnieżdżony w innym mcp_batch ani w recepturze — zamiast tego wypisz wywołania w jednej płaskiej partii, co nie kosztuje więcej. Partia przekraczająca limit jest odrzucana z komunikatem wskazującym limit, zamiast być po cichu przycinana; limit ogranicza pracę, którą może zainicjować pojedyncze żądanie, a nie łączną ilość pracy, więc większe zadanie podziel na kilka partii.
Receptura paginate_through_listing zatrzymuje się po 200 stronach, niezależnie od tego, jak wysoką wartość max_pages przekażesz, i zgłasza partial: true, gdy zatrzyma się wcześniej. Dzięki temu i limitowi max_items pojedyncze wywołanie paginacji zawsze się kończy.
Receptura odrzuca klucz params, którego nie rozpoznaje, a komunikat wymienia klucze, które ta receptura akceptuje — dzięki temu błędnie napisany parametr opcjonalny kończy się wyraźnym błędem, a nie jest pomijany, co sprawiłoby, że wywołanie po cichu odpowiadałoby na inne pytanie, niż zadano. Wywołaj mcp_recipes(name=...), aby poznać klucze przyjmowane przez daną recepturę.
Wyniki zorientowane kolumnowo
Dział zatytułowany „Wyniki zorientowane kolumnowo”Duży wynik, którego wiersze mają te same pola, wraca w postaci kolumnowej, a nie listy obiektów, więc nazwy pól są wysyłane raz, a nie w każdym wierszu:
{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}Wiersz i to dict(zip(cols, rows[i])). Małe wyniki oraz wyniki, których wiersze nie mają identycznego zestawu pól, pozostają zwykłymi tablicami obiektów — dlatego pojawiają się oba kształty, a kod odczytujący te odpowiedzi bezpośrednio powinien obsługiwać każdy z nich. Koperta wokół wyniku się nie zmienia, a żadna wartość nie jest konwertowana ani zaokrąglana. Agenci są informowani o tym kształcie przy połączeniu i odczytują go bez żadnej podpowiedzi z Twojej strony; oszczędność wynosi około 30% znaków i około 15% budżetu odczytu agenta przy typowym ruchu list, co zostawia więcej kontekstu na Twoje właściwe pytanie. (Obie wartości się różnią, ponieważ powtarzające się nazwy pól są dla modelu tanie w odczycie — oszczędność znaków jest zawsze większa.)
Aby poznać aktualny katalog, wskaż agentowi serwer i wywołaj mcp_introspect (bez argumentów) — zwraca bieżącą liczbę narzędzi, podsumowania dla poszczególnych domen i sygnatury parametrów. Użyj mcp_recipes, aby poznać typowe scenariusze wielonarzędziowe (paginacja dużych list, migawka przed modyfikacją, ponowne uruchomienie nieudanego kroku itp.).
Etykiety i widoki
Dział zatytułowany „Etykiety i widoki”Każde narzędzie upsert, które ustawia etykiety — dla tabel, przepływów pracy, kroków, projektów, wymiarów, widoków, edytorów, UDF, połączeń i magazynów — przyjmuje dwa parametry: labels dodaje etykiety, a remove_labels je usuwa. Pozostałe etykiety obiektu zostają. Usunięcia są stosowane przed dodaniami, więc jedno wywołanie może zmienić nazwę etykiety:
{"remove_labels": ["01"], "labels": ["001"]}Usunięcie etykiety, której obiekt nie ma, nic nie robi.
Narzędzia widoków działają na widokach, które widzisz w PlaidCloud:
view_findwyświetla widoki, aview_describezwraca jeden według identyfikatora lub nazwy.view_upserttworzy widok lub aktualizuje istniejący w miejscu. Aktualizacja zachowuje identyfikator i etykiety widoku, a same etykiety można zmienić bez ponownego wysyłania zapytania.view_organizeusuwa, zmienia nazwę, duplikuje i przenosi widoki.- Parametry zapytania zapisuj jako symbole zastępcze
%(name)s.
Widoki współdzielą drzewo folderów tabel, więc do zarządzania ich folderami użyj table_organize.
Tworzenie przepływów pracy z natywnych kroków
Dział zatytułowany „Tworzenie przepływów pracy z natywnych kroków”Gdy Twoje dane znajdą się w PlaidCloud, Twój agent jest kierowany do budowania każdej transformacji z natywnych kroków tabel — kroków Table Extract, kroków złączenia, Table Melt, Table Union All i Table Lookup — zamiast z kroku Wyodrębnij SQL. Krok natywny podstawia Twoje zmienne w filtrach i wyrażeniach, a PlaidCloud generuje jego SQL dla magazynu Twojego projektu. Krok Wyodrębnij SQL wysyła swoje zapytanie do magazynu dokładnie tak, jak zostało napisane: nie podstawia żadnych zmiennych, a jego SQL jest pisany dla jednego magazynu.
Agent może wypróbować konfigurację kroku Table Extract za pomocą query_run(mode='config') — czyli konfigurację, którą zapisałby przez step_upsert — i zobaczyć jej wiersze przed zapisaniem kroku. Gdy zapisuje krok Wyodrębnij SQL, step_upsert zwraca wpis prefer_native_steps w config_warnings, wskazujący natywne kroki, których należy użyć zamiast niego, a describe_step_operation zawiera tę samą uwagę. Krok Wyodrębnij SQL pozostaje dostępny dla tego, czego żaden krok natywny nie potrafi wyrazić.
Szablony zadań
Dział zatytułowany „Szablony zadań”Serwer zawiera niewielki zestaw szablonów dla zadań, o które ludzie proszą po nazwie. Klient obsługujący monity MCP wyświetla je i oferuje jako menu — sprawdź w dokumentacji klienta, gdzie je umieszcza — dzięki czemu wybierasz zadanie, zamiast opisywać sekwencję wywołań narzędzi, którą ono wymaga:
| Szablon | Co mu podajesz |
|---|---|
| Importuj plik CSV do tabeli | Plik oraz opcjonalnie projekt, folder, w którym się znajduje, i nazwę nowej tabeli |
| Wyjaśnij zmianę kosztów | Tabelę wyników oraz opcjonalnie projekt i dwa okresy |
| Zdiagnozuj nieudany przepływ pracy | Przepływ pracy oraz opcjonalnie projekt |
| Eksploruj dane projektu | Czego szukasz oraz opcjonalnie projekt |
Każdy z nich to wiadomość początkowa, a nie polecenie: agent ją czyta, a następnie sam steruje narzędziami, więc możesz ją edytować lub kontynuować rozmowę od tego miejsca.
Import pliku bez znajomości modelu obiektów
Dział zatytułowany „Import pliku bez znajomości modelu obiektów”Szablon importu oszczędza najwięcej pracy, ponieważ naiwna droga wymaga czterech narzędzi we właściwej kolejności — znalezienia konta dokumentów, przejścia do pliku, utworzenia tabeli docelowej, a następnie uruchomienia importu — a błędne założenie w którymkolwiek z nich kończy przepływ kilka wywołań później.
Odczytuje tekst rozdzielany separatorami — CSV, TSV i podobne. Skoroszyt Excel lub plik Parquet jest odrzucany, a nie błędnie odczytywany; zamiast tego wczytaj je za pomocą odpowiedniego kroku importu w przepływie pracy.
Zamiast tego scenariusz bulk_import_csv przyjmuje konto według nazwy, a plik według nazwy lub ścieżki:
mcp_recipe_run(name='bulk_import_csv', params={ 'project_id': '<project>', 'document_path': 'sales_2026.csv', 'document_account': 'Demo Data',})Rozwiązuje konto do jego identyfikatora, lokalizuje plik, tworzy tabelę z kolumnami i typami odczytanymi z samego pliku i ładuje ją — więc nie podajesz ani identyfikatora konta, ani specyfikacji kolumn. table_name domyślnie przyjmuje nazwę pliku bez rozszerzenia, a table_path katalog główny projektu.
Podaj folder, gdy go znasz — 'document_path': 'raw/sales_2026.csv' — a wyszukiwanie zostanie do niego ograniczone. Plik nazwany w folderze jest dopasowywany tylko w tym folderze: plik o tej samej nazwie głębiej jest oferowany jako wybór, a nie importowany w jego miejsce.
Gdy argument jest niejednoznaczny, wynik pyta, zamiast zgadywać:
{ "needs_choice": "document_account", "question": "More than one document account is named 'Archive'. Which one?", "candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]}Pokaż kandydatów osobie, której pomagasz, a następnie wywołaj scenariusz ponownie z jej odpowiedzią, przekazując kandydata dokładnie w takiej postaci, w jakiej został podany. Gdy nie można znaleźć pliku, odpowiedź wymienia najbliższe nazwy i podaje, ile plików przeszukano, dzięki czemu „nie ma go tam” można odróżnić od „nie ma go tam, gdzie szukano”.
Uwierzytelnianie
Dział zatytułowany „Uwierzytelnianie”Serwer MCP PlaidCloud akceptuje dwie ścieżki uwierzytelniania:
- OAuth 2.1 + PKCE przez Dynamic Client Registration (DCR). Z tego korzysta interfejs niestandardowych konektorów Claude.ai i jest to także domyślna metoda mostu MCP w Claude Code. Klient rejestruje się sam i przekierowuje Cię do logowania Keycloak w PlaidCloud. Po zalogowaniu PlaidCloud wyświetla stronę Application Access Request z nazwą aplikacji i identyfikatorem URI przekierowania, na który wyśle poświadczenia — zatwierdź ją raz dla każdej autoryzacji, aby otrzymać token. To mechanizm bezpieczeństwa, a nie formalność: sprawdź, czy nazwa aplikacji i identyfikator URI przekierowania odpowiadają klientowi, który faktycznie łączysz, i nie zatwierdzaj żądania, którego nie zainicjowano.
- Statyczny token okaziciela w nagłówku
Authorization. Dla środowisk uruchomieniowych agentów, które nie mają użytecznego przekierowania w przeglądarce lub potrzebują długotrwałego tokenu w pliku konfiguracyjnym. PlaidCloud udostępnia stronę pomocniczą, która go dla Ciebie wygeneruje (patrz niżej).
Pobieranie statycznego tokenu okaziciela
Dział zatytułowany „Pobieranie statycznego tokenu okaziciela”Otwórz ten adres URL w karcie przeglądarki z aktywną sesją PlaidCloud:
https://<your-workspace>.plaid.cloud/mcp/setup/tokenStrona zwraca fragment JSON gotowy do wklejenia do konfiguracji MCP agenta. Każdy obszar roboczy ma własny fragment.
Czas życia tokenu wynika z polityki czasu życia tokenu dostępu w Twoim obszarze Keycloak (zwykle od kilku godzin do doby). Aby go odświeżyć, załaduj ponownie ten sam adres URL — sesja przeglądarki automatycznie wygeneruje token na nowo.
Wybierz klienta
Dział zatytułowany „Wybierz klienta”Pozostała część tej sekcji opisuje konfigurację dla poszczególnych klientów agentów AI:
- Claude Code — agent do kodowania Anthropic (CLI, rozszerzenie VSCode, wtyczka JetBrains).
- Claude Desktop i Claude.ai — aplikacja konsumencka Claude (desktop) i web (
claude.ai) z użyciem „niestandardowych konektorów”. - Cursor — edytor kodu natywnie oparty na AI.
- GitHub Copilot — tryb agenta Copilot w VSCode.
- Google Gemini CLI —
gemini-clii Gemini Code Assist. - ChatGPT — aktualny stan obsługi i zalecane obejście.
- Grok — łączenie niestandardowych konektorów Grok.
- Rozwiązywanie problemów — typowe błędy i sposoby ich naprawy.