Coraz częściej pytamy o pieniądze ogólnego asystenta AI. „Ile wydaliśmy w zeszłym miesiącu na zakupy spożywcze?”, „które budżety są przekroczone?” — pytania są proste, ale Claude czy ChatGPT nie odpowie na nie bez danych. Użytkownik AI Budżet musiał więc dotąd eksportować dane albo przepisywać liczby do czatu ręcznie.

Zamknęliśmy tę lukę konektorem MCP. Każdy asystent obsługujący zdalne serwery MCP może teraz połączyć się z https://api.ai-budget.pl/mcp, poprosić użytkownika o zgodę na naszej własnej stronie i czytać jego wydatki, przychody, kategorie oraz budżety. Ten artykuł opisuje, po co to zbudowaliśmy, dlaczego zajęło to tylko kilka dni i co znalazły przeglądy kodu, zanim włączyliśmy konektor 13 listopada 2026 roku.

Dlaczego MCP i dlaczego teraz

MCP (Model Context Protocol) to otwarty standard łączenia asystentów AI z zewnętrznymi narzędziami i danymi. Asystent nie potrzebuje integracji napisanej specjalnie dla niego: pobiera z serwera listę narzędzi i wywołuje je, gdy pytanie tego wymaga. Jeden serwer działa więc z Claude, ChatGPT i każdym innym klientem, który zna ten protokół.

Dla nas było to tanie z powodu, który przygotowaliśmy wcześniej. AI Budżet miał już publiczne API to interfejs, przez który dwa systemy wymieniają dane automatycznie — bez eksportów do Excela i przeklejania ręką. Pełna definicja → z własnym serwerem OAuth — opisaliśmy je w poprzednim artykule. Autoryzacja, ekran zgody, dostęp per konto, maskowanie pól i limity zapytań istniały i działały na produkcji. Konektor MCP to drugie wejście do tych samych danych, a nie nowy system.

Powody były trzy:

Użytkownicy. Pytanie asystenta o własny budżet jest naturalne, a ręczne przepisywanie liczb to dokładne przeciwieństwo tego, do czego służy aplikacja.

Zasięg. „Działa z Claude i ChatGPT” to krótka i uczciwa historia, a katalogi konektorów to kanał, którego nie mieliśmy.

Sprawdzian. To pierwszy prawdziwy, pełny przebieg naszego OAuth na produkcji — kod, Token to fragment tekstu, zwykle kawałek słowa, w którym modele AI mierzą i długość zapytania, i koszt — rachunek wystawiany jest za tokeny, nie za pytania. Pełna definicja →, wywołanie, odświeżenie, odwołanie — prowadzony przez klientów, których nie napisaliśmy.

Decyzje właściciela szybko ustaliły zakres: połączyć może się dowolny klient MCP, dostęp jest tylko do odczytu, a asystent widzi dokładnie to, co daje publiczne API — nic więcej. Zapis, zdjęcia paragonów i lokalny pakiet serwera (stdio) świadomie pominęliśmy.

Jak asystent znajduje nas bez klucza API

Użytkownik wpisuje jeden adres. Resztę asystent odkrywa sam, dzięki istniejącym już standardom:

1. Odpowiedź 401, która się tłumaczy. Pierwsze wywołanie /mcp nie ma tokenu, więc serwer odpowiada 401 z nagłówkiem WWW-Authenticate wskazującym /.well-known/oauth-protected-resource/mcp (RFC 9728).

2. Metadane. Ten dokument wskazuje nasz serwer autoryzacji, a /.well-known/oauth-authorization-server (RFC 8414) podaje adresy, obsługiwane zakresy i jedyną dozwoloną metodę PKCE, S256.

3. Samorejestracja. Asystent rejestruje się sam pod /oauth/register (Dynamic Client Registration, RFC 7591). Staje się klientem publicznym: bez sekretu, z obowiązkowym PKCE, oznaczonym jako zarejestrowany przez asystenta.

4. Zgoda. Przeglądarka otwiera app.ai-budget.pl/authorize — tę samą stronę, której używa każda połączona aplikacja. Użytkownik loguje się, zaznacza konta, które asystent może czytać, i zatwierdza.

5. Token i wywołania. Asystent wymienia kod na token i wywołuje narzędzia na /mcp. Odświeżony token pozostaje przypisany do tego samego zasobu.

Dziewięć narzędzi tylko do odczytu

Serwer udostępnia dziewięć narzędzi: list_accounts, list_expenses, get_expense, list_incomes, get_income, list_categories, list_budgets, get_budget i get_spending_summary. Obejmują to, co czyta publiczne API: konta, wydatki i przychody z filtrami i szczegółami, kategorie wydatków i przychodów, budżety z postępem w bieżącym okresie oraz sumy wydatków.

Wyniki są celowo ograniczone. Lista przyjmuje limit od 1 do 200 (domyślnie 50) i kursor, żaden wynik nie przekracza 200 wierszy, a wydatek z ponad 200 pozycjami paragonu mówi wprost „Showing 200 of N”, zamiast udawać kompletność. Zdjęć paragonów przez MCP nie ma wcale: są duże i mało przydatne dla modelu czatu.

Endpoint działa wewnątrz naszego API w NestJS, na oficjalnym SDK MCP dla TypeScriptu, w transporcie Streamable HTTP. Jest bezstanowy — jedna instancja serwera na zapytanie — bo narzędzia do odczytu nie potrzebują sesji.

Jeden rdzeń autoryzacji dla REST i MCP

Najważniejsza zasada projektu jest negatywna: MCP nie ma osobnej autoryzacji. Zanim napisaliśmy konektor, wydzieliliśmy logikę strażnika publicznego API do jednej usługi, PublicApiAuthorizer, i przypięliśmy jej zachowanie testami. Wywołują ją i strażnik REST, i /mcp; zmiana autoryzacji zmienia obie powierzchnie naraz.

Usługa czyta bazę przy każdym wywołaniu i niczego nie buforuje: token, to, czy dostęp odwołano, czy aplikację zablokowano, czy użytkownik jest aktywny, czy osoba, która udzieliła dostępu, nadal jest właścicielem lub edytorem konta, oraz poziom szyfrowania konta. Rozłączenie asystenta w aplikacji, blokada przez administratora czy degradacja do roli obserwatora zatrzymują go przy następnym wywołaniu narzędzia.

Zasady danych są takie same jak dla każdej połączonej aplikacji. Konta z pełnym szyfrowaniem end-to-end nie da się odczytać wcale, a na koncie z szyfrowaniem tekstów zaszyfrowane pola pozostają ukryte. Każde narzędzie czyta przez te same funkcje widoku co kontrolery REST, nigdy własnym zapytaniem.

Token działa dokładnie na jednej powierzchni

Token OAuth mówi, kto może co zrobić, ale nie gdzie. Dodaliśmy to przez wskaźniki zasobów (RFC 8707): token niesie zasób, dla którego go wydano. Token dla /mcp jest odrzucany przez REST API, a token REST — przez /mcp.

Ma to znaczenie dla samorejestrujących się klientów: asystent, który zarejestrował się sam, musi wskazać zasób MCP, więc może trzymać wyłącznie tokeny MCP. Anonimowa rejestracja nigdy nie dotrze do REST API, którego zakresów zapisu mogłaby inaczej zażądać.

Z tego samego powodu ograniczone są zakresy. Samorejestrujący się asystent może mieć tylko expenses:read, categories:read, incomes:read, budgets:read i analytics:read. receipts:read i każdy zakres zapisu są odrzucane przy autoryzacji, wymianie kodu i odświeżeniu.

Jedną subtelność zapisaliśmy jako regułę: /mcp jest tylko do odczytu z powodu zestawu narzędzi, a nie sprawdzenia zakresu — aplikacja zarejestrowana przez programistę mogłaby mieć zakresy zapisu i token MCP. Dodanie narzędzia zapisu nie może więc polegać na „zarejestrowaniu narzędzia”; wymusza decyzję o zakresach, typach klientów i potwierdzeniu.

Co znalazły przeglądy

Kod przeszedł kilka rund przeglądów przed startem. Większość uwag dotyczyła samorejestracji i ekranu zgody, bo tam nieznana strona może postawić coś przed naszymi użytkownikami.

Nadużycia rejestracji. Pierwszy limit liczył się per adres IP. Przegląd wskazał, że w IPv6 jedna maszyna może rotować adresy w całym prefiksie /64, więc limit liczy się teraz per /64, a ponad nim jest globalny pułap 300 rejestracji na godzinę. Gdy Redis jest niedostępny, rejestracja kończy się kodem 429, a nie staje się nieograniczona; treść zapytania ma limit 16 KB.

Podszywanie się na naszym ekranie zgody. Asystent sam podaje swoją nazwę, więc rejestracja mogłaby nazwać się jak nasz produkt. Nazwa zawierająca nazwę produktu jest odrzucana — bez względu na wielkość liter, znaki diakrytyczne i spacje, z małą mapą podobnie wyglądających znaków, a także nazwa naszej firmy oraz polskie i rosyjskie słowo „budżet”.

Zaufanie do metadanych deklarowanych przez klienta. Wszystko w rejestracji pisze ten, kto się rejestruje. Ekran zgody pokazuje więc nazwę jako zwykły tekst bez znaków bidi, znaków zerowej szerokości i znaków sterujących, deklarowaną stronę domową tylko jako host w punycode i bez linku, a logo nigdy — jego pobranie wysłałoby też adres IP oglądającego temu, kto się zarejestrował. Zamiast tego w ramce ostrzeżenia pokazuje jedyny fakt, który nie jest deklaracją: „Dostęp zostanie wysłany do <host>”, wzięty ze zweryfikowanego adresu przekierowania, więc podobna domena wygląda jak xn--….

Koszt zapytania. Limit liczy jedną jednostkę na wywołanie narzędzia, w tych samych pulach co REST API. Sprawdzenie połączenia przed wywołaniem się nie liczy — to świadoma poprawka, bo liczenie go obciążałoby każde wywołanie podwójnie. Treść /mcp ma limit 128 KB przed uwierzytelnieniem — globalny parser przyjąłby 50 MB — a paczki JSON-RPC są odrzucane: wersja protokołu 2025-06-18 usunęła batching, a paczka mnożyłaby koszt jednej jednostki.

Ukryta ścieżka musi pozostać ukryta. Wszystko jest za dwiema flagami, a gdy są wyłączone, /mcp, rejestracja i dokumenty odkrywania odpowiadają 404. Przegląd zauważył, że parsery treści dla tych ścieżek działają przed jakimkolwiek strażnikiem i odpowiadałyby 400 lub 413 — zdradzając ścieżkę, która miała być niewidoczna. Teraz sprawdzają flagę przy każdym zapytaniu.

Nie psuć istniejących klientów. Klient publicznego API zgodny ze specyfikacją też może wskazać swój zasób. Takie identyfikatory oznaczają REST API, więc przypisanie tokenów do zasobów nie zepsuło nikomu już połączonego.

Porządki i logi. Samorejestrujący się klienci, z których nikt nie korzysta, są miękko usuwani 30 dni po ostatnim dostępie. Logi MCP zawierają nazwę narzędzia, wynik i czas — nigdy tokenu, kodu ani wiersza finansowego; przy błędzie wewnętrznym dodają tylko nazwę klasy błędu.

Włączenie

13 listopada 2026 roku dodaliśmy dwa bloki do współdzielonego nginx — /mcp i dokumenty odkrywania w strefie limitów publicznego API, z małym limitem treści — przeładowaliśmy go łagodnie i włączyliśmy flagę. Przed flagą sprawdziliśmy, że nowe ścieżki docierają do API i odpowiadają 404 z API, a nie z nginx; po niej — że dokumenty odkrywania odpowiadają, a /mcp zwraca 401 z właściwym wyzwaniem.

Pierwszy prawdziwy klient znalazł potem to, czego nie znalazł żaden przegląd. Claude Code rejestruje się pod nazwą „Claude Code (<jak użytkownik nazwał serwer>)”, a my nazwaliśmy serwer ai-budget — zarejestrował się więc jako „Claude Code (ai-budget)” i nasza ochrona przed podszywaniem się go odrzuciła. Każdy, kto nazwałby konektor naszą nazwą, zostałby zablokowany niezrozumiałym błędem. Naprawiliśmy to tego samego dnia: końcowa etykieta w nawiasie nie jest już sprawdzana, jeśli coś ją poprzedza, a „AI Budget (official)” i samo „(AI Budget)” nadal są odrzucane. Potem cała ścieżka zadziałała — odkrywanie, rejestracja, zgoda, token, połączenie i lista narzędzi.

Jedno pytanie zostawiamy otwarte: limit rejestracji liczy się per IP, a jeśli platforma rejestruje się ze wspólnych serwerów, a nie z przeglądarki użytkownika, wszyscy jej użytkownicy dzieliliby jedną pulę. Zanim ogłosimy konektor w katalogach, zapisujemy adresy rejestracji prawdziwych klientów i w razie potrzeby podnosimy limit dla danej platformy.

Jak połączyć

W Claude otwórz Ustawienia → Konektory, dodaj własny konektor i wpisz https://api.ai-budget.pl/mcp. W planach Team i Enterprise własne konektory dodaje tylko właściciel organizacji — sami się na to natknęliśmy. Inni asystenci obsługujący zdalne konektory MCP przyjmują ten sam adres.

Asystent otworzy stronę AI Budżet, na której logujesz się jak zwykle. Zobaczysz nazwę asystenta z dopiskiem, że zarejestrował się sam, oraz host, do którego trafi dostęp. Zaznacz konta, które może czytać, i zezwól. Aby go odciąć, otwórz w AI Budżet Ustawienia → Połączone aplikacje i rozłącz go; traci dostęp przy następnym wywołaniu.

Najczęstsze pytania

Czy asystent może zmienić moje dane w AI Budżet?
Nie. Konektor ma tylko narzędzia do odczytu: konta, wydatki, przychody, kategorie, budżety i sumy wydatków. Nie dodaje, nie zmienia ani nie usuwa niczego i nie pobiera zdjęć paragonów.
Czy potrzebuję klucza API?
Nie. Wpisujesz w asystencie adres https://api.ai-budget.pl/mcp, asystent rejestruje się sam, a Ty zatwierdzasz dostęp na stronie zgody AI Budżet i wybierasz konta.
Jak odebrać asystentowi dostęp?
W AI Budżet otwórz Ustawienia → Połączone aplikacje i rozłącz asystenta. Uprawnienia są sprawdzane przy każdym wywołaniu, więc traci dostęp przy następnym zapytaniu.
Czy działa to z kontami szyfrowanymi?
Konta z pełnym szyfrowaniem end-to-end nie da się odczytać. Na koncie z szyfrowaniem tekstów zaszyfrowane pola pozostają ukryte — tak samo jak dla każdej połączonej aplikacji.