Serwer MCP KRONENWERK: podłącz agenta AI do swojej księgowości

KRONENWERK udostępnia serwer Model Context Protocol (MCP) pod adresem https://kronenwerk.org/api/extern/mcp. Agent AI mówiący MCP przez Streamable HTTP uwierzytelnia się przez OAuth 2.1 (Claude, ChatGPT i inni hostowani asystenci) albo tym samym kluczem API Bearer co API REST, czyta klientów, faktury, transakcje i raporty jednej firmy oraz tworzy szkice, transakcje i notatki. Czy może też wystawić fakturę, wysłać ją lub zaksięgować płatność, decyduje firma: domyślnie pozostają to czynności człowieka, a firma może je dopuścić w Ustawienia → Asystenci AI do ustalonego przez siebie limitu kwoty, przy czym każda czynność jest zapisywana. Serwer MCP jest częścią planu Enterprise.

Czym jest MCP

Model Context Protocol to otwarta specyfikacja, opublikowana na modelcontextprotocol.io, która definiuje, w jaki sposób aplikacja AI (klient) odnajduje i wywołuje narzędzia oferowane przez system zewnętrzny (serwer). Komunikaty mają format JSON-RPC 2.0. Serwer publikuje listę narzędzi z nazwami, opisami i schematami wejściowymi JSON; model czyta te opisy, decyduje, co wywołać, a klient wysyła w jego imieniu żądanie tools/call. Wynik wraca jako treść, którą model może odczytać, oraz opcjonalnie jako ustrukturyzowany JSON.

Ustandaryzowane są dwa transporty: stdio dla serwera uruchamianego jako lokalny podproces oraz Streamable HTTP dla serwera dostępnego przez sieć. KRONENWERK jest usługą sieciową, dlatego implementuje wyłącznie Streamable HTTP. Protokół jest wersjonowany datami. Na dzień 2026-09-03 specyfikacja wskazuje 2026-07-28 jako bieżącą rewizję; wcześniejsze rewizje (2025-11-25, 2025-06-18, 2025-03-26) otwierają połączenie uzgodnieniem initialize, natomiast bieżąca rewizja przenosi wersję protokołu i tożsamość klienta w obiekcie _meta w każdym żądaniu i dodaje metodę server/discover. Serwer może obsługiwać więcej niż jedną rewizję na tym samym punkcie końcowym — i KRONENWERK tak robi.

Punkt końcowy, transport i uwierzytelnianie

Wszystko odbywa się pod jednym adresem i jedną metodą HTTP: POST https://kronenwerk.org/api/extern/mcp, treść application/json, jeden komunikat JSON-RPC na żądanie.

Uwierzytelnianie

Albo Authorization: Bearer greif_oauth_… — token dostępu OAuth 2.1 uzyskany w przepływie authorization code + PKCE pod /oauth/authorize i /oauth/token, z dynamiczną rejestracją klientów pod /oauth/register i odkrywaniem pod /.well-known/oauth-authorization-server (tak łączą się Claude i ChatGPT: właściciel firmy loguje się i wyraża zgodę raz) — albo Authorization: Bearer greif_live_… / greif_test_…, ten sam klucz API, który przyjmuje API REST, utworzony w ustawieniach KRONENWERK i związany z dokładnie jedną firmą. Żądanie bez ważnego poświadczenia otrzymuje 401 z WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource", za którym klienci MCP podążają, by rozpocząć logowanie. Zobacz uwierzytelnianie.

Najemca (tenant)

Firma, do której dociera agent, to firma klucza. W całym interfejsie protokołu nie ma parametru organizacji, więc agent nie może wybierać ani wyliczać firm.

Sesja

Brak. Serwer nie utrzymuje sesji i nie wydaje MCP-Session-Id. Każde żądanie niesie własne poświadczenie i własną wersję protokołu. GET (opcjonalny strumień serwer→klient) i DELETE (zakończenie sesji) odpowiadają 405 Method Not Allowed, co specyfikacja przewiduje dla serwerów, które ich nie oferują.

Wersje protokołu

2026-07-28 (_meta w każdym żądaniu) oraz oparte na uzgodnieniu 2025-11-25, 2025-06-18 i 2025-03-26. Żądanie wskazujące inną wersję otrzymuje błąd JSON-RPC -32022 z listą obsługiwanych wersji w data.supported. Żądanie bez żadnej wersji jest obsługiwane jako klient starszego typu (legacy).

Metody

server/discover, initialize, tools/list, tools/call, ping. Brak zasobów, promptów, samplingu i powiadomień; serwer nigdy nie otwiera strumienia. Pakiety (batch) nie są akceptowane; każde żądanie to jeden komunikat.

Origin

Żądanie z nagłówkiem Origin innej witryny jest odrzucane kodem 403, czego specyfikacja wymaga jako ochrony przed DNS rebinding. Klienci nieprzeglądarkowi nie wysyłają Origin i nie są tym objęci.

Limit żądań

Punkt końcowy MCP znajduje się w tym samym łańcuchu filtrów co REST API, więc budżet klucza — 240 żądań, uzupełniany w tempie około dwóch na sekundę — obejmuje oba razem. Po przekroczeniu budżetu odpowiedzią jest 429 z nagłówkiem Retry-After. Zob. limity żądań.

Plan

Ważny klucz, którego firma nie jest w planie Enterprise, otrzymuje 403 z kodem błędu aplikacji 1402 i zdaniem wyjaśniającym. Plany opisano na stronie cennika.

W przypadku klientów w bieżącej rewizji serwer sprawdza również zgodność wprowadzonych przez specyfikację nagłówków lustrzanych — MCP-Protocol-Version, Mcp-Method oraz, przy tools/call, Mcp-Name — z treścią żądania i na niezgodność odpowiada błędem -32020 oraz HTTP 400. Klienci zbudowani na utrzymywanym SDK MCP robią to automatycznie.

Narzędzia

Istnieje dwadzieścia dwa narzędzia w trzech klasach: narzędzia odczytu, które nic nie zmieniają; narzędzia szkiców, które tworzą coś bezczynnego, na czym człowiek musi jeszcze działać; oraz narzędzia działania, które czynią fakt finansowy prawdziwym i są oferowane tylko firmom, które wybrały poziom Działaj w granicach limitu. tools/list zwraca tylko narzędzia, na które pozwalają zakresy poświadczenia i poziom firmy; klucz z samym invoices:read widzi czytniki faktur i nic więcej, a firma na poziomie domyślnym nigdy nie widzi narzędzia działania. Zakresy są takie same jak w API REST.

Kwoty są zwracane jako liczba jednostek podrzędnych z kodem waluty — {"minor": 105910, "currency": "EUR"} to 1 059,10 EUR — nigdy jako sformatowany ciąg znaków. Daty to dni kalendarzowe w formacie YYYY-MM-DD. Każdy obiekt utworzony przez narzędzie szkiców jest zapisywany jako utworzony przez dany klucz API, a firma widzi tę atrybucję w produkcie. Model nie może przedstawić swojej pracy jako pracy osoby.

Poziomy i granice bezpieczeństwa

To firma — nie agent i nie KRONENWERK — decyduje, jak daleko może sięgać oprogramowanie. W Ustawienia → Asystenci AI właściciel ustala jeden z trzech poziomów, a ustawienie dotyczy jednakowo każdego podłączonego asystenta i każdego klucza:

• Tylko odczyt — dwanaście narzędzi odczytu. Szkice są wyłączone; wywołanie szkicu otrzymuje zdanie, które to mówi.
• Czytaj i proponuj (domyślnie) — narzędzia odczytu plus siedem narzędzi szkiców. Nic, co agent robi na tym poziomie, nie jest faktem finansowym; człowiek wystawia, wysyła i księguje.
• Działaj w granicach limitu — dodaje issue_invoice, send_invoice i record_payment. Każda pojedyncza czynność jest sprawdzana względem limitu kwoty brutto w walucie bazowej firmy, w ramach własnej transakcji, więc faktura przekraczająca limit jest w całości wycofywana: żaden numer nie zużyty, żaden zapis, żaden e-mail.

Na żadnym poziomie żadne narzędzie nie anuluje ani nie koryguje wystawionego dokumentu, nie zatwierdza ani nie opłaca faktury dostawcy, nie księguje zapisu dziennika, nie zamyka okresu ani nie tworzy, nie rotuje i nie unieważnia poświadczeń oraz ustawień. To pozostaje przy osobie zalogowanej w KRONENWERK.

Gdy model prosi o czynność, której firma nie dopuściła — record_payment na poziomie domyślnym, cancel_invoice na każdym poziomie — serwer nie odpowiada „nieznane narzędzie”, co model odczytuje jako problem z nazwą i próbuje obejść. Odpowiada zwykłym wynikiem oznaczonym isError: true, którego tekst podaje regułę, mówi, że żadna część żądania nie została wykonana, i wskazuje ustawienie, które zmieniłby człowiek. Model przekazuje coś prawdziwego i przestaje.

Każda czynność i każdy szkic są zapisywane w rejestrze autorstwa firmy z narzędziem, połączeniem i czasem, a usługi poniżej piszą swoje zwykłe wiersze audytu pod połączeniem, a nie pod osobą, więc ślad zawsze mówi, który asystent co zrobił. Inne właściwości wynikają z transportu: odczyty podlegają tym samym uprawnieniom co odpowiedni ekran; identyfikatory innej firmy są zgłaszane jako nieznalezione, a nie zabronione; awarie wewnętrzne są opisywane jednym stałym zdaniem bez stack trace, więc nazwy tabel i ścieżki plików nigdy nie trafiają do kontekstu modelu; a połączenie można w każdej chwili unieważnić w ustawieniach, co kończy dostęp tego agenta przy następnym żądaniu. Obowiązują te same zasady co dla API REST — zobacz bezpieczeństwo API.

Podłączanie klienta

Większość klientów MCP przyjmuje konfigurację JSON wskazującą serwery zdalne. Ogólny wpis dla KRONENWERK wygląda następująco; nazwy kluczy obiektu zewnętrznego różnią się między klientami, pola wewnętrzne nie:

{
  "mcpServers": {
    "kronenwerk": {
      "type": "http",
      "url": "https://kronenwerk.org/api/extern/mcp",
      "headers": {
        "Authorization": "Bearer greif_live_XXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

Podczas budowania należy używać klucza greif_test_. Trafia on do tego samego punktu końcowego w trybie testowym dla firmy, która go utworzyła; nie ma osobnego hosta sandbox. Klucz należy utworzyć tylko z zakresami, których agent potrzebuje: asystent odpowiadający na pytanie „kto jest nam winien pieniądze” potrzebuje reports:read i customers:read i niczego więcej.

Bez klienta punkt końcowy można przetestować za pomocą curl. Uzgodnienie w starszym stylu i wywołanie narzędzia:

curl -s https://kronenwerk.org/api/extern/mcp \
  -H "Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-11-25","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}'

curl -s https://kronenwerk.org/api/extern/mcp \
  -H "Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"list_receivables","arguments":{"as_of":"2026-09-03"}}}'

Wynik drugiego wywołania zawiera raport zarówno jako czytelny tekst w content, jak i jako JSON w structuredContent. Klient w bieżącej rewizji wysyła te same komunikaty z wersją w params._meta["io.modelcontextprotocol/protocolVersion"] i nagłówkami lustrzanymi; serwer odpowiada na obie formy.

MCP czy REST: czego użyć

MCP należy używać wtedy, gdy o tym, o co zapytać, decyduje w czasie działania model językowy. REST API — gdy decyduje Państwa własny kod. Oba interfejsy odczytują te same dane pod tym samym kluczem i zakresami, więc nic nie wymusza wyboru, a jeden system może korzystać z obu.

Interfejs REST opisano w przeglądzie API księgowości, referencji i szybkim starcie. Wzorce integracji na poziomie aplikacji omówiono w artykule podłączanie Państwa SaaS.

Jak KRONENWERK to obsługuje

SUPPORTED Serwer MCP działa pod https://kronenwerk.org/api/extern/mcp dla firm w planie Enterprise, mówi Streamable HTTP dla rewizji protokołu 2026-07-28, 2025-11-25, 2025-06-18 i 2025-03-26, uwierzytelnia przez OAuth 2.1 lub klucz API i oferuje każdej firmie dwanaście narzędzi odczytu i siedem narzędzi szkiców, a firmom, które w Ustawienia → Asystenci AI dopuściły działanie, trzy narzędzia działania — każda czynność ograniczona własnym limitem firmy i zapisana. Anulowanie, korygowanie, płacenie dostawcom, księgowanie, zamykanie i konfigurowanie celowo pozostają bez narzędzia. Ten sam serwer działa z kluczem greif_test_ w trybie testowym. Serwer MCP, API REST, webhooki i katalog integracji są częścią planu Enterprise; zobacz cennik i przegląd dla programistów.