Server MCP

Nordlet supporta il Model Context Protocol all'indirizzo https://api.nordlet.com/mcp. Un assistente IA connesso può cercare nell'API, leggere lo schema di richiesta di qualsiasi operazione ed eseguirla, utilizzando la stessa chiave API, la stessa azienda e gli stessi permessi (scopes) di una richiesta diretta. Ogni chiamata a uno strumento (tool call) corrisponde a una richiesta API ordinaria: viene autenticata, sottoposta a limitazione di frequenza (rate limiting) e conteggiata allo stesso modo, mentre una chiamata con modifiche (mutating call) aggiorna la contabilità aziendale.

Connessione

L'endpoint utilizza il protocollo Streamable HTTP ed è autenticato tramite la chiave API Bearer descritta in Guida introduttiva. In Claude Code:

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

Qualsiasi altro client MCP richiede lo stesso URL e la stessa intestazione. Una chiave con permessi limitati a *:read può eseguire esclusivamente le operazioni di lettura; in caso di permessi mancanti, gli strumenti restituiscono un errore 403 dell'API.

Strumenti

Tre strumenti coprono tutte le operazioni dell'API:

Strumento	Funzione
search_operations	Trova le operazioni in base alle parole presenti nel nome, nel percorso, nel sommario o nella descrizione, eventualmente circoscrivendo la ricerca a un modulo specifico (sales, bank, reports, ...). Se non viene inserita alcuna query, elenca i moduli disponibili.
describe_operation	Restituisce il metodo, il percorso, la descrizione e lo schema di richiesta JSON di una specifica operazione; impostando includeResponse: true, viene aggiunto anche lo schema della risposta 200.
call_operation	Esegue un'operazione passando un corpo in formato JSON. Il corpo della risposta viene restituito come JSON; una risposta con codice 4xx o 5xx viene gestita come errore dello strumento, includendo lo stato e il busta di errore (error envelope). Un parametro opzionale idempotencyKey viene trasmesso tramite l'intestazione Idempotency-Key, consentendo alle chiamate ripetute con la stessa chiave di replicare la prima risposta senza duplicare gli effetti contabili.

Le operazioni più utilizzate sono disponibili anche come strumenti dedicati dotati di propri schemi di richiesta, consentendo all'assistente di visualizzarne i campi senza alcuna ricerca preventiva: 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 e reports_debt_aging. Ciascuno strumento include le annotazioni MCP (readOnlyHint, destructiveHint) che indicano al client se l'operazione comporta scritture.

L'indice delle operazioni e gli schemi sono generati a partire dalla stessa descrizione OpenAPI utilizzata per la Riferimento API e per gli SDK, pertanto ogni nuova operazione aggiunta all'API risulta disponibile in search_operations contestualmente al suo rilascio. Le istruzioni del server ricordano all'assistente le convenzioni in uso: gli importi sono stringhe decimali, le liste gestiscono i parametri page, pageSize, sort e filter, e le dichiarazioni fiscali specifiche per paese restituiscono un errore 422 se applicate a un'azienda registrata in un paese differente.