Konektor MCP to nie cała usługa, tylko wybrane zapytania do jej API – te, które przewidział autor konektora. Przy Gmailu widać to szybko: MCP przeczyta wiadomość i nada jej etykietę, ale treści załącznika nie pokaże, a filtra nie założy. Reszta operacji leży w samym API Gmaila i czeka, aż ktoś sięgnie po nie wprost.

Szerzej pisaliśmy o tym w poradzie o tym, co zrobić, gdy AI mówi, że nie ma takiego narzędzia – tam opisujemy wszystkie drogi do usługi i prompt, który otwiera każdą z nich. Dziś pokazujemy, jak zaprezentowaną tam teorię wykorzystać w praktyce.

API to skrót od application programming interface, czyli interfejsu programistycznego. To ta sama usługa, do której ty wchodzisz przez stronę i przyciski, wystawiona dla programów jako lista operacji, o które można poprosić z zewnątrz. Konektor MCP sięga po API i podaje agentowi AI jego wycinek; własna integracja sięga po nie bez pośrednika.

Żeby agent AI mógł rozmawiać z API Gmaila, potrzebujesz trzech rzeczy: projektu w Google Cloud Console, włączonego w nim Gmail API i własnych danych logowania OAuth, czyli identyfikatora i sekretu klienta, którymi twoja integracja przedstawia się Google. Wszystkie trzy skonfigurujesz w przeglądarce, a autoryzację i pierwszy test zlecisz Claude Code.

Jeśli potrzebujesz samego czytania i wysyłania poczty, zostań przy gotowym konektorze – pokazujemy go w lekcji o konektorach Google, gdzie wszystko da się podłączyć kilkoma kliknięciami.

Konsola Google jest spolszczona tylko częściowo, a nazwy przetłumaczonych pozycji potrafią zmienić się z miesiąca na miesiąc. Dlatego każdy element ekranu nazywamy tu po polsku i dodajemy w nawiasie nazwę angielską – to po niej szukaj, gdy u siebie widzisz inny napis.

Przy każdym ekranie dajemy też odnośnik prowadzący wprost do niego, podpisany słowem link – klikasz i jesteś na miejscu, bez szukania w menu. Google przestawia adresy w konsoli, więc nie obiecujemy, że wszystkie będą działać za miesiąc. Gdy któryś zawiedzie, obok stoi nazwa strony, po której go znajdziesz.

Najłatwiej przejść przez tę lekcję razem z Claude Code: powiedz mu, że chcesz zbudować własną integrację przez Google Cloud Console, daj link do tego wpisu i postaw jeden ważny warunek:

Chcę podpiąć własną integrację z Gmailem przez Google Cloud Console. Zapoznaj się z wpisem https://howstart.cc/pl/lekcje/jak-zbudowac-wlasna-integracje-z-google/ i przeprowadź mnie przez niego krok po kroku. Ważne: opisuj mi, jak wykonać jeden krok, i czekaj, aż potwierdzę, że mam go za sobą. Dopiero wtedy przejdź do następnego kroku.

Gdy gdzieś utkniesz – a przy pierwszym podejściu to normalne – wystarczy napisać „nie widzę tego przycisku” albo „mam błąd o zablokowanym dostępie”. Nie musisz wtedy szukać właściwego miejsca w środku długiej instrukcji.

Załóż projekt w Google Cloud Console

Google Cloud Console zmienia układ ekranów i ich nazwy – cała sekcja od autoryzacji nazywa się dziś Google Auth Platform i jest rozbita na kilka osobnych stron. Nazwy elementów podajemy tu za dokumentacją Google; układ menu traktuj jako kierunek, nie jako mapę co do piksela.

Projekt to pojemnik na wszystko, co dalej zrobisz: włączone API, ekran zgody, dane logowania i limity. Załóż go przyciskiem Utwórz projekt (Create project) na stronie Zarządzanie zasobami (Manage resources) – link. W okienku podaj nazwę projektu i wybierz zasób nadrzędny (Parent resource), czyli organizację albo folder. Zwykłe konto Google żadnego nie ma, więc to pole zostaw bez zmian. Identyfikator projektu Google układa z nazwy automatycznie; możesz go w tym momencie poprawić, ale po utworzeniu projektu zostaje z nim na zawsze.

Nazwij projekt ogólnie. „Połączenie z Gmail” wygląda sensownie przez pierwszy tydzień, a przestaje w dniu, w którym włączysz w tym samym projekcie API Google Drive lub innej usługi – i zostaniesz z nazwą, która kłamie na temat własnej zawartości. Nazwa opisująca obszar integracji, na przykład „Integracje biurowe” albo „Automatyzacje firmowe”, będzie aktualna po dodaniu każdej kolejnej usługi Google, którą włączysz.

Projekty w Google Cloud

Włącz API dla usługi, z którą się integrujesz

Świeży projekt nie umie jeszcze nic. Dostęp do każdej usługi Google włącza się osobno, w bibliotece API (API Library): w menu wybierz Interfejsy API i usługi (APIs & Services), potem Bibliotekę (Library), a w niej sekcję Google Workspace – link. Kliknij w API, którego potrzebujesz – dla poczty jest to Gmail API – i włącz je przyciskiem Włącz (Enable) – link.

API nie wybierasz raz na zawsze – kolejne usługi można włączyć później, a także wyłączyć te już uruchomione, jeśli uznasz, że nie są ci już potrzebne. Wszystko w ramach jednej integracji, bez zakładania od nowa projektu w Google Cloud Console. Dalsze kroki prowadzimy na przykładzie poczty; dla każdej innej usługi Google wygląda to tak samo, tylko z innym API i innym zakresem.

Włączanie API Google Workspace

Skonfiguruj ekran zgody OAuth i zakresy dostępu

Ekran zgody to okno, które Google pokazuje przy logowaniu: nazwa aplikacji i lista uprawnień, o które prosi. Po drugiej stronie tego okna jesteś tylko ty, ale procedura wygląda tak samo jak przy aplikacji dla tysiąca osób. W konsoli ustawienia te leżą w sekcji Google Auth Platform, rozbitej na kilka stron: Marka (Branding), Odbiorcy (Audience), Klienci (Clients) i Dostęp do danych (Data Access).

Na stronie Odbiorcy – link – wybierz typ użytkownika Zewnętrzny (External); ten obejmuje każde zwykłe konto Google, także twoje. Niżej stoi status publikacji i tu od razu kliknij Opublikuj aplikację (Publish app). Nowy projekt startuje w statusie Testowanie (Testing), a ten kosztuje ponowne logowanie co siedem dni – tyle żyje w nim zgoda razem z tokenem odświeżającym.

W statusie Produkcja (In production) nie ma już listy kont zawężającej dostęp: formalnie zalogować się do twojej integracji może każdy, kto ma konto Google. W praktyce nie zaloguje się nikt poza tobą, bo żeby w ogóle zobaczyć to okno, trzeba mieć twój identyfikator i sekret klienta – a te będą zapisane w pliku na twoim dysku. Google tej aplikacji nie weryfikowało, więc przy logowaniu zobaczysz ostrzeżenie, że jej nie sprawdziło; przechodzisz przez nie przyciskiem Zaawansowane (Advanced). Weryfikacja zdejmuje to ostrzeżenie i limit stu nowych użytkowników, a przy integracji dla jednej osoby nie potrzebujesz ani jednego, ani drugiego.

Zakresy (scopes) dodaj na stronie Dostęp do danych – link. Nie wpisuje się ich ręcznie: otwiera się lista z wyszukiwarką, w której szukasz zakresu po nazwie i klikasz ten, który wybierasz. Zakres rządzi dwiema rzeczami naraz: tym, o co Google zapyta w oknie zgody, i tym, co token potrafi później – a token potrafi dokładnie tyle, ile przyznasz mu w trakcie autoryzacji. Tu łatwo o odruch, który psuje całą robotę: zakres tylko do odczytu wygląda ostrożnie, a zostawia integrację słabszą od konektora, który właśnie porzucasz. Dobierz zakresy tak, żeby pokryć wszystko, co konektor umiał, i dołożyć to, czego nie umiał. Dla poczty są to dwa:

  • https://www.googleapis.com/auth/gmail.modify – czytanie, tworzenie i wysyłanie wiadomości, bez trwałego kasowania z pominięciem kosza. Pozwala zrobić wszystko, co robił konektor, a przy okazji otwiera treść załączników i pozwala wysłać wiadomość zbudowaną jako HTML, czyli z pogrubieniami, listami i odnośnikami w treści.
  • https://www.googleapis.com/auth/gmail.settings.basic – ustawienia Gmaila i filtry, czyli to, czego konektor nie dotyka w ogóle.

Zakresu https://mail.google.com/ nie dokładaj. Daje to samo plus trwałe kasowanie poza koszem, a pomyłka w skrypcie usuwa wtedy wiadomości bez śladu.

Odbiorcy i użytkownicy testowi Zakresy OAuth Google

Wygeneruj dane logowania OAuth dla aplikacji

Dane logowania to para: identyfikator klienta i sekret klienta. Tymi dwoma przedstawia się twoja integracja, kiedy puka do Google. Utwórz tę parę na stronie Klienci (Clients) – link – przyciskiem Utwórz klienta (Create client). Jako typ aplikacji wybierz Desktop app – to ten, który pasuje do integracji uruchamianej na twoim komputerze. Reszty ustawień nie ruszaj.

Zaraz po utworzeniu klienta pobierz plik JSON z danymi – w dokumentacji Google nazywa się client_secret.json. Sekret klienta widać wyłącznie w tym jednym momencie; później nie da się go ani podejrzeć, ani pobrać ponownie. Jeśli go zgubisz, musisz wygenerować nowy sekret i podmienić plik.

Polecamy utworzyć specjalny katalog, który będzie służył tylko do przechowywania kluczy dostępu, np. klucze-dostepu.

Aplikacje instalowane na komputerze

Przeprowadź pierwszą autoryzację i odbierz token

Klikanie w Google Cloud Console kończy się w tym miejscu. Teraz na podstawie pliku z danymi klienta trzeba uzyskać token, którym integracja będzie się posługiwać na co dzień, a to jest już praca dla Claude Code: krótki skrypt, uruchomienie go u ciebie i odczytanie błędu, gdy coś nie zagra.

W katalogu klucze-dostepu jest plik client_secret.json z danymi do OAuth typu Desktop app do projektu w Google Cloud. Napisz i uruchom skrypt, który przeprowadzi jednorazową autoryzację z zakresami gmail.modify i gmail.settings.basic i zapisze token odświeżający do pliku obok. Pokaż mi link do zalogowania i zaczekaj, aż potwierdzę.

Zobaczysz wtedy to, co widzi każdy użytkownik dowolnej aplikacji korzystającej z Google: okno logowania i listę uprawnień z twojego ekranu zgody. Po zgodzie Google odsyła kod na lokalny adres. Skrypt wymienia go na token dostępu i token odświeżający. Od tego momentu integracja loguje się już bez ciebie.

Po kliknięciu zgody przeglądarka często ląduje na stronie, która wygląda na pustą – biały ekran i żadnego komunikatu. Tak ma być: skrypt odebrał już odpowiedź, a sama strona nie ma ci czego pokazać. Napisz wtedy Claude Code, że logowanie masz za sobą, i poproś o dokończenie. Jeśli okaże się, że skrypt niczego nie dostał, skopiuj adres tej pustej strony z paska przeglądarki i wklej go w rozmowie – w adresie siedzi kod, którym Claude Code dokończy autoryzację.

Jeśli zamiast okna zgody dostaniesz komunikat o zablokowanym dostępie, wróć na stronę Odbiorcy (Audience) – link – i sprawdź status publikacji. W Testowaniu (Testing) zaloguje się wyłącznie konto dopisane do listy użytkowników testowych, więc kliknij Opublikuj aplikację (Publish app). W Produkcji (In production) żadna lista kont nie ogranicza logowania, więc przyczyna leży gdzie indziej – najczęściej brakuje zakresu na stronie Dostęp do danych (Data Access) – link.

Wygasanie tokenów OAuth

Podłącz dane do swojej integracji i przetestuj ją

Zanim uznasz temat za zamknięty, sprawdź cały łańcuch: projekt, włączone API, zgoda, token. Najprościej jednym prawdziwym zapytaniem.

Korzystając z zapisanego tokenu, wypisz tematy trzech ostatnich wiadomości z mojej skrzynki. Nie zmieniaj niczego w skrzynce ani w plikach z kluczami – to ma być wyłącznie odczyt.

Błąd na tym etapie jest pomocny, bo każdy wskazuje inne miejsce. Odmowa z informacją, że API nie jest włączone, odsyła do biblioteki API (API Library) – link. Najczęściej okazuje się włączone, tylko w innym projekcie niż ten, z którego pochodzą dane logowania. Odmowa z powodu niewystarczającego zakresu znaczy, że token nosi w sobie stary zestaw uprawnień: dopisanie zakresu na stronie Dostęp do danych (Data Access) – link – niczego nie zmienia, dopóki nie powtórzysz autoryzacji i nie odbierzesz nowego tokenu.

Dołóż kolejne usługi Google do tego samego projektu

Ten sam projekt i te same dane logowania obsłużą każdą kolejną usługę Google. Wracasz do biblioteki API (API Library) – link – włączasz następną i dopisujesz jej zakres na stronie Dostęp do danych (Data Access) – link. Autoryzację powtarzasz, bo stary token nosi w sobie stary zestaw uprawnień. Drugiego projektu nie zakładasz.

Najwięcej daje tu Google Sheets API i Google Docs API. Gotowy konektor Dysku Google czyta pliki, zmienia im nazwy i przenosi je między folderami, ale treści istniejącego arkusza czy dokumentu nie ruszy. Edycja w środku pliku zaczyna się dokładnie tam, gdzie kończy się konektor.

Dalej jest cała reszta Google, do której konektora nie ma w ogóle – na claude.ai oficjalne połączenia z Google są trzy: Gmail, Kalendarz Google i Dysk Google. Google Tasks API pozwoli AI zakładać i odhaczać zadania na twoich listach zadań. Google Chat API otwiera czytanie i pisanie wiadomości w firmowym czacie. Obie usługi wchodzą do twojego projektu tą samą drogą co Gmail – jedno kliknięcie w bibliotece API, jeden zakres, jedna autoryzacja.

Samo połączenie z pocztą to tylko dostęp do narzędzia. O tym, jak nauczyć Claude Code twojego sposobu pisania, żeby odpowiedzi na maile brzmiały jak twoje, przeczytasz w lekcji o ghostwriterze.

Konektory Google Workspace Google Tasks API Google Chat API

Zabezpiecz klucze dostępu

W katalogu klucze-dostepu leżą teraz dwa pliki i każdy niesie co innego: client_secret.json mówi Google, jaka aplikacja prosi o dostęp, a plik z tokenem trzyma twoją zgodę i to on otwiera skrzynkę. Dokumentacja Google mówi o obu krótko: mają być w miejscu, do którego sięga wyłącznie twoja integracja.

Dlatego ten katalog trzymaj poza folderem projektu, nad którym pracujesz z Claude Code, i nie umieszczaj go tam, gdzie zobaczy go ktoś jeszcze – na współdzielonym dysku, w załączniku maila ani w publicznym repozytorium kodu.

Nie wklejaj też zawartości tych plików do czatu, żeby „AI zobaczyło, czy wszystko się zgadza”. Sekret w treści rozmowy przestaje być sekretem, a Claude Code do sprawdzenia pliku wystarczy sama ścieżka do niego.

Przechowywanie tokenów w aplikacji na komputerze

Z tej lekcji zapamiętaj

Projekt w Google Cloud Console to pojemnik, nie połączenie z jedną usługą. Nazwij go ogólnie i dokładaj do niego kolejne API wtedy, gdy będą potrzebne.

Włączone API i zakres to dwie różne zgody. Pierwsza mówi, do jakiej usługi projekt w ogóle sięga, druga – co wolno konkretnemu tokenowi.

Token nosi zakresy z chwili, w której powstał. Zmiana zakresów w konsoli działa dopiero po powtórzeniu autoryzacji.

Status publikacji rozstrzyga, jak długo żyje token. W Testowaniu zgoda i token odświeżający wygasają po siedmiu dniach, w Produkcji nie – dlatego integracja mająca pracować na stałe zaczyna od kliknięcia Opublikuj aplikację.

Sekret klienta widzisz raz. Pobierasz go przy tworzeniu klienta, trzymasz w katalogu na klucze dostępu i nie pokazujesz nikomu – także AI, któremu podajesz samą ścieżkę do pliku.

Zadania

Odhacz, gdy zrobisz. Stan zapamięta się w przeglądarce, więc możesz wrócić do tej listy jutro.

  • Projekt w Google Cloud Console założony i nazwany ogólnie, nie od jednej usługi
  • API usługi, z którą się integrujesz, włączone w bibliotece API (API Library) – link
  • Aplikacja opublikowana – status Produkcja na stronie Odbiorcy (Audience) – link
  • Zakresy gmail.modify i gmail.settings.basic dodane na stronie Dostęp do danych (Data Access) – link
  • Plik z danymi klienta pobrany i zapisany w katalogu na klucze dostępu
  • Pierwsza autoryzacja przeprowadzona, token zapisany na dysku
  • Jedno prawdziwe zapytanie wykonane na tokenie i potwierdzone wynikiem