Serwer MCP: faktury z ChatGPT, Claude, Gemini i innych asystentów AI

Fakturnia udostępnia serwer MCP (Model Context Protocol), dzięki któremu asystent AI pracuje bezpośrednio na koncie użytkownika: wystawia faktury, sprawdza płatności, wyszukuje kontrahentów, odczytuje stany magazynowe i wysyła dokumenty do KSeF. Serwer działa z ChatGPT, Claude i Claude Code, Gemini, Mistral Vibe (dawniej Le Chat), Perplexity, GitHub Copilot, Cursor i Windsurf, a także z innymi klientami MCP i z własnym agentem. Użytkownik łączy asystenta w aplikacji jednym logowaniem (OAuth 2.1), a każda zmiana danych przechodzi przez podgląd i potwierdzenie w rozmowie.

Ta strona opisuje serwer od strony technicznej. Instrukcja dla użytkownika końcowego (krok po kroku ze zrzutami) jest w pomocy Fakturnii.

W skrócie. Adres serwera: https://prod.api.fakturnia.pl/mcp (sandbox: https://sandbox.api.fakturnia.pl/mcp). Transport: Streamable HTTP, tylko POST, bez sesji. Autoryzacja: OAuth 2.1 z odkrywaniem (RFC 9728 i RFC 8414), PKCE S256, rejestracja dynamiczna i dokumenty client_id; alternatywnie klucz fmcp_… w nagłówku Authorization. Wymagany aktywny plan MAX.

Co daje MCP w porównaniu z REST API#

Narzędzia MCP wykonują się przez to samo External API (z pełną walidacją, limitami i logami), więc reguły z pozostałych przewodników (kwoty, typy dokumentów, KSeF) obowiązują bez zmian.

Adresy i odkrywanie#

Żądanie bez tokenu dostaje 401 z nagłówkiem WWW-Authenticate: Bearer realm="mcp", resource_metadata="…/.well-known/oauth-protected-resource/mcp", od którego klienci MCP zaczynają odkrywanie. GET i DELETE na /mcp zwracają 405: transport jest bezstanowy, nagłówek Mcp-Session-Id jest ignorowany. Serwer obsługuje obie ery protokołu: żądania z metadanymi w params._meta (rewizja 2026-07-28) i starsze klienty zaczynające od initialize.

Podłączanie klientów#

Każdemu klientowi wystarczy adres serwera https://prod.api.fakturnia.pl/mcp. Klient z obsługą OAuth rejestruje się sam (rejestracja dynamiczna) i otwiera ekran zgody Fakturnii, a klient bez OAuth wysyła klucz dostępu fmcp_… (opis w sekcji Uwierzytelnianie).

ChatGPT#

Ustawienia, Konektory, Utwórz: nazwa Fakturnia, adres serwera MCP, uwierzytelnianie OAuth. ChatGPT rejestruje się dynamicznie, otwiera ekran zgody Fakturnii i po kliknięciu „Zezwól" dostaje tokeny. Konektory MCP działają w płatnych planach ChatGPT; w części kont wymagają trybu deweloperskiego.

Claude (claude.ai, Claude Desktop)#

Ustawienia, Konektory, „Dodaj niestandardowy konektor": nazwa Fakturnia, adres serwera. Pola Client ID i Client secret zostają puste (rejestracja dynamiczna albo dokument client_id). Po „Połącz" otwiera się ekran zgody.

Claude Code#

claude mcp add --transport http fakturnia https://prod.api.fakturnia.pl/mcp

Następnie /mcp w Claude Code, fakturnia, Authenticate: przeglądarka otwiera ekran zgody. Claude Code rejestruje redirect_uri na http://localhost:<port>/callback (obie formy, localhost i 127.0.0.1, są dopuszczone).

Gemini#

Aplikacja Gemini (gemini.google.com). W ustawieniach otwórz Connected Apps, potem Custom apps i wybierz „Add a custom app". Wklej adres serwera MCP, kliknij „Next" i zatwierdź dostęp na ekranie zgody Fakturnii. Gemini rejestruje się dynamicznie, więc nie podajesz Client ID ani sekretu. Po podłączeniu w przeglądarce Fakturnia działa też w aplikacji mobilnej Gemini, a w poleceniu wybierzesz ją przez @.

Google udostępnia własne aplikacje w Gemini na razie tylko w USA: dla osób pełnoletnich, po angielsku, na prywatnym koncie Google (nie Workspace) i z włączonym zapisywaniem aktywności (Keep Activity). Gdy funkcja trafi do Polski, podłączysz Fakturnię tym samym adresem serwera.

Gemini Enterprise. W edycji Business administrator zespołu może dodać połączenie z własnym serwerem MCP. Google wymaga transportu Streamable HTTP i publicznego adresu HTTPS z zaufanym certyfikatem, a serwer Fakturnii spełnia oba warunki. Adresy autoryzacji i tokenu znajdziesz w tabeli „Adresy i odkrywanie" powyżej, zakres (scope) to mcp. Jeśli formularz wymaga stałego Client ID i sekretu, użyj klienta prekonfigurowanego wydawanego przez Fakturnię (sekcja Uwierzytelnianie).

Gemini CLI. Dodaj serwer w pliku ~/.gemini/settings.json:

{
  "mcpServers": {
    "fakturnia": {
      "httpUrl": "https://prod.api.fakturnia.pl/mcp"
    }
  }
}

Gemini CLI wykrywa OAuth po odpowiedzi 401 z serwera i otwiera ekran zgody w przeglądarce.

Mistral Vibe (dawniej Le Chat)#

Le Chat nazywa się teraz Mistral Vibe, a konta, plany i ustawienia przeszły bez zmian. Na chat.mistral.ai otwórz Connectors, „Add connector" i zakładkę „Custom MCP Connector". Wpisz nazwę Fakturnia i adres serwera, potem kliknij „Connect". Vibe sam wykrywa logowanie OAuth 2.1 z rejestracją dynamiczną i otwiera ekran zgody Fakturnii. Jeśli wolisz klucz, wybierz uwierzytelnianie „HTTP Bearer Token" i wklej klucz fmcp_…. Własne konektory dodaje administrator organizacji; w planach Free, Pro i Student administratorem jest właściciel konta.

Perplexity#

Własne konektory zdalne (custom remote connectors) są dostępne w planach Pro, Max i Enterprise, w planie Free ich nie ma. W ustawieniach konektorów dodaj własny konektor zdalny, wklej adres serwera i wybierz OAuth: Perplexity zarejestruje się dynamicznie i otworzy ekran zgody Fakturnii. Jeśli zamiast OAuth wybierzesz klucz API, podaj klucz fmcp_…, który serwer przyjmuje w nagłówku Authorization: Bearer.

GitHub Copilot (VS Code, JetBrains, Eclipse, Xcode)#

Tryb agenta GitHub Copilot łączy się ze zdalnymi serwerami MCP i loguje przez OAuth z rejestracją dynamiczną. W VS Code (wersja 1.101 lub nowsza) dodaj do projektu plik .vscode/mcp.json:

{
  "servers": {
    "fakturnia": {
      "type": "http",
      "url": "https://prod.api.fakturnia.pl/mcp"
    }
  }
}

Następnie uruchom serwer („Start" nad jego wpisem w pliku). VS Code otworzy ekran zgody Fakturnii w przeglądarce, a narzędzia pojawią się w czacie Copilota w trybie agenta. W JetBrains, Eclipse i Xcode dodaj ten sam adres w konfiguracji MCP wtyczki GitHub Copilot; logowanie przebiega tak samo, przez rejestrację dynamiczną.

Cursor, Windsurf i inne klienty MCP#

Serwer typu HTTP z adresem powyżej. Klient z obsługą OAuth loguje się w przeglądarce; klient bez OAuth używa klucza dostępu:

{
  "mcpServers": {
    "fakturnia": {
      "url": "https://prod.api.fakturnia.pl/mcp",
      "headers": { "Authorization": "Bearer fmcp_..." }
    }
  }
}

Własny agent (Claude API, OpenAI Responses API)#

Serwer działa jako zdalny serwer MCP w Messages API (mcp_servers z url i authorization_token równym kluczowi fmcp_… albo access tokenowi OAuth). Ten sam wzorzec działa w OpenAI Responses API (tools: [{ type: "mcp", server_url, authorization }]).

Uwierzytelnianie#

OAuth 2.1 (zalecane)#

Przepływ authorization code z PKCE S256, zgodny z sekcją autoryzacji specyfikacji MCP:

1. Klient odczytuje metadane zasobu, potem metadane serwera autoryzacji (code_challenge_methods_supported: ["S256"], client_id_metadata_document_supported: true, authorization_response_iss_parameter_supported: true).
2. Klient identyfikuje się jednym z trzech sposobów: rejestracja dynamiczna (POST /mcp/oauth/register, klienci publiczni, redirect_uris tylko https:// albo http://localhost), dokument client_id (client_id jest adresem HTTPS dokumentu JSON z redirect_uris; serwer pobiera go z ochroną przed SSRF i buforuje) albo klient prekonfigurowany (wydawany przez Fakturnię dla konektorów, które wymagają stałego client_id i sekretu).
3. GET /mcp/oauth/authorize z response_type=code, code_challenge, code_challenge_method=S256, state, resource=https://prod.api.fakturnia.pl/mcp (RFC 8707; brak resource oznacza zasób /mcp). Serwer przekierowuje do aplikacji Fakturnia na ekran zgody. Nieznany client_id albo redirect_uri spoza rejestracji kończy się stroną błędu, nigdy przekierowaniem.
4. Zalogowany użytkownik (właściciel albo pracownik) widzi nazwę klienta, host powrotu, zakres dostępu i plan, po czym zezwala albo odmawia. Odpowiedź autoryzacji niesie code, state i iss.
5. POST /mcp/oauth/token (grant_type=authorization_code, code_verifier, redirect_uri, resource) zwraca access_token (JWT, 1 godzina, audience równe adresowi serwera) i refresh_token (30 dni, rotowany przy każdym odświeżeniu; ponowne użycie zużytego tokenu unieważnia całe połączenie).

Stan konta jest sprawdzany przy każdym żądaniu, nie z tokenu: rozłączenie w aplikacji, dezaktywacja pracownika, zmiana uprawnień albo wygaśnięcie planu działają natychmiast.

Klucz dostępu fmcp_…#

Dla klientów bez OAuth. Użytkownik tworzy klucz w aplikacji (Integracje, Asystent AI, Klucze dostępu): etykieta, ważność do 90 dni, sekret pokazany raz. Klucz ma dokładnie uprawnienia osoby, która go utworzyła, i jest przekazywany jako Authorization: Bearer fmcp_…. Odwołanie działa natychmiast; właściciel konta widzi i odwołuje klucze pracowników.

Uprawnienia i plan#

• Właściciel konta widzi wszystkie narzędzia poza konfiguracją integracji (webhooki, konta pracownicze) i poza tym, co nigdy nie trafia do MCP: konfiguracja KSeF (token KSeF w argumentach), pobieranie PDF (binaria), dane skrzynek pocztowych poza odczytem.
• Pracownik widzi tylko narzędzia odpowiadające jego uprawnieniom z panelu (np. „Podgląd dokumentów" daje browseDocuments i getDocument, „Wystawianie i edycja dokumentów" dodaje prepareDocument, issueDocument, patchDocument). Narzędzie niewidoczne na liście jest niedostępne także przy wywołaniu; odpowiedź nie rozróżnia „nie istnieje" od „brak uprawnień".
• Plan. Asystent AI jest funkcją planu MAX: podłączenie konta (ekran zgody) i utworzenie klucza fmcp_… wymagają aktywnego planu MAX, inaczej odpowiedź to 403 SUBSCRIPTION_REQUIRED. Gdy plan wygaśnie albo spadnie poniżej MAX, działają tylko getAccountOverview, getDictionaries i lookupCompanyByNip. Pozostałe narzędzia zostają na liście z prefiksem [WYMAGA PLANU MAX …] i zwracają isError z wyjaśnieniem, żeby model mógł powiedzieć, czego brakuje, zamiast udawać, że funkcji nie ma.

Narzędzia#

Lista zależy od uprawnień i planu, pełny zestaw poniżej. Narzędzia oznaczone jako generowane odpowiadają 1:1 operacjom REST API (ten sam operationId, te same pola), więc ich schematy znajdziesz w specyfikacji OpenAPI.

Prowadzone wystawianie dokumentu#

Surowe createDocument nie jest wystawione jako narzędzie. Zamiast niego:

1. prepareDocument przyjmuje pełne ciało dokumentu (schemat identyczny z POST /documents: documentType, issueDate, buyerId albo buyer, products, płatność, adnotacje), uruchamia pełną walidację bez zapisu i zwraca:

{
  "previewId": "b7Jk…",
  "expiresAt": "2026-09-26T12:15:00.000Z",
  "preview": {
    "documentType": "FakturaVAT",
    "documentNumber": "FV/12/09/2026",
    "seller": { "name": "Firma Testowa", "nip": "5261040828" },
    "buyer": { "name": "Beta Sp. z o.o.", "nip": "5252248481", "street": "Prosta 1", "postalCode": "00-001", "city": "Warszawa" },
    "products": [{ "name": "Usługa doradcza", "quantity": 2, "unitOfMeasure": "szt.", "netPrice": 500, "vatRate": 23 }],
    "totals": { "netSum": 1000, "vatSum": 230, "grossSum": 1230, "currency": "PLN" },
    "payment": { "method": "przelew", "statusId": 1, "paymentDeadlineDate": "2026-10-10" }
  },
  "warnings": [
    { "code": "NEW_CONTRACTOR", "message": "Nabywca „Beta Sp. z o.o." nie występował wcześniej w kontrahentach…" }
  ],
  "summaryText": "Faktura VAT nr FV/12/09/2026 (data wystawienia 2026-09-26)\nSprzedawca: …\nRazem: netto 1 000,00 zł, VAT 230,00 zł, brutto 1 230,00 zł\n…",
  "nextStep": "Pokaż użytkownikowi summaryText razem z ostrzeżeniami i zapytaj, czy wystawić dokument…"
}

Ostrzeżenia: POSSIBLE_DUPLICATE (ten sam nabywca, kwota i typ w ostatnich 30 dniach), NEW_CONTRACTOR, ISSUE_DATE_IN_FUTURE, ISSUE_DATE_OLD, PAYMENT_DEADLINE_BEFORE_ISSUE, SALE_DATE_AFTER_ISSUE, NO_ITEMS, ZERO_QUANTITY, ZERO_PRICE, FOREIGN_CURRENCY_NO_RATE, HIGH_AMOUNT, KSEF_BUYER_ADDRESS_MISSING, BANK_ACCOUNT_INVALID (numer rachunku na dokumencie nie przechodzi cyfr kontrolnych). Podgląd zawiera też payment.bankAccount: rachunek sprzedawcy, który trafi na dokument (domyślny rachunek konta przy płatności przelewem). Błąd walidacji wraca jako isError z kodem i listą pól z External API (422 VALIDATION_ERROR, PAYMENT_DEADLINE_REQUIRED itd.).

Brakujące pola uzupełniają ustawienia konta tak jak w aplikacji (uwagi, podpisy, miejsce wystawienia, automatyczne adnotacje, podstawa zwolnienia z VAT, płatność, stawka VAT): podgląd wymienia je w preview.appliedDefaults i w summaryText, żeby model powiedział o nich użytkownikowi. Szczegóły w Tworzeniu dokumentów. Ostrzeżenia dotyczące adnotacji: VAT_EXEMPTION_BASIS_MISSING (stawka zw bez podstawy zwolnienia), REVERSE_CHARGE_ANNOTATION_MISSING i REVERSE_CHARGE_WITHOUT_OO_RATE (odwrotne obciążenie niespójne ze stawką oo), WDT_BUYER_VAT_UE_MISSING (0% WDT bez VAT UE nabywcy), INVOICE_ALREADY_CORRECTED (faktura ma już korektę).

2. Model pokazuje użytkownikowi summaryText i ostrzeżenia, użytkownik potwierdza.
3. issueDocument({ previewId, confirm: true, sendToKsef?: false }) wystawia dokładnie zapisany podgląd (model nie ma jak zmienić danych między podglądem a wystawieniem), z kluczem idempotencji, i zwraca document (id, numer, kwota), appUrl (podgląd w aplikacji) oraz ksef (wynik wysyłki, gdy sendToKsef=true). Podgląd jest jednorazowy, ważny 15 minut i przypisany do osoby, która go przygotowała.

Dokumenty magazynowe#

prepareWarehouseDocument działa tak samo dla WZ, PZ, PW, RW i MM (schemat POST /warehouse/documents): pozycje wskazują produkty z kartoteki (productId z browseProducts), podgląd pokazuje magazyn, stan przed i po każdej pozycji, braki towaru i wartości z ustawień, a canIssue: false oznacza, że brak towaru zablokuje wystawienie (model pyta użytkownika, co zrobić; allowNegativeStock tylko na jego wyraźne życzenie). Wystawienie to ten sam issueDocument. Pracownik z uprawnieniem do dokumentów magazynowych widzi prepareWarehouseDocument i issueDocument, ale nie prepareDocument. Zasady modułu: Magazyn.

Zasady wspólne dla narzędzi#

• confirm=true jest wymagany przez narzędzia nieodwracalne (delete*, sendDocumentToKsef, issueDocument). Bez niego narzędzie nic nie zmienia i odpowiada instrukcją dla modelu.
• Argumenty spoza schematu przy zapisie kończą się odmową z listą obsługiwanych pól (pole nie ginie po cichu); przy odczycie są logowane.
• Listy mają domyślnie 25 wierszy i maksymalnie 100 (itemsPerPage, currentPage); większe wartości są przycinane z adnotacją w meta.hint.
• Rozmiar wyniku jest ograniczony do 120 000 znaków; większy wynik wraca jako błąd z instrukcją zawężenia zapytania zamiast obciętego JSON-a.
• Koperta wyniku. Treść narzędzia jest otoczona znacznikami [DANE_NARZEDZIA_START] i [DANE_NARZEDZIA_END], a błędy mają prefiks [HTTP <status>]. Instrukcje serwera mówią modelowi, że wyniki narzędzi to dane, nie polecenia.
• Instrukcje serwera (instructions w odpowiedzi initialize i w server/discover) zawierają nazwę firmy, kto jest połączony (właściciel czy pracownik), stan planu i kolejność kroków przy wystawianiu dokumentu.

Limity i bezpieczeństwo#

• Limity: 120 wywołań na minutę na konto Fakturnii (właściciel i pracownicy razem), 240 na minutę na adres IP przed uwierzytelnieniem, 10 rejestracji klientów na minutę na IP, 30 wymian tokenu na minutę na IP. Odpowiedź 429 niesie Retry-After. Fakturnia może dodatkowo ustawić limit wywołań na 30 dni; wyczerpany limit wraca jako isError z wyjaśnieniem.
• Wywołania asystenta są widoczne w logach REST API w aplikacji, a limity REST API Twoich własnych integracji pozostają od nich niezależne.
• Sekrety nigdy nie trafiają do modelu: token KSeF, hasła skrzynek, sekrety kluczy API i webhooków są poza zasięgiem narzędzi.
• Każde wykonanie narzędzia jest zapisywane (kto, którym poświadczeniem, jakie narzędzie, wynik) i widoczne w aplikacji w sekcji „Ostatnia aktywność".
• Rozłączenie aplikacji, odwołanie klucza, dezaktywacja pracownika i wygaśnięcie planu działają od następnego żądania.

Przykład: jedno wywołanie JSON-RPC#

POST /mcp HTTP/1.1
Host: sandbox.api.fakturnia.pl
Authorization: Bearer fmcp_...
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: browseDocuments

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "browseDocuments",
    "arguments": { "dateFrom": "2026-09-01", "dateTo": "2026-09-30", "documentType": "FakturaVAT" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "my-agent", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Odpowiedź to result.content[0].text z kopertą danych i result.isError.

Przykładowe polecenia dla asystenta#

• „Wystaw fakturę VAT dla Nowak Sp. z o.o. za usługę doradczą: 2 godziny po 250 zł netto, termin płatności 14 dni."
• „Pokaż faktury z tego miesiąca, które nie są jeszcze opłacone, i podsumuj kwotę."
• „Znajdź w GUS firmę o NIP 5252248481 i dodaj ją do kontrahentów."
• „Oznacz fakturę FV/12/09/2026 jako zapłaconą dzisiaj przelewem."
• „Ile sprzedałem w trzecim kwartale w podziale na kontrahentów?"
• „Przyjmij na magazyn 20 krzeseł biurowych od Fabryki Mebli po 120 zł netto."
• „Wystaw korektę do FV/12/09/2026: klient zwrócił jeden laptop."

Asystent zaczyna od getAccountOverview, dobiera nabywcę z kontrahentów albo z GUS, przygotowuje podgląd, pokazuje go i dopiero po potwierdzeniu wystawia dokument. Do KSeF wysyła wyłącznie na wyraźne życzenie. KSeF już obowiązuje, więc faktura wystawiona przez asystenta trafia do systemu tak samo jak faktura wystawiona ręcznie: po Twojej decyzji.

Zobacz też#

• Dla agentów i botów: maszynowo czytelne zasoby dokumentacji.
• Uwierzytelnianie i Tworzenie dokumentów: reguły, które narzędzia MCP dziedziczą z REST API.
• Wysyłka do KSeF: asynchroniczny przebieg, statusy i UPO.