Serwer MCP Invoiso

Invoiso mówi w Model Context Protocol, więc klient MCP — Claude, ChatGPT albo cokolwiek innego, co go zna — może czytać i pracować na fakturach, zakupach, kontaktach, stanach magazynowych i raportach w Twojej przestrzeni invoiso. Ta strona to wszystko, czego potrzeba, aby go podłączyć.

Punkt końcowy

https://www.invoiso.com/api/mcp

Transport   Streamable HTTP (POST, JSON-RPC 2.0)
Auth        OAuth 2.1 — see below
Server      invoiso 0.1.0
Protocol    2025-06-18, 2025-03-26, 2024-11-05

Większości osób wystarczy sam adres URL. Dodaj go jako własny konektor w ChatGPT albo zdalny serwer MCP w Claude, a potem zaloguj się do invoiso jak zwykle — klucz API nie jest potrzebny. Klient sam odkrywa sposób uwierzytelnienia: nieuwierzytelnione wywołanie odpowiada 401 z nagłówkiem WWW-Authenticate wskazującym na https://www.invoiso.com/.well-known/oauth-protected-resource, gdzie wskazano serwer autoryzacji i zakresy do zażądania.

Łączenie

1. Dodaj https://www.invoiso.com/api/mcp do swojego klienta jako zdalny serwer MCP.
2. Klient przekieruje Cię do logowania invoiso. Zaloguj się jak zwykle.
3. Zatwierdź dostęp opisany na ekranie zgody. Wskazuje on przestrzeń, którą podłączasz.
4. Połączono. Zapytaj klienta o coś ze swoich ksiąg — „ile zafakturowałem w zeszłym miesiącu?” to dobre pierwsze pytanie, bo nie wymaga uprawnień poza odczytem.

Żądane zakresy to openid, email, profile i user:org:read. Ostatni mówi nam, którą przestrzeń podłączasz; bez niego serwer odmawia, zamiast zgadywać — patrz niżej.

Z którą przestrzenią jesteś połączony

Jesteś połączony z przestrzenią, która była aktywna w Twojej przeglądarce w chwili zatwierdzenia połączenia. Ekran zgody ją wskazuje. To ta sama zasada, którą stosuje przeglądarka — sesja jest naraz w jednej przestrzeni — i oznacza, że przełączenie przestrzeni w invoiso nie zmienia tego, co widzi Twój klient MCP.

Aby skierować klienta na inną przestrzeń: najpierw przełącz się na nią w invoiso, potem usuń i dodaj połączenie ponownie w kliencie. Przejdziesz jeszcze raz przez zgodę, a nowy token będzie niósł nową przestrzeń.

Jeśli serwer nie potrafi ustalić, do której przestrzeni należy token, odpowiada 403 z error="insufficient_scope", wskazując zakres do zażądania, zamiast wybierać samodzielnie. Wybór byłby gorszy niż odmowa: prawdopodobną błędną odpowiedzią jest Twoja pusta przestrzeń osobista, a Ty uznałbyś, że invoiso zgubiło Twoje księgi.

Co może Twój plan

Asystent wewnątrz invoiso ma dostęp do wszystkiego w każdym planie. To, co zmienia się w zewnętrznym kliencie MCP, to prawo do zapisu.

Połączenie tylko do odczytu to nie okrojony klient — to każde narzędzie, które wyłącznie raportuje. Zapis z zewnętrznego klienta zaczyna się od Business. Poproś połączenie tylko do odczytu o zmianę, a powie to jednym zdaniem i niczego nie zmieni, zamiast zawieść niezrozumiale.

Co robią narzędzia

Narzędzi jest 167. 63 z nich tylko raportuje; reszta zapisuje. Każde narzędzie niesie trzy adnotacje zdefiniowane przez MCP — readOnlyHint, destructiveHint i openWorldHint — dzięki czemu klient może Cię zapytać, zanim zrobi coś nieodwracalnego. 15 z nich może zmienić coś poza invoiso: wysłać e-mail, opublikować stronę płatności, zapisać do Xero lub QuickBooks. To właśnie te warto potwierdzać.

Kwoty zawsze podane są dwa razy

Przestrzeń może zawierać dokumenty w kilku walutach. Każde narzędzie zwracające kwotę zwraca ją we własnej walucie dokumentu oraz w walucie raportowej przestrzeni, przeliczoną po kursie przypiętym do tego dokumentu. Tylko druga jest porównywalna między dokumentami, a instrukcje serwera nakazują modelowi nigdy nie dodawać dwóch kwot w różnych walutach. Tam, gdzie żaden kurs nie obejmował daty, wartość raportowa to null, a nie zero.

Sumy pochodzą z narzędzia raportowego

run_report odpowiada na pytania „ile”. Narzędzia listujące listują; zsumowanie listy to nie ta sama arytmetyka — szkice i noty korygujące liczą się inaczej — a opis każdego narzędzia mówi, którym jest.

Co serwer czyta i co zachowuje

Wywołanie narzędzia czyta i zapisuje dane Twojej przestrzeni: faktury, zakupy, kontakty, produkty i ustawienia. Odpowiedzi zawierają rekordy, o które pytano — dla kontaktu jego nazwę, a możliwe że też adres e-mail, adres pocztowy lub numer identyfikacji podatkowej, bo to właśnie pojawia się na fakturze.

Serwer nie zachowuje osobnej kopii rozmowy, nie wysyła żadnej odpowiedzi narzędzia nigdzie poza klienta, który o nią poprosił, i nigdy nie zwraca poświadczeń, kluczy API ani tokenów OAuth — ani Twoich, ani podłączonej usługi. Co robimy z danymi ogólnie, w tym które podmioty trzecie co otrzymują, opisuje polityka prywatności, a regulamin obowiązuje to połączenie tak jak każde inne.

Rozłączanie

Usuń połączenie w swoim kliencie MCP. To wystarczy: token jest jedyną rzeczą dającą dostęp, a po naszej stronie bez niego nic nie działa dalej. Usunięcie konta invoiso usuwa wszystko, co za nim stoi — polityka prywatności mówi, co to znaczy i ile trwa.

Szczegóły protokołu

Serwer negocjuje 2025-06-18, 2025-03-26 i 2024-11-05, odpowiadając najnowszą wersją, którą rozumieją i on, i klient. Na nierozpoznaną wersję odpowiada najnowszą obsługiwaną, zamiast odmawiać — tego wymaga specyfikacja.

Autoryzacja przebiega zgodnie z OAuth 2.1 z PKCE. Odkrywanie to metadane zasobu chronionego wg RFC 9728 pod https://www.invoiso.com/.well-known/oauth-protected-resource, a serwer autoryzacji publikuje dokumenty odkrywania zarówno RFC 8414, jak i OpenID Connect. Klienci rejestrują się sami przez dynamiczną rejestrację klienta (RFC 7591) — dlatego kroki powyżej nie proszą o nic poza adresem URL. Punkt rejestracji ogłaszany jest wyłącznie w dokumencie RFC 8414; klient czytający tylko dokument OpenID Connect go nie znajdzie i będzie potrzebował predefiniowanego identyfikatora klienta poniżej.

Jeśli Twój klient nie potrafi zarejestrować się sam i prosi o identyfikator klienta, napisz na support@invoiso.com, a my go wydamy. Sekret klienta zostaw pusty — klient jest publiczny i uwierzytelnia się przez PKCE.

Tokeny są weryfikowane wobec JWKS naszej własnej instancji i muszą nieść naszego wydawcę oraz zakres wskazujący Twoją przestrzeń. Token wystawiony przez inne wdrożenie invoiso lub inną instancję Clerk jest odrzucany. Token innej aplikacji zarejestrowanej wobec tej instancji jest nieodróżnialny od naszego i zostaje przyjęty — to właśnie oznacza otwarta rejestracja i dlatego warto przeczytać ekran zgody, który wskazuje pytającą aplikację, zanim ją zatwierdzisz.

Jeśli coś jest nie tak

Napisz na support@invoiso.com, co wysłał Twój klient i co wróciło. 401 zwykle oznacza, że połączenie wymaga ponownego zatwierdzenia; 403 wskazujący zakres oznacza, że klient o niego nie poprosił; a odmowa wskazująca Twój plan to bramka tylko-do-odczytu powyżej, nie awaria.