Come collegare Falco a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Falco, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Falco + Gemini

Falco, contabilità belga e fatturazione elettronica Peppol: documenti di acquisto e di vendita con i loro file, fatture ricevute via Peppol, ricerca dei partecipanti Peppol e clienti, articoli e fatture del modulo di fatturazione di Falco. Quasi tutto in sola lettura; l'impostazione dello stato di pagamento degli acquisti e l'invio delle risposte Peppol alle fatture sono disattivati all'installazione.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

FALCO_APP_SECRET, FALCO_API_KEY

Step 1 — Ottieni le credenziali

Il connettore richiede due chiavi, entrambe obbligatorie: un application secret dell'integratore e una chiave API del cliente Falco.

1. L'integratore crea un'applicazione nel portale sviluppatori di Falco (dev.falco-app.be), richiede gli scope necessari, per esempio documents:purchases:read, documents:sales:read, peppol:inbound:read, peppol:participants:read, customers:read, articles:read e invoices:read, e la rende Public. Il suo Application Secret di produzione (as_live_...) va in FALCO_APP_SECRET.
2. Il cliente Falco, un amministratore dell'organizzazione con piano Expert Essential o Expert Premium, apre API access sotto le sue iniziali nell'applicazione desktop di Falco, sceglie quell'applicazione tramite il suo id (app_...) e genera una API key (sk_live_...) per la sua organizzazione. Va in FALCO_API_KEY.
3. Installa il connettore ed esegui falco_get_organization per verificare entrambe le chiavi. Il connettore chiama l'API di produzione, https://api.falco-app.be/v1; le chiavi sandbox (as_test_, sk_test_) funzionano solo sull'host sandbox e qui vengono rifiutate.

Cosa legge: l'organizzazione a cui appartiene la chiave (nome, partita IVA, identificativo Peppol, indirizzo, IBAN, piano); i documenti di acquisto (fatture e note di credito dei fornitori) con stato di pagamento e Peppol, cronologia degli eventi e file allegati; i documenti di vendita, anche quelli importati come PDF o UBL; i documenti ricevuti via Peppol con mittente, importi, scadenza, riferimento di pagamento e conto bancario; e clienti, articoli e fatture del modulo di fatturazione di Falco, con righe, subtotali IVA e stato Peppol. Scarica anche i file: il file principale, l'XML UBL o un allegato di un documento di acquisto, l'UBL di un documento ricevuto via Peppol e il PDF di una fattura del modulo di fatturazione.

Come lo usa l'AI: per le fatture dei fornitori parte da falco_list_peppol_inbound (cosa è arrivato via Peppol) e falco_list_purchase_documents (tutti i documenti di acquisto con i loro file); per le vendite da falco_list_sale_documents o, per i documenti creati nel modulo di fatturazione, da falco_list_invoices. Per sapere se un'azienda può ricevere fatture elettroniche usa falco_find_peppol_participant con la partita IVA, oppure falco_check_peppol_participant con un id partecipante come 0208:0123456789.

Disattivati all'installazione: falco_set_purchase_payment_status e falco_send_invoice_response. Il primo sostituisce lo stato di pagamento di un documento di acquisto con not_paid, partially_paid o paid, per esempio dopo aver pagato un fornitore. Il secondo invia al mittente di un documento ricevuto una risposta alla fattura via Peppol (acknowledged, in_process, under_query, conditionally_accepted, rejected, accepted o paid); il fornitore la riceve subito e non si può ritirare. Un amministratore li attiva consapevolmente. Anche allora l'AI ti mostra il documento e il nuovo stato o la risposta e aspetta il tuo sì.

Date e importi: i filtri accettano YYYY-MM-DD. Gli importi sono stringhe nella valuta del documento, di solito EUR. Gli elenchi sono paginati con page (da 0) e page_size (da 20 a 200, fatture fino a 100), e l'AI chiede la pagina successiva finché una pagina torna piena.

Limiti: 60 richieste al minuto per application secret. Oltre, Falco risponde 429 e l'AI aspetta e riprova.

Errori comuni: gli errori seguono la RFC 9457 con title, detail e code. 401 significa un application secret o una chiave API sbagliati, oppure una chiave sandbox usata in produzione. 403 significa che alla chiave manca lo scope per quell'area; il cliente concede gli scope quando crea la chiave. 404 nella ricerca di un partecipante significa che l'azienda non è raggiungibile via Peppol.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di Falco.

Tool disponibili

Esempi di prompt

• "Quali fatture dei fornitori ricevute via Peppol questo mese sono ancora da pagare, e quando scadono?"
• "Mostrami i documenti di acquisto degli ultimi 30 giorni con fornitore, importo e stato di pagamento."
• "L'azienda con partita IVA BE0123456789 può ricevere fatture elettroniche via Peppol?"
• "Elenca le fatture del modulo di fatturazione inviate ma non ancora pagate, con gli importi IVA inclusa."
• "Scarica il PDF della fattura 2026-0142 dal modulo di fatturazione."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Meta Muse
• Collegare a Microsoft Copilot