Serwer MCP

Nordlet obsługuje Model Context Protocol pod adresem https://api.nordlet.com/mcp. Podłączony do niego asystent AI może wyszukiwać w API, odczytywać schemat żądania dla dowolnej operacji i ją wywoływać, korzystając z tego samego klucza API, kontekstu spółki i uprawnień (scopes) co przy żądaniu bezpośrednim. Każde wywołanie narzędzia jest zwykłym żądaniem API: jest uwierzytelniane, podlega limitom prędkości (rate limiting) oraz jest rozliczane w taki sam sposób, a wywołanie modyfikujące dane wpływa bezpośrednio na księgi rachunkowe spółki.

Połączenie

Endpoint obsługuje protokół Streamable HTTP i jest uwierzytelnianym kluczem API Bearer z sekcji Pierwsze kroki. W programie Claude Code:

claude mcp add --transport http nordlet https://api.nordlet.com/mcp --header "Authorization: Bearer nl_..."

Dowolny inny klient MCP przyjmuje ten sam adres URL oraz nagłówek. Klucz z uprawnieniem *:read może wywoływać wyłącznie operacje odczytu - w przypadku braku uprawnień narzędzia zgłaszają błąd 403 zwrócony przez API.

Narzędzia

Trzy narzędzia obsługują wszystkie operacje dostępne w API:

Narzędzie	Działanie
search_operations	Znajduje operacje na podstawie słów w ich nazwie, ścieżce, podsumowaniu lub opisie, opcjonalnie w obrębie wskazanego modułu (sales, bank, reports itd.). Bez podania zapytania zwraca listę modułów.
describe_operation	Zwraca metodę, ścieżkę, opis oraz schemat żądania JSON dla wybranej operacji; parametr includeResponse: true dodaje schemat odpowiedzi 200.
call_operation	Uruchamia wybrane żądanie z ciałem (body) w formacie JSON. Treść odpowiedzi jest zwracana jako JSON; odpowiedź 4xx lub 5xx jest zwracana jako błąd narzędzia zawierający status oraz kopertę błędu. Opcjonalny parametr idempotencyKey jest wysyłany jako nagłówek Idempotency-Key, dzięki czemu ponowienie żądania z tym samym kluczem zwraca pierwszą odpowiedź zamiast powtarzać skutek operacji.

Najczęściej używane operacje są również dostępne jako bezpośrednie narzędzia z własnymi schematami żądań, dzięki czemu asystent widzi ich pola bez konieczności wyszukiwania: partners_list, partners_get, partners_create, partners_find_or_create, catalog_items_list, sales_invoices_list, sales_invoices_get, sales_invoices_create, sales_invoices_issue, sales_invoices_send, purchases_invoices_list, purchases_invoices_create, purchases_invoices_register, bank_transactions_list, bank_transactions_import, bank_transactions_match, ledger_journal_transactions_list, reports_trial_balance, reports_financial_statements, reports_vat_summary i reports_debt_aging. Każde narzędzie posiada odpowiednie adnotacje MCP (readOnlyHint, destructiveHint), które informują klienta, czy dana operacja zapisuje dane.

Indeks operacji oraz schematy są generowane z tej samej specyfikacji OpenAPI co Dokumentacja API oraz pakiety SDK, dzięki czemu każda nowo dodana funkcja API pojawia się w search_operations wraz z wydaniem aktualizacji. Instrukcje serwera przypominają asystentowi o przyjętych konwencjach: kwoty są przekazywane jako ciągi znaków o stałym przecinku (decimal strings), listy obsługują parametry page, pageSize, sort oraz filter, a deklaracje podatkowe specyficzne dla danego kraju zwracają błąd 422 w przypadku spółki zarejestrowanej poza tym krajem.