Server MCP (Assistenti IA)

Server MCP (Integrazione assistenti IA)

Collega il tuo account Lumabill ad assistenti IA come Claude, ChatGPT e Cursor tramite il Model Context Protocol (MCP). Una volta collegato, il tuo assistente IA puo creare fatture, cercare clienti, generare report e molto altro — il tutto in linguaggio naturale.

Il server MCP richiede un piano Pro o Lifetime e una chiave API. Creane una in Impostazioni > API nella dashboard.

Prerequisiti

1. Abbonamento Pro o Lifetime — il server MCP utilizza l'API pubblica, una funzionalita Pro
2. Una chiave API — creane una in Impostazioni > API (solo lettura va bene per le query; lettura e scrittura per accesso completo)
3. Un client IA compatibile — Claude Desktop, Claude Code, Cursor o qualsiasi strumento compatibile MCP

Configurazione

Claude Desktop

Aggiungi quanto segue al tuo claude_desktop_config.json:

{
  "mcpServers": {
    "lumabill": {
      "type": "streamable-http",
      "url": "https://mcp.lumabill.ch/mcp?key=lmb_la_tua_chiave_qui"
    }
  }
}

Posizione del file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

Aggiungi in .mcp.json nella root del progetto:

{
  "mcpServers": {
    "lumabill": {
      "type": "streamable-http",
      "url": "https://mcp.lumabill.ch/mcp?key=lmb_la_tua_chiave_qui"
    }
  }
}

Cursor

1. Apri Impostazioni > MCP
2. Clicca su Aggiungi server MCP
3. Inserisci:
   • Nome: lumabill
   • Tipo: streamable-http
   • URL: https://mcp.lumabill.ch/mcp?key=lmb_la_tua_chiave_qui

Sostituisci lmb_la_tua_chiave_qui con la tua chiave API reale in tutti gli esempi sopra.

Strumenti disponibili

Una volta collegato, il tuo assistente IA ha accesso a tutti gli endpoint dell'API Lumabill come strumenti:

Fatturazione

• Elencare, creare, modificare ed eliminare fatture
• Creare e gestire offerte/preventivi
• Gestire fatture ricorrenti

Clienti & Fornitori

• Cercare e consultare clienti
• Creare e aggiornare schede clienti
• Gestire contatti fornitori

Spese & Entrate

• Registrare e categorizzare spese
• Monitorare entrate non fatturate
• Consultare dati sulle entrate

Contabilita

• Creare registrazioni contabili
• Visualizzare il piano dei conti
• Gestire gli esercizi fiscali

Banca

• Importare transazioni bancarie (CAMT)
• Riconciliare transazioni

Rapporti

• Generare conti economici
• Generare bilanci
• Creare rapporti IVA

Impostazioni

• Visualizzare profili e informazioni aziendali
• Sfogliare il catalogo prodotti

Esempi di prompt

Una volta collegato il tuo assistente IA, prova prompt come:

• "Crea una fattura per Muster AG per 3 ore di consulenza a CHF 180/ora"
• "Mostrami tutte le fatture non pagate"
• "Qual e stato il mio fatturato il mese scorso?"
• "Genera un report P&L per il Q1 2026"
• "Cerca il cliente Meier GmbH"
• "Crea una spesa di CHF 49.90 per materiale d'ufficio"
• "Elenca tutte le fatture ricorrenti"

Permessi & Limiti di frequenza

• Le chiavi in sola lettura espongono solo strumenti di lettura (elencare, ottenere, rapporti). Le operazioni di scrittura sono nascoste.
• Le chiavi lettura e scrittura espongono tutti gli strumenti.
• I limiti di frequenza sono identici all'API REST: 60 letture/minuto e 20 scritture/minuto per chiave.
• Il server MCP rispetta l'ambito del profilo della tua chiave — se la chiave e limitata a un profilo, l'assistente vede solo i dati di quel profilo.

Risoluzione dei problemi

"Connection refused" o timeout

• Verifica che la tua chiave API sia corretta e inizi con lmb_
• Controlla che l'URL sia esattamente https://mcp.lumabill.ch/mcp?key=lmb_la_tua_chiave_qui (nessuna barra finale)
• Assicurati che il tuo abbonamento sia attivo (Pro o Lifetime)

"Unauthorized" o "Chiave API non valida"

• La chiave potrebbe essere stata revocata — controlla in Impostazioni > API nella dashboard
• Assicurati di aver copiato la chiave completa incluso il prefisso lmb_

Gli strumenti non appaiono

• Riavvia il tuo client IA dopo aver modificato la configurazione
• Per Claude Desktop, esci completamente e riapri l'applicazione
• Per Cursor, ricarica la finestra dopo aver aggiunto il server MCP

Errori "Chiave in sola lettura" sulle operazioni di scrittura

• La tua chiave API e impostata su sola lettura. Crea una nuova chiave lettura e scrittura se devi creare o modificare dati.

Errori di limite di frequenza (429)

• Stai inviando troppe richieste. Attendi un momento e riprova.
• Considera di raggruppare le operazioni o di distribuirle nel tempo.