Collegare Claude (e ogni AI agent) al tuo CRM con MCP: guida pratica

In breve

Un server MCP per CRM è un middleware che traduce le API del tuo CRM in strumenti (tool) usabili direttamente da Claude e dagli altri AI agent compatibili con il Model Context Protocol. In pratica permette di chiedere in linguaggio naturale "quali trattative sono ferme da più di 30 giorni?" e ottenere la risposta leggendo i dati reali del CRM, senza aprire nessuna schermata. Per collegarlo servono tre cose: un client MCP (es. Claude Desktop o Claude Code), un server MCP per il tuo CRM e le credenziali API. Sotto trovi il codice reale, la configurazione e, punto spesso ignorato, come farlo in sola lettura per non rischiare scritture indesiderate sui dati di vendita.

Cos'è un server MCP per CRM

Il Model Context Protocol (MCP) è lo standard, adottato da Claude, Claude Code, Cursor, OpenAI Codex e altri, che permette a un modello di linguaggio di usare strumenti esterni in modo strutturato. Un server MCP espone delle funzioni (i tool) che l'AI può richiamare: list_opportunita, search_contatti, update_opportunita e così via.

Applicato al CRM significa che l'AI smette di essere uno strumento separato e inizia a lavorare dentro i tuoi dati: legge la pipeline, riassume una trattativa, prepara un meeting, aggiorna uno stato. Il CRM smette di essere un database in cui inserire dati a mano e diventa qualcosa che risponde alle domande.

È utile distinguerlo da una normale integrazione. Un'integrazione classica collega due sistemi con un flusso predefinito (quando succede X, scrivi Y). Un server MCP invece espone capacità: è l'AI a decidere, di volta in volta, quale tool usare in base alla tua richiesta. Più flessibile, ma proprio per questo va governato (vedi la sezione sicurezza).

Come funziona, in tre passaggi

1. Traduzione. Il server MCP converte le chiamate API del CRM in tool standardizzati. L'AI vede azioni come get_opportunita o create_lead, non endpoint REST.
2. Connessione. Il client MCP (Claude Desktop, Claude Code) avvia il server e ne scopre i tool disponibili.
3. Esecuzione. Tu scrivi una richiesta in linguaggio naturale, l'AI sceglie il tool giusto, il server interroga il CRM e restituisce i dati.

Cosa puoi davvero chiedere al CRM

Per capire il valore concreto, ecco richieste reali e il tool che l'AI usa dietro le quinte:

• "Elenca le opportunità aperte sopra i 10.000 euro con chiusura prevista questo trimestre" → list_opportunita
• "Riassumi la trattativa con l'azienda Rossi e le ultime attività registrate" → get_opportunita + list_attivita_opportunita
• "Quali contatti abbiamo che lavorano in Acme Srl?" → search_contatti
• "Aggiungi una nota all'opportunità 4521: cliente richiamato, ricontattare lunedì" → add_nota_opportunita (scrittura)
• "Quali campi ha il modulo Opportunità?" → describe_modulo
• "Dammi le opportunità perse negli ultimi 90 giorni raggruppate per motivo" → query_raw (VTQL)

Il punto non è la singola query, ma che tutto questo avviene in una conversazione, senza filtri da impostare a mano e senza esportare in Excel.

Tutorial: collegare Claude a VTENext con un server MCP

Usiamo come esempio concreto mcp-vtenext, il server MCP open source (MIT) che abbiamo scritto per VTENext, un CRM self-hosted molto diffuso tra le PMI italiane. La logica è identica per qualsiasi altro CRM: cambia solo il server.

1. Requisiti

• Node.js 18 o superiore
• Un'istanza VTENext raggiungibile
• Una Access Key, che trovi in VTENext sotto Admin → Users → [utente] → Access Key

2. Configurazione

Crea un file .env con le credenziali:

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

3. Collega il server a Claude Code

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

{
  "mcpServers": {
    "vtenext": {
      "type": "stdio",
      "command": "node",
      "args": ["/percorso/assoluto/a/index.js"]
    }
  }
}

Riavvia il client: Claude rileva automaticamente i tool e da quel momento puoi chiedere, ad esempio, "elenca le opportunità aperte sopra i 10.000 euro" e ottenere la risposta dai dati reali.

4. I tool disponibili

Il server espone funzioni su più moduli del CRM:

L'autenticazione segue il protocollo WebService di vtiger (challenge token, hash MD5 della Access Key, login con sessione in cache per 4 minuti): tutto gestito dal server, tu non devi pensarci.

Sola lettura e sicurezza: il punto che quasi nessuno affronta

Far leggere il CRM a un'AI è utile. Farle scrivere dati di vendita in autonomia è un rischio che un'azienda seria non si prende alla leggera. Per questo il server supporta la modalità sola lettura:

{
  "mcpServers": {
    "vtenext-bot": {
      "type": "stdio",
      "command": "node",
      "args": ["/percorso/assoluto/a/index.js"],
      "env": {
        "VTENEXT_URL": "http://tua-istanza-vtenext",
        "VTENEXT_USERNAME": "admin",
        "VTENEXT_ACCESS_KEY": "la_tua_access_key",
        "READ_ONLY": "true"
      }
    }
  }
}

Con READ_ONLY=true ogni tool di scrittura (create_opportunita, update_opportunita, add_nota_opportunita) restituisce un errore invece di toccare i dati. Puoi far girare un'istanza in sola lettura per i bot e gli agenti automatici, e una a pieno accesso solo per gli operatori.

La sola lettura è il primo presidio, non l'unico. Una configurazione sicura prevede anche:

• Utente CRM dedicato con i permessi minimi necessari, non l'admin. Così limiti cosa l'AI può vedere e fare a monte.
• Credenziali fuori dal codice: la Access Key vive in variabili d'ambiente, mai nel repo o nei prompt.
• Accesso di rete ristretto all'istanza CRM (VPN, IP whitelisting) se il server gira su una macchina diversa.
• Tracciabilità: sapere quali chiamate fa l'agente, soprattutto quando le scritture sono abilitate.

È la differenza tra "proviamo l'AI sul CRM" e "abbiamo messo l'AI sul CRM in modo controllato".

I tre modi per avere un server MCP sul tuo CRM

Non c'è una sola strada. Prima di scegliere un server specifico, conviene capire a quale delle tre famiglie appartiene:

1. Server ufficiali del vendor. Forniti dal produttore del CRM (HubSpot, Microsoft Dynamics). Più semplici da attivare, supportati, ma legati a quel CRM.
2. Piattaforme di API unificate. Servizi come Merge o Unified.to espongono un unico server MCP che si collega a decine di CRM diversi. Ottimi se gestisci più CRM o vuoi un solo punto di integrazione, di solito a pagamento e in cloud.
3. Open source e self-hosted. Server che installi e controlli tu (VTENext, Twenty). Massimo controllo sui dati, ideali quando la sovranità del dato conta o il CRM è on-premise.

Quali server MCP per CRM esistono oggi

Ecco una selezione testata, con un giudizio onesto.

Se sei su Salesforce, l'MCP non è un esperimento da smanettoni: è il modo per portare gli agenti AI dentro processi di vendita seri, con governance e sicurezza. È esattamente il tipo di integrazione su cui lavoriamo come Salesforce Certified Partner.

Come scegliere quello giusto

Quattro domande bastano a orientarti:

• Sei già su un CRM con server ufficiale (HubSpot, Dynamics)? Parti da lì, è la strada più corta.
• I tuoi dati sono sensibili o il CRM è on-premise? Vai su open source self-hosted, mantieni tutto in casa.
• Gestisci più CRM (gruppo, clienti diversi)? Una piattaforma di API unificate ti evita N integrazioni.
• Quante competenze tecniche hai a disposizione? Self-hosting richiede chi lo gestisce; i server ufficiali e le piattaforme cloud chiedono meno.

Errori comuni (e come risolverli)

• Claude non vede i tool. Quasi sempre il command/args nel .mcp.json punta a un percorso sbagliato: usa il path assoluto a index.js e riavvia il client.
• Errore di autenticazione. Access Key o username errati, oppure il challenge token è scaduto. Verifica le credenziali e che l'istanza risponda.
• La scrittura viene rifiutata. Se i tool di scrittura restituiscono errore, controlla READ_ONLY: se è true, è il comportamento voluto.
• Timeout o nessuna risposta. L'istanza CRM non è raggiungibile dalla macchina che esegue il server: controlla rete, URL e firewall.

Limiti: quando un server MCP non è la risposta

Per onestà, non è la soluzione a tutto:

• Non è una sincronizzazione continua. Un server MCP lavora on-demand quando l'agente lo interroga, non sostituisce un'integrazione che tiene allineati due sistemi in tempo reale.
• Vale quanto valgono i tuoi dati. Se il CRM è pieno di record sporchi o duplicati, l'AI restituirà risposte sporche.
• Le scritture vanno governate. Lasciare a un agente la modifica autonoma dei dati di vendita richiede regole, non entusiasmo.
• Non è un nuovo CRM. È un layer sopra quello che hai già: se il problema è il CRM in sé, l'MCP non lo risolve.

Domande frequenti

Serve saper programmare? Per un server ufficiale o una piattaforma cloud, poco. Per il self-hosting (es. VTENext) serve qualcuno che sappia installare e configurare Node.js e gestire le credenziali.

Funziona solo con Claude? No. MCP è uno standard aperto: gli stessi server funzionano con ogni client compatibile (Claude Desktop, Claude Code, Cursor e altri).

È sicuro far accedere l'AI al CRM? Sì, a condizione di usare un utente dedicato con permessi minimi, la modalità sola lettura dove serve e credenziali protette in variabili d'ambiente.

Posso usarlo con Salesforce? Sì, tramite integrazioni ufficiali e partner. È uno degli scenari più potenti, e quello su cui lavoriamo come Salesforce Certified Partner.

Che differenza c'è con una normale integrazione API? Un'integrazione esegue un flusso predefinito; un server MCP espone capacità che l'AI usa in autonomia in linguaggio naturale, scegliendo il tool giusto per ogni richiesta.

Da dove partire davvero

Se vuoi capire più a fondo l'implementazione su VTENext, abbiamo una guida dedicata passo-passo: MCP server per VTENext: come collegare Claude al tuo CRM. Se invece stai ancora prendendo le misure con le Skill e l'automazione di Claude, parti da come funzionano le skill di Claude.

Il salto vero, però, non è tecnico: è decidere quale processo di vendita ha senso mettere nelle mani di un agente AI, e con quali limiti. Qui un server MCP in sola lettura è il primo passo intelligente.

Vuoi collegare la tua AI al CRM senza rischiare i dati e senza progetti infiniti? Parliamone: costruiamo integrazioni MCP e CRM su misura per le PMI, dalla sola lettura al flusso completo, con il controllo che serve a un'azienda.