Server MCP

Il server MCP di Frihet implementa il Model Context Protocol affinché gli assistenti IA possano interagire direttamente con il tuo ERP. Creare fatture, registrare spese, consultare clienti o gestire preventivi — tutto dal tuo IDE o terminale, in linguaggio naturale.

Tu:      "Crea una fattura per TechStart SL, 40 ore di consulenza a 75 EUR/ora, scadenza 1 marzo"
Claude:  Fatto. Fattura INV-2026-089 creata. Totale: 3.000,00 EUR + 21% IVA = 3.630,00 EUR.

Cosa aspettarsi (e cosa no)

Il server MCP è un ponte stateless tra il tuo assistente IA e l'API REST di Frihet. Ogni chiamata di strumento si traduce in una richiesta HTTP all'API.

Cosa FA:

CRUD completo su fatture, spese, clienti, prodotti, preventivi e webhook
Ricerca di fatture per nome cliente
Accesso a dati di riferimento (aliquote fiscali, calendario fiscale, categorie)
Workflow guidati (chiusura mensile, preparazione fiscale, gestione dei debitori morosi)

Cosa NON fa:

OCR di documenti (questo lo fa l'assistente IA all'interno dell'app)
Generazione di PDF (usa l'API REST direttamente: GET /v1/invoices/:id/pdf)
Elaborazione dei pagamenti (gli incassi sono gestiti tramite Stripe Connect nell'app)

Requisiti

Account Frihet con accesso all'API (piani a pagamento)
Chiave API generata dal pannello

Ottenere la chiave API

Accedi a app.frihet.io
Vai su Impostazioni > Sviluppatori > API Keys
Clicca su Crea chiave API
Copia la chiave (inizia con fri_) — viene mostrata solo una volta

Installazione

Universale (oltre 30 agenti)

Il modo più rapido per installare il server MCP e la skill di business:

npx skills add Frihet-io/frihet-mcp

Funziona con Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code, e oltre 30 altri agenti.

MCP Registry

Il server è registrato come io.frihet/erp nel MCP Registry ufficiale. I client MCP compatibili con il registro possono scoprirlo e installarlo automaticamente tramite il suo nome canonico.

npx diretto

npx -y @frihet/mcp-server@latest

Non è necessario installare nulla globalmente. npx scarica ed esegue l'ultima versione automaticamente.

Configurazione manuale

Ci sono due modalità di connessione: locale (il server viene eseguito sulla tua macchina tramite npx) e remota (connessione diretta a mcp.frihet.io, senza installare nulla).

Locale (stdio)

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server@latest"],
      "env": {
        "FRIHET_API_KEY": "fri_la_tua_chiave_qui"
      }
    }
  }
}

Remoto (streamable-http)

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_la_tua_chiave_qui"
      }
    }
  }
}

Configurazione per client

La struttura JSON è identica in tutti i client. Cambia solo la posizione del file di configurazione.

Cliente	File di configurazione
Claude Code	`~/.claude/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	`.cursor/mcp.json` o `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	Configurazione di VS Code o `.cline/mcp.json`
Codex CLI	`~/.codex/config.toml` (sezione MCP)

suggerimento

Se usi Claude Code, puoi aggiungere il server con un solo comando:

claude mcp add frihet -- npx -y @frihet/mcp-server@latest

Successivamente configura la variabile FRIHET_API_KEY nel file ~/.claude/mcp.json risultante.

Variabili d'ambiente

Variabile	Richiesta	Valore predefinito
`FRIHET_API_KEY`	Sì	--
`FRIHET_API_URL`	No	`https://api.frihet.io/v1`
`FRIHET_MCP_DEBUG`	No	`0`

FRIHET_API_URL è utile se punti a un ambiente di staging o a un'istanza personalizzata. Deve essere https:// con un hostname sotto frihet.io.
FRIHET_MCP_DEBUG=1 attiva i log di livello debug (utile per diagnosticare problemi).

Flusso OAuth

Il server MCP supporta l'autenticazione OAuth oltre alla chiave API manuale. Quando un client MCP avvia il flusso OAuth:

L'utente si autentica tramite Firebase Auth (email, Google, GitHub o Microsoft)
Il client invia il token di sessione a POST /api/oauth/api-key
Il server effettua il provisioning di una nuova chiave fri_xxx... etichettata "MCP OAuth" con scadenza di 365 giorni
La chiave viene utilizzata automaticamente per le chiamate successive

Ciò consente agli utenti di connettere il server MCP senza copiare manualmente le chiavi.

Strumenti disponibili (44)

Il server espone 52 strumenti organizzati in 7 categorie. Ogni strumento include output strutturato (outputSchema + structuredContent) affinché gli assistenti possano parsare le risposte in modo affidabile, oltre ad annotazioni di sicurezza e contenuto. Bilingue (EN/ES).

Fatture (6 strumenti)

Strumento	Descrizione	Parametri chiave
`list_invoices`	Elenca fatture con paginazione	`limit`, `offset`
`get_invoice`	Ottiene una fattura per ID	`id`
`create_invoice`	Crea una fattura con righe di dettaglio	`clientName`, `items[]` (description, quantity, unitPrice), `status`, `dueDate`, `notes`, `taxRate`
`update_invoice`	Aggiorna campi di una fattura (parziale)	`id`, e qualsiasi campo da modificare
`delete_invoice`	Elimina una fattura permanentemente	`id`
`search_invoices`	Cerca fatture per nome cliente	`clientName`, `limit`, `offset`

Stati possibili della fattura: bozza, inviata, pagata, scaduta, annullata

Spese (5 strumenti)

Strumento	Descrizione	Parametri chiave
`list_expenses`	Elenca spese con paginazione	`limit`, `offset`
`get_expense`	Ottiene una spesa per ID	`id`
`create_expense`	Registra una nuova spesa	`description`, `amount`, `category`, `date`, `vendor`, `taxDeductible`
`update_expense`	Modifica una spesa esistente (parziale)	`id`, e qualsiasi campo da modificare
`delete_expense`	Elimina una spesa permanentemente	`id`

Clienti (5 strumenti)

Strumento	Descrizione	Parametri chiave
`list_clients`	Elenca tutti i clienti	`limit`, `offset`
`get_client`	Ottiene un cliente per ID	`id`
`create_client`	Registra un nuovo cliente	`name`, `email`, `phone`, `taxId`, `address` (street, city, state, postalCode, country)
`update_client`	Aggiorna dati di un cliente (parziale)	`id`, e qualsiasi campo da modificare
`delete_client`	Elimina un cliente permanentemente	`id`

Prodotti (5 strumenti)

Strumento	Descrizione	Parametri chiave
`list_products`	Elenca prodotti e servizi	`limit`, `offset`
`get_product`	Ottiene un prodotto per ID	`id`
`create_product`	Crea un prodotto o servizio	`name`, `unitPrice`, `description`, `taxRate`
`update_product`	Modifica un prodotto esistente (parziale)	`id`, e qualsiasi campo da modificare
`delete_product`	Elimina un prodotto permanentemente	`id`

Preventivi (5 strumenti)

Strumento	Descrizione	Parametri chiave
`list_quotes`	Elenca preventivi	`limit`, `offset`
`get_quote`	Ottiene un preventivo per ID	`id`
`create_quote`	Crea un preventivo per un cliente	`clientName`, `items[]` (description, quantity, unitPrice), `validUntil`, `notes`, `status`
`update_quote`	Modifica un preventivo (parziale)	`id`, e qualsiasi campo da modificare
`delete_quote`	Elimina un preventivo permanentemente	`id`

Stati possibili del preventivo: bozza, inviato, accettato, rifiutato, scaduto

Webhook (5 strumenti)

Strumento	Descrizione	Parametri chiave
`list_webhooks`	Elenca webhook configurati	`limit`, `offset`
`get_webhook`	Ottiene configurazione di un webhook	`id`
`create_webhook`	Registra un endpoint di webhook	`url`, `events[]`, `active`, `secret`
`update_webhook`	Modifica un webhook esistente	`id`, e qualsiasi campo da modificare
`delete_webhook`	Elimina un webhook permanentemente	`id`

Eventi webhook disponibili: invoice.created, invoice.updated, invoice.deleted, invoice.paid, expense.created, expense.updated, expense.deleted, client.created, client.updated, client.deleted, product.created, product.updated, product.deleted, quote.accepted. Consulta Webhook per il formato del payload e la verifica HMAC.

Risorse disponibili (8)

Le risorse MCP sono dati di riferimento che l'assistente può consultare senza effettuare chiamate all'API. Sono statici e sempre accessibili.

Risorsa	URI	Descrizione
Schema API	`frihet://api/schema`	Riepilogo di endpoint, autenticazione, rate limits e codici di errore
Aliquote fiscali	`frihet://tax/rates`	IVA (21/10/4%), IGIC (7/3/0%), IPSI, intracomunitario, IRPF (15%/7%)
Calendario fiscale	`frihet://tax/calendar`	Date di presentazione trimestrale (Modello 303, 130, 420, 390)
Categorie di spesa	`frihet://config/expense-categories`	8 categorie con regole di deducibilità e trattamento fiscale
Stati della fattura	`frihet://config/invoice-statuses`	Flusso di stati (bozza, inviata, pagata, scaduta, annullata) con trigger
Fornitori	`frihet://config/vendors`	Elenco di fornitori registrati con dati fiscali e di contatto
Integrazioni attive	`frihet://config/integrations`	Stato delle integrazioni connesse (Stripe, Shopify, ecc.)
Configurazione del business	`frihet://config/business`	Dati fiscali dell'azienda, zona fiscale, valuta e preferenze

Prompt disponibili (7)

I prompt sono workflow guidati che l'assistente esegue passo dopo passo. Vengono invocati per nome.

Prompt	Descrizione	Parametri
`monthly-close`	Chiusura mensile: rivedi fatture non pagate, categorizza spese, verifica obblighi fiscali, genera riepilogo	`month` (opzionale)
`onboard-client`	Registrazione cliente: determina tipo impositivo in base alla posizione, crea record, genera preventivo di benvenuto	`clientName`, `country`, `region`
`quarterly-tax-prep`	Preparazione fiscale trimestrale: raccoglie fatture, calcola IVA/IGIC, genera anteprima del Modello 303/130	`quarter`, `fiscalZone`
`overdue-followup`	Sollecito morosi: identifica fatture scadute, raggruppa per cliente, redige messaggi di sollecito	—
`expense-batch`	Elaborazione spese in batch: categorizza, applica imposte, verifica deducibilità, crea con conferma	`fiscalZone`
`vendor-analysis`	Analisi fornitori: raggruppa spese per fornitore, calcola totali, identifica tendenze e opportunità di risparmio	`period` (opzionale)
`business-health`	Diagnostica dello stato di salute del business: KPI chiave, confronto con il mese precedente, avvisi e raccomandazioni attuabili	`month` (opzionale)

suggerimento

Puoi invocare un prompt direttamente: "Esegui la chiusura mensile di febbraio" o "Prepara le imposte del Q1".

Esempi di utilizzo

Queste sono richieste reali in linguaggio naturale che l'assistente traduce in chiamate agli strumenti MCP.

Creare una fattura

"Crea una fattura per Acme SL con 10 ore di consulenza a 95 EUR/ora, scadenza 15 marzo"

L'assistente chiama create_invoice con clientName: "Acme SL", una riga di dettaglio (10 x 95) e dueDate: "2026-03-15". Calcola il totale automaticamente.

Registrare una spesa

"Registra una spesa di 59.99 EUR in Adobe Creative Cloud, categoria software, deducibile"

Chiama create_expense con description, amount: 59.99, category: "software" e taxDeductible: true.

Cercare fatture di un cliente

"Cerca tutte le fatture di TechStart SL"

Chiama search_invoices con clientName: "TechStart SL" e restituisce le corrispondenze con i loro totali e stati.

Consultare i morosi

"Mostrami tutte le fatture non pagate"

Chiama list_invoices e filtra per status: "inviata" o "scaduta", mostrando quelle scadute ordinate per importo.

Registrare un cliente

"Nuovo cliente: Design Studio SL, NIF B87654321, email hola@designstudio.es, Madrid 28001"

Chiama create_client con nome, NIF, email e indirizzo.

Configurare l'automazione

"Crea un webhook per notificare a https://mi-app.com/hook quando viene pagata una fattura"

Chiama create_webhook con url ed events: ["invoice.paid"].

Aggiornare un prodotto

"Aumenta il prezzo dell'ora di consulenza a 85 EUR"

Chiama update_product con l'id del prodotto e unitPrice: 85. Viene modificato solo il campo indicato.

Osservabilità

Il server MCP v1.5.1 include logging strutturato e metriche degli strumenti.

Logging strutturato

Tutti i log vengono emessi come JSON su stderr (MCP usa stdout per i messaggi del protocollo). Ogni voce include:

level: debug, info, warn, error
service: sempre frihet-mcp
timestamp: ISO 8601
tool: nome dello strumento (quando applicabile)
operation: tipo di operazione (tool_call, api_call, api_retry, startup, shutdown_metrics)
durationMs: tempo di esecuzione in millisecondi
error: dettagli dell'errore (message, code, statusCode)

Attiva i log di debug con FRIHET_MCP_DEBUG=1.

Metriche degli strumenti

Il server registra in memoria le chiamate a ogni strumento: numero di invocazioni, errori e durata media. Alla chiusura del server (SIGINT/SIGTERM), viene emesso un riepilogo:

{
  "level": "info",
  "message": "Shutdown after 3600s — 42 calls, 1 errors",
  "operation": "shutdown_metrics",
  "metadata": {
    "tools": {
      "list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
      "create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
    },
    "uptime": 3600
  }
}

Retry automatico per rate-limit

Quando l'API risponde con 429, il server riprova automaticamente con backoff esponenziale (fino a 3 tentativi). I tentativi vengono registrati nel log:

{
  "level": "warn",
  "message": "Rate limited, retrying GET /invoices (attempt 2, delay 2000ms)",
  "operation": "api_retry"
}

Non è necessario gestire manualmente il rate limiting — il server lo fa per te.

Trasporto

Il server MCP di Frihet supporta due modalità di trasporto. Entrambi espongono gli stessi 52 strumenti, 11 risorse e 10 prompt.

Locale (stdio)

Il server viene eseguito come processo locale sulla tua macchina. La comunicazione tra il client MCP e il server utilizza l'input/output standard (stdin/stdout).

Richiede: Node.js installato (viene scaricato automaticamente tramite npx)
Vantaggio: Minore latenza, funziona senza connessione a internet (tranne per le chiamate all'API)
Caso d'uso: Sviluppo quotidiano, uso intensivo, ambienti aziendali con restrizioni di rete

Remoto (streamable-http)

Il server viene eseguito su Cloudflare Workers. Il tuo client MCP si connette direttamente a https://mcp.frihet.io/mcp tramite HTTP.

Richiede: Solo connessione a internet
Vantaggio: Nessuna installazione locale, nessuna dipendenza, funziona su qualsiasi dispositivo
Caso d'uso: Configurazione rapida, team che preferiscono non installare pacchetti, client che supportano solo il trasporto HTTP

informazioni

Se il tuo client MCP non supporta streamable-http (alcuni client più vecchi supportano solo stdio), usa la modalità locale.

Gestione degli errori

Rate limiting

L'API consente 100 richieste al minuto per chiave. Se il limite viene superato, il server restituisce un errore 429 con il tempo di attesa in retryAfter.

Il server MCP gestisce automaticamente il rate limiting con backoff esponenziale: riprova la richiesta dopo aver atteso il tempo indicato, senza intervento dell'utente. Massimo 3 tentativi.

Errori di autenticazione

Codice	Causa	Soluzione
`401`	Chiave API non valida, scaduta o non fornita	Verifica che la chiave nella tua configurazione inizi con `fri_` e non sia scaduta
`403`	La chiave non ha i permessi per questa risorsa	Genera una nuova chiave con i permessi necessari

Altri errori

Codice	Descrizione
`400`	Parametri errati o campi obbligatori mancanti
`404`	La risorsa richiesta non esiste
`408`	Timeout della richiesta (30 secondi)
`413`	Il corpo della richiesta supera 1 MB
`422`	Dati validi ma non elaborabili (es: profilo fiscale non configurato)
`429`	Limite di richieste superato (viene riprovato automaticamente)
`500`	Errore interno del server

Tutti gli errori restituiscono un messaggio descrittivo bilingue (EN/ES) affinché l'assistente possa comunicare il problema all'utente in modo chiaro.

Limiti

Concetto	Valore
Richieste al minuto	100 per chiave API
Risultati per pagina	100 massimo (50 predefinito)
Corpo della richiesta	1 MB massimo
Payload di webhook	100 KB massimo
Webhook per account	20 massimo
Timeout della richiesta	30 secondi
Tentativi per rate limit	3 massimo

Differenza con l'API REST

	Server MCP	API REST
Destinato a	Assistenti IA (Claude, Cursor, Windsurf)	Applicazioni, script, integrazioni
Comunicazione	Linguaggio naturale tramite il client MCP	HTTP/JSON diretto
Autenticazione	Variabile d'ambiente nella config del client (o OAuth)	Intestazione `X-API-Key` o `Authorization: Bearer`
Formato	Testo formattato + output strutturato per l'assistente	JSON grezzo
Rate limiting	Gestito automaticamente (backoff esponenziale, 3 tentativi)	Manuale (il consumatore deve implementare i tentativi)
Osservabilità	Logging strutturato + metriche per strumento	Log di richiesta tramite `X-Request-Id`
Caso d'uso	Parlare con il tuo ERP dall'IDE	Costruire integrazioni programmatiche

Internamente, il server MCP traduce ogni chiamata di strumento in una richiesta all'API REST. Non duplica la logica — è un ponte stateless.

Sviluppo

Per contribuire o eseguire il server in modalità sviluppo:

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Eseguire localmente:

FRIHET_API_KEY=fri_la_tua_chiave node dist/index.js

Eseguire con log di debug:

FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_la_tua_chiave node dist/index.js

Testare con l'MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Risorse correlate

API REST — Riferimento completo di endpoint, autenticazione e codici di errore
Webhook — Eventi disponibili, verifica HMAC-SHA256 e politica di retry
Skill per Claude Code — Livello di intelligenza di business sul server MCP
Codice sorgente (GitHub) — Repository del server MCP
Pacchetto npm — @frihet/mcp-server@1.5.1
MCP Registry — io.frihet/erp
Endpoint remoto — Server MCP ospitato su Cloudflare Workers
Specifiche MCP — Documentazione del protocollo

Precedente: Webhook | Successivo: Skill per Claude Code

Cosa aspettarsi (e cosa no)​

Requisiti​

Ottenere la chiave API​

Installazione​

Universale (oltre 30 agenti)​

MCP Registry​

npx diretto​

Configurazione manuale​

Locale (stdio)​

Remoto (streamable-http)​

Configurazione per client​

Variabili d'ambiente​

Flusso OAuth​

Strumenti disponibili (44)​

Fatture (6 strumenti)​

Spese (5 strumenti)​

Clienti (5 strumenti)​

Prodotti (5 strumenti)​

Preventivi (5 strumenti)​

Webhook (5 strumenti)​

Risorse disponibili (8)​

Prompt disponibili (7)​

Esempi di utilizzo​

Creare una fattura​

Registrare una spesa​

Cercare fatture di un cliente​

Consultare i morosi​

Registrare un cliente​

Configurare l'automazione​

Aggiornare un prodotto​

Osservabilità​

Logging strutturato​

Metriche degli strumenti​

Retry automatico per rate-limit​

Trasporto​

Locale (stdio)​

Remoto (streamable-http)​

Gestione degli errori​

Rate limiting​

Errori di autenticazione​

Altri errori​

Limiti​

Differenza con l'API REST​

Sviluppo​

Risorse correlate​

Cosa aspettarsi (e cosa no)

Requisiti

Ottenere la chiave API

Installazione

Universale (oltre 30 agenti)

MCP Registry

npx diretto

Configurazione manuale

Locale (stdio)

Remoto (streamable-http)

Configurazione per client

Variabili d'ambiente

Flusso OAuth

Strumenti disponibili (44)

Fatture (6 strumenti)

Spese (5 strumenti)

Clienti (5 strumenti)

Prodotti (5 strumenti)

Preventivi (5 strumenti)

Webhook (5 strumenti)

Risorse disponibili (8)

Prompt disponibili (7)

Esempi di utilizzo

Creare una fattura

Registrare una spesa

Cercare fatture di un cliente

Consultare i morosi

Registrare un cliente

Configurare l'automazione

Aggiornare un prodotto

Osservabilità

Logging strutturato

Metriche degli strumenti

Retry automatico per rate-limit

Trasporto

Locale (stdio)

Remoto (streamable-http)

Gestione degli errori

Rate limiting

Errori di autenticazione

Altri errori

Limiti

Differenza con l'API REST

Sviluppo

Risorse correlate