Serwer MCP · OAuth 2.1 · REST

Agenci AI w Centrum Finansowe: Claude, Hermes i ChatGPT pracują na Twoich fakturach

Podłącz asystenta AI do konta, a wystawi fakturę, wyśle ją do KSeF, zaksięguje koszt ze skanu, zarejestruje płatność i zmieni ustawienia firmy — z Twoimi uprawnieniami, we wszystkich firmach na koncie. Łączysz się adresem https://ksiegowosc.aiagenthub.pl/mcp przez OAuth albo kluczem API z panelu.

56 narzędzi, ten sam zakres co panel w przeglądarce. Działania nieodwracalne agent wykonuje dopiero po Twojej zgodzie.

Claude i Hermes

Konektor w claude.ai, Claude Code, Hermes Agent, ChatGPT.

Wiele firm

Agent wybiera firmę po nazwie lub NIP-ie; klucz można zawęzić.

OAuth lub klucz

Logowanie i zgoda albo klucz API z zakresem i datą ważności.

Pełna kontrola

Dziennik wywołań i cofnięcie dostępu jednym kliknięciem.

Jak podłączyć agenta

Claude (claude.ai, aplikacja Claude Desktop i mobilna)

Logowanie przez OAuth — bez kopiowania kluczy. Claude zapyta o zgodę na Twoim koncie Centrum Finansowe i od tej chwili działa na wszystkich Twoich firmach.

  1. Otwórz Ustawienia → Konektory (Settings → Connectors) i wybierz Dodaj własny konektor.
  2. Nazwa: Centrum Finansowe, adres serwera:
https://ksiegowosc.aiagenthub.pl/mcp
  1. Kliknij Połącz, zaloguj się na swoje konto i zatwierdź dostęp.
  2. W rozmowie włącz konektor i napisz np. „Pokaż moje firmy i nieopłacone faktury sprzedaży”.

Konektory działają w planach Claude, które pozwalają dodawać własne serwery MCP. W organizacji (Team, Enterprise) konektor dodaje właściciel organizacji.

Claude Code (terminal)

Z logowaniem OAuth (otworzy się przeglądarka):

claude mcp add --transport http centrum-finansowe https://ksiegowosc.aiagenthub.pl/mcp

Albo z kluczem API (serwer, CI, bez przeglądarki). Klucz tworzysz po zalogowaniu: Panel → Agenci AI (https://ksiegowosc.aiagenthub.pl/dashboard/agents).

claude mcp add --transport http centrum-finansowe https://ksiegowosc.aiagenthub.pl/mcp \
  --header "Authorization: Bearer cfa_TWÓJ_KLUCZ_Z_PANELU"

Sprawdzenie: /mcp w sesji Claude Code pokazuje stan połączenia i listę narzędzi.

Hermes Agent

Hermes czyta serwery MCP z ~/.hermes/config.yaml. Na komputerze z przeglądarką wystarczy OAuth:

~/.hermes/config.yaml
mcp_servers:
  centrum_finansowe:
    url: "https://ksiegowosc.aiagenthub.pl/mcp"
    auth: oauth

Na serwerze (Hermes uruchomiony jako usługa, np. w Aderlo Cloud) użyj klucza API zapisanego w ~/.hermes/.env. Klucz tworzysz po zalogowaniu: Panel → Agenci AI (https://ksiegowosc.aiagenthub.pl/dashboard/agents).

~/.hermes/.env
CENTRUM_FINANSOWE_API_KEY=cfa_TWÓJ_KLUCZ_Z_PANELU
~/.hermes/config.yaml
mcp_servers:
  centrum_finansowe:
    url: "https://ksiegowosc.aiagenthub.pl/mcp"
    headers:
      Authorization: "Bearer ${CENTRUM_FINANSOWE_API_KEY}"
    timeout: 120

Potem /reload-mcp w rozmowie (albo restart Hermesa). Logowanie OAuth z terminala bez przeglądarki:

hermes mcp login centrum_finansowe --flow device

Chcesz, żeby Hermes tylko czytał dane? Utwórz klucz z zakresem „tylko odczyt” albo wyklucz narzędzia zapisujące w konfiguracji: tools: { exclude: [send_to_ksef, unpost_document, delete_company] }.

ChatGPT i inni klienci MCP

Każdy klient obsługujący zdalne serwery MCP (Streamable HTTP) z OAuth: w ChatGPT — Ustawienia → Aplikacje i konektory → tryb dewelopera → nowy konektor z adresem https://ksiegowosc.aiagenthub.pl/mcp i uwierzytelnianiem OAuth. Cursor, Windsurf, VS Code i inne przyjmują ten sam adres albo konfigurację JSON:

{
  "mcpServers": {
    "centrum-finansowe": {
      "type": "http",
      "url": "https://ksiegowosc.aiagenthub.pl/mcp",
      "headers": { "Authorization": "Bearer cfa_TWÓJ_KLUCZ_Z_PANELU" }
    }
  }
}

REST API (n8n, Make, własne skrypty)

Te same narzędzia co w MCP: POST https://ksiegowosc.aiagenthub.pl/api/v1/tools/<nazwa> z argumentami w JSON. Opis OpenAPI: https://ksiegowosc.aiagenthub.pl/openapi.json.

curl -s https://ksiegowosc.aiagenthub.pl/api/v1/tools/list_companies \
  -H "Authorization: Bearer cfa_TWÓJ_KLUCZ_Z_PANELU" \
  -H "Content-Type: application/json" -d '{}'

Wiele firm na jednym koncie

  • Agent widzi wszystkie firmy z Twojego konta. Zaczyna od narzędzia list_companies, a w każdym poleceniu przekazuje company_id — wystarczy, że napiszesz nazwę albo NIP firmy („wystaw fakturę dla ACME w firmie Kowalski sp. z o.o.”).
  • Gdy nie wskażesz firmy, a jest ich kilka, agent zapyta, której dotyczy polecenie.
  • Klucz API możesz ograniczyć do wybranych firm — np. osobny Hermes dla każdego klienta biura rachunkowego. Taki agent nie zobaczy pozostałych firm.
  • Każda firma ma własne integracje (Systim, token KSeF dla swojego NIP-u) i własne dokumenty.

Co agent może, a czego nie

  • Może wszystko, co Ty w panelu: wystawiać i księgować faktury, wgrywać koszty do odczytu (OCR), rejestrować płatności, wysyłać do KSeF, zmieniać ustawienia firm, kontrahentów i integracje.
  • Działania nieodwracalne (wysyłka do KSeF, wycofanie z ksiąg, usunięcie firmy) są oznaczone dla agenta jako destrukcyjne — Claude i inni klienci pytają Cię o zgodę przed ich wykonaniem.
  • Narzędzia agenta nie zmieniają hasła, e-maila ani 2FA, nie zwracają haseł API ani tokenów KSeF i nie obejmują funkcji administracyjnych.
  • Każde wywołanie trafia do dziennika w panelu (Agenci AI → Dziennik). Dostęp cofasz jednym kliknięciem.

Narzędzia agenta

Konto i firmy

  • list_companies — Lista firm na koncie · odczyt
  • get_company — Ustawienia firmy · odczyt
  • update_company — Zmień ustawienia firmy · zmienia dane
  • create_company — Dodaj firmę · zmienia dane
  • delete_company — Usuń firmę · nieodwracalne, wymaga zgody
  • lookup_company_by_nip — Sprawdź NIP w rejestrach · odczyt
  • check_vat_registry — Sprawdź firmę w Białej Liście VAT · zmienia dane
  • get_dashboard_summary — Podsumowanie finansów firmy · odczyt
  • get_profile — Profil konta · odczyt
  • update_profile — Zmień profil konta · zmienia dane

Dokumenty

  • list_documents — Lista dokumentów · odczyt
  • get_document — Szczegóły dokumentu · odczyt
  • get_document_pdf — PDF dokumentu · odczyt
  • upload_document — Wgraj fakturę kosztową (OCR) · zmienia dane
  • update_document — Popraw dane dokumentu · zmienia dane
  • void_document — Anuluj niezaksięgowany dokument · nieodwracalne, wymaga zgody
  • refresh_document — Odśwież dokument z programu księgowego · zmienia dane
  • import_from_systim — Importuj dokumenty z Systim · zmienia dane

Faktury i księgowanie

  • preview_invoice — Sprawdź fakturę przed wystawieniem · odczyt
  • create_sales_invoice — Wystaw fakturę sprzedaży · zmienia dane
  • create_purchase_invoice — Zaewidencjonuj fakturę kosztową · zmienia dane
  • post_document — Zaksięguj dokument · zmienia dane
  • unpost_document — Wycofaj dokument z księgowości · nieodwracalne, wymaga zgody
  • register_payment — Zarejestruj płatność · zmienia dane
  • check_invoice_edit — Czy fakturę można edytować · odczyt
  • edit_invoice — Edytuj zaksięgowaną fakturę sprzedaży · zmienia dane
  • correct_invoice — Wystaw fakturę korygującą · zmienia dane

KSeF

  • send_to_ksef — Wyślij fakturę do KSeF · nieodwracalne, wymaga zgody
  • get_ksef_status — Status faktury w KSeF · zmienia dane
  • import_from_ksef — Pobierz faktury z KSeF · zmienia dane
  • list_ksef_register — Rejestr KSeF firmy · odczyt
  • get_ksef_invoice — Faktura z KSeF: XML, PDF i UPO · odczyt
  • get_sync_status — Stan pobierania i zgodności źródeł · odczyt
  • list_sync_conflicts — Konflikty importu KSeF · odczyt
  • resolve_sync_conflict — Zamknij konflikt importu · zmienia dane

Księgi w Systim

  • systim_accounting_setup — Forma księgowości w Systim · odczyt
  • systim_list_invoices — Rejestr faktur w Systim · odczyt
  • systim_list_ledger — Księga w Systim: dziennik, KPiR, ryczałt · odczyt
  • systim_list_payments — Płatności w Systim · odczyt
  • systim_get_record — Rekord z Systim · odczyt
  • systim_export_report — Raport z Systim: JPK_KR, bilans, RZiS · odczyt

Uzgodnienie i naprawy

  • reconcile_sources — Uzgodnij KSeF, panel, Systim i księgę · odczyt
  • propose_change — Zaproponuj zmianę (plan do zatwierdzenia) · odczyt
  • apply_change — Wykonaj zatwierdzony plan zmiany · zmienia dane
  • list_change_plans — Plany zmian i ich wyniki · odczyt

Kontrahenci

  • list_counterparties — Kontrahenci · odczyt
  • create_counterparty — Dodaj kontrahenta · zmienia dane
  • update_counterparty — Zmień kontrahenta · zmienia dane
  • delete_counterparty — Usuń kontrahenta · nieodwracalne, wymaga zgody

Integracje

  • get_integrations — Stan integracji · odczyt
  • connect_systim — Podłącz program księgowy Systim · zmienia dane
  • connect_ksef — Podłącz KSeF · zmienia dane
  • manage_ksef — Zarządzaj integracją KSeF · nieodwracalne, wymaga zgody

Abonament

  • get_subscription — Abonament i zużycie · odczyt
  • list_billing_invoices — Faktury za abonament · odczyt
  • get_billing_link — Link do płatności lub zmiany planu · zmienia dane

Adresy dla deweloperów

Pytania o agentów AI

Czy agent AI może wystawić fakturę w KSeF za mnie?

Tak. Po podłączeniu konta agent przygotowuje fakturę (create_sales_invoice), księguje ją w programie księgowym i — po Twojej zgodzie — wysyła do KSeF (send_to_ksef). Wysyłka do KSeF jest nieodwracalna, dlatego klienci MCP, tacy jak Claude, pytają o potwierdzenie przed jej wykonaniem.

Jak agent rozróżnia moje firmy?

Każda firma na koncie ma identyfikator. Agent zaczyna od listy firm (list_companies) i w każdym poleceniu podaje company_id. Wystarczy, że wskażesz firmę nazwą albo NIP-em; gdy firm jest kilka, a polecenie nie wskazuje żadnej, agent zapyta. Klucz API można ograniczyć do wybranych firm.

Czym różni się logowanie OAuth od klucza API?

OAuth wybierasz, gdy agent ma przeglądarkę (Claude, ChatGPT, Hermes na komputerze): logujesz się i zatwierdzasz dostęp, bez kopiowania sekretów. Klucz API jest dla agentów działających na serwerze (Hermes jako usługa, n8n, skrypty) — tworzysz go w panelu, wybierasz firmy i zakres (tylko odczyt albo odczyt i zmiany) i możesz go cofnąć.

Czy agent zobaczy moje hasło do Systim albo token KSeF?

Nie. Agent może je zapisać, gdy sam mu je podasz przy podłączaniu integracji, ale serwer szyfruje je i nigdy ich nie zwraca. Agent nie zmienia też hasła do konta, e-maila ani ustawień 2FA.

Gdzie widać, co zrobił agent?

W panelu, w zakładce Agenci AI: lista połączonych agentów i kluczy oraz dziennik każdego wywołania narzędzia (co, dla której firmy, z jakim wynikiem). Tam też cofasz dostęp.

For AI agents and developers (English)

Centrum Finansowe AI Agent HUB is a Polish invoicing and finance panel: KSeF e-invoices, purchase invoices with OCR, counterparties, payments and export to the Systim accounting program. The remote MCP server at https://ksiegowosc.aiagenthub.pl/mcp (Streamable HTTP) exposes 56 tools with read and write access on behalf of the signed-in user. Authenticate with OAuth 2.1 (PKCE, dynamic client registration), a panel API key (Bearer cfa_…) or the agent registration flow described in auth.md. One account can manage many companies: call list_companies first and pass company_id.