MCP Server per VTENext: Come Connettere Claude al CRM in Linguaggio Naturale

Un MCP server per VTENext è un middleware che espone le API del CRM come strumenti utilizzabili da Claude e altri LLM compatibili con il Model Context Protocol. Il risultato: puoi interrogare e aggiornare VTENext in linguaggio naturale, direttamente dalla chat con il modello AI, senza aprire il browser o scrivere codice.

Ho costruito e pubblicato questo server open source nelle ultime settimane, sviluppandolo in parallelo a un'app gestionale per cantieri edili che usa VTENext come sistema di record. Il pacchetto @castaldosolutions/mcp-vtenext è disponibile su npm e GitHub sotto licenza MIT.

Autore: Gaetano Castaldo, consulente AI e digital transformation, ex Accenture/Capgemini, certificato Salesforce Architect. Aggiornato: marzo 2026.

Cos'è il Model Context Protocol (MCP) e Come Funziona con i CRM

Il Model Context Protocol (MCP) è uno standard aperto rilasciato da Anthropic a novembre 2024 che permette agli LLM di connettersi a sistemi esterni tramite un'interfaccia standardizzata di "strumenti". Invece di copiare dati nella chat, scrivi un server MCP che espone le tue API — e il modello le invoca autonomamente durante la conversazione.

Per un CRM come VTENext, significa che puoi chiedere a Claude di cercare un'opportunità, aggiungere una nota o filtrare i deal per stato. Il modello riconosce l'intenzione, chiama lo strumento giusto e ti restituisce la risposta nel contesto della conversazione — senza cambio di schermata, senza export CSV.

Perché Costruire un MCP Server per VTENext

VTENext è un CRM open source basato sul motore vtiger, molto diffuso nelle PMI italiane per la gestione di opportunità commerciali, contatti e attività. Offre una WebService API completa ma con alcune peculiarità:

• Autenticazione a sfida/risposta (challenge/MD5), non OAuth o API key standard
• Documentazione ufficiale lacunosa su dettagli critici (metodo HTTP, campi obbligatori)
• Nessun SDK ufficiale per Node.js o Python

Ho iniziato a costruire il client di integrazione per un'app gestionale nel settore edile. Quando ho capito che il codice era riutilizzabile e non esisteva nessun connettore MCP pubblico per VTENext, l'ho estratto e pubblicato.

Come Funziona l'Autenticazione VTENext WebService

L'API VTENext usa un protocollo challenge/response in tre passaggi:

1. GET /webservice.php?operation=getchallenge&username=... — il server restituisce un token temporaneo
2. Il client calcola MD5(token + accessKey) — la access key si trova in VTENext sotto Preferenze Utente
3. POST /webservice.php con operation=login e il digest MD5 — il server restituisce il sessionName

Il sessionName va incluso in tutte le richieste successive. Le sessioni vengono cachate per 4 minuti (il token scade dopo 5) per evitare un round-trip ad ogni chiamata.

Nota critica documentata dai test di integrazione: VTENext richiede il login via POST, non GET. La documentazione non lo specifica. Una chiamata GET restituisce INVALID_AUTH_TOKEN silenziosamente — ho scoperto questo comportamento solo testando contro un'istanza Docker reale.

Quali Strumenti Espone il Server MCP per VTENext

Il server espone 10 strumenti organizzati per modulo:

Come Installare e Configurare mcp-vtenext

Requisiti: Node.js 18+, istanza VTENext attiva (self-hosted o Docker).

npm install @castaldosolutions/mcp-vtenext

Aggiungi al file .mcp.json nella root del progetto:

{
  "mcpServers": {
    "vtenext": {
      "type": "stdio",
      "command": "node",
      "args": ["/percorso/assoluto/node_modules/@castaldosolutions/mcp-vtenext/index.js"]
    }
  }
}

Crea un file .env nella stessa cartella del server:

VTENEXT_URL=http://tua-istanza-vtenext
VTENEXT_USERNAME=admin
VTENEXT_ACCESS_KEY=la_tua_access_key

La access key si trova in VTENext sotto Admin → Utenti → [utente] → Access Key. Le credenziali non vengono mai hardcoded nel codice.

Cosa Puoi Chiedere a Claude con VTENext Connesso

Una volta attivo il server MCP, questi sono esempi di richieste reali che Claude gestisce autonomamente:

• "Cerca l'opportunità per il cliente Rossi Costruzioni e dimmi in che fase si trova"
• "Aggiungi una nota all'opportunità 12345: chiamata confermata per giovedì"
• "Quante opportunità sono in fase Negoziazione con chiusura entro fine mese?"
• "Crea una nuova opportunità per il prospect XYZ, importo 15.000 euro, fase Qualificazione"
• "Mostrami i campi disponibili nel modulo Contatti"

Claude riconosce l'intenzione, chiama lo strumento corretto e risponde nel contesto. Nessun copia-incolla, nessun cambio di schermata, nessuna query SQL.

Come Sviluppare con VTENext in Docker

Per sviluppare senza dipendere da un'istanza di produzione, ho usato VTENext dockerizzato in locale. Questo ha permesso test di integrazione reali — non mock — che verificano il comportamento effettivo dell'API.

I test di integrazione hanno rivelato 3 bug che unit test standard non avrebbero trovato:

1. login richiede POST, non GET (errore silenzioso INVALID_AUTH_TOKEN)
2. Per collegare un commento al record padre il campo corretto è related_to, non related_id
3. Il payload di creazione nota deve includere assigned_user_id obbligatoriamente

Avere un'istanza Docker locale eliminabile e riproducibile ha reso questi test stabili, ripetibili e indipendenti dall'ambiente di produzione.

Perché il Protocollo MCP è Rilevante per le PMI con CRM Esistenti

Le PMI che usano VTENext (o qualsiasi altro CRM) hanno spesso il problema opposto all'assenza di dati: i dati ci sono, ma accedere rapidamente è costoso in termini di tempo. Il modello MCP risolve questo in modo architetturalmente pulito:

• Non sostituisce il CRM — aggiunge uno strato di accesso AI sopra l'esistente
• Non richiede migrazione dati — interroga l'API in tempo reale
• Non richiede competenze tecniche all'utente finale — basta fare la domanda in italiano
• È estendibile — aggiungere un nuovo strumento significa aggiungere una funzione al server

Il codice sorgente è su GitHub (Castaldo-Solutions/mcp-vtenext) e il pacchetto è su npm (@castaldosolutions/mcp-vtenext).

Domande Frequenti su MCP e VTENext

Posso usare mcp-vtenext con altri client MCP oltre a Claude? Sì. Il server implementa il protocollo MCP standard, compatibile con qualsiasi client MCP: Claude Desktop, Claude Code, e qualsiasi altro LLM con supporto MCP.

Funziona con VTENext self-hosted? Sì, è il caso d'uso principale. Il server si connette a qualsiasi istanza VTENext raggiungibile via HTTP/HTTPS, sia locale che remota.

È sicuro usare le credenziali VTENext con MCP? Le credenziali vengono lette da variabili d'ambiente o file .env locale, mai trasmesse al modello AI. Il server gira localmente e le sessioni VTENext vengono chiuse correttamente.

Posso aggiungere nuovi moduli VTENext al server? Sì. Ogni strumento è una funzione autonoma nel codice. Puoi aggiungere supporto a qualsiasi modulo VTENext (Fatture, Ticket, Account, ecc.) seguendo lo stesso pattern degli strumenti esistenti.

Qual è la differenza tra query_raw e gli strumenti specifici? query_raw esegue una query VTQL SELECT arbitraria — utile per esplorazione e debug. Gli strumenti specifici come list_opportunita hanno validazione degli input con Zod e sono più sicuri in produzione.

Vuoi Integrare l'AI nel Tuo CRM?

Connettere un LLM al CRM aziendale è uno dei modi più rapidi per ridurre il lavoro manuale senza cambiare i processi esistenti. Se usi VTENext, HubSpot, Salesforce o Odoo e vuoi capire dove ha senso introdurre AI e automazione, contattami per un pre-assessment gratuito.

Richiedi il pre-assessment gratuito