MCP server

Nordlet sprístupňuje protokol Model Context Protocol na adrese https://api.nordlet.com/mcp. K nemu pripojený asistent umelej inteligencie môže vyhľadávať v API, čítať schému požiadaviek ľubovoľnej operácie a volať ju s rovnakým kľúčom API, spoločnosťou a oprávneniami (scopes) ako pri priamej požiadavke. Každé volanie nástroja je bežnou požiadavkou API: autentifikuje sa, vzťahujú sa naň limity požiadaviek (rate limits) a účtuje sa rovnako ako ona, pričom modifikačné volanie mení účtovníctvo spoločnosti.

Pripojenie

Koncový bod (endpoint) komunikuje cez Streamable HTTP a autentifikuje sa pomocou kľúča API Bearer z časti Začíname. V programe Claude Code:

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

Akýkoľvek iný klient MCP vyžaduje rovnakú adresu URL a hlavičku. Kľúč s obmedzeným rozsahom oprávnení na *:read môže volať iba operácie čítania, pričom nástroje hlásia chýbajúce oprávnenie ako chybu API 403.

Nástroje

Tri nástroje pokrývajú každú operáciu API:

Nástroj	Čo robí
search_operations	Vyhľadáva operácie podľa slov v ich názve, ceste, súhrne alebo opise, voliteľne v rámci jedného modulu (sales, bank, reports, ...). Bez zadaného vyhľadávacieho dopytu vypíše zoznam modulov.
describe_operation	Vraciam metódu, cestu, opis a schému požiadavky JSON pre jednu operáciu; parameter includeResponse: true pridáva schému odpovede 200.
call_operation	Spustí jednu operáciu s telom JSON. Telo odpovede sa vráti vo formáte JSON; odpoveď 4xx alebo 5xx sa vráti ako chyba nástroja spolu so stavovým kódom a chybovou obálkou. Voliteľný kľúč idempotencyKey sa odošle ako hlavička Idempotency-Key, takže opakované volanie s rovnakým kľúčom vráti pôvodnú odpoveď namiesto opätovného vykonania akcie.

Najčastejšie používané operácie sú zároveň priamymi nástrojmi s vlastnými schémami požiadaviek, takže asistent vidí ich polia bez nutnosti vyhľadávania: 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 a reports_debt_aging. Každý nástroj obsahuje anotácie MCP (readOnlyHint, destructiveHint), ktoré klienta informujú o tom, či vykonáva zápis.

Register operácií a schémy sa generujú z rovnakého opisu OpenAPI ako referencia API a sady SDK, takže operácia pridaná do API sa objaví v nástroji search_operations spolu s verziou, v ktorej bola pridaná. Inštrukcie servera pripomínajú asistentovi zaužívané konvencie: peňažné čiastky sú desatinné reťazce, zoznamy akceptujú parametre page, pageSize, sort a filter, pričom daňové priznanie pre konkrétnu krajinu vráti chybu 422 v prípade spoločnosti sídliacej mimo tejto krajiny.