Przejdź do głównej zawartości

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.

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/mcp

Zastąp <your-workspace> poddomeną swojego obszaru roboczego (tą, której używasz do logowania w interfejsie PlaidCloud).

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_search wyszukuje strony dokumentacji PlaidCloud według słów kluczowych, a docs_fetch odczytuje 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.

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_find zwraca 50). Strona obcięta przez limit ustawia next_cursor, a narzędzia find dodatkowo wskazują obciętą listę w truncated — każde z nich oznacza „jest więcej”, a nie „to wszystko”. total zawsze podaje pełną liczbę. Zwiększ limit lub 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łaj mcp_introspect, aby zobaczyć, jakie parametry akceptuje dane narzędzie.
  • Liczniki. count_only=True określa rozmiar zbioru wyników bez jego pobierania.

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.

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ę.

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.).

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_find wyświetla widoki, a view_describe zwraca jeden według identyfikatora lub nazwy.
  • view_upsert tworzy 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_organize usuwa, 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.

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ć.

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.

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”.

Serwer MCP PlaidCloud akceptuje dwie ścieżki uwierzytelniania:

  1. 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.
  2. 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).

Otwórz ten adres URL w karcie przeglądarki z aktywną sesją PlaidCloud:

https://<your-workspace>.plaid.cloud/mcp/setup/token

Strona 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.

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-cli i 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.