Collegare un agente IA (Claude) via MCP

Collega un agente IA, come Claude, al tuo CRM tramite il server MCP nativo. L'agente legge e crea record (lead, contatti, opportunità) in modo sicuro, usando la tua chiave API.

MCP (Model Context Protocol) è lo standard che permette a un agente IA di dialogare con sistemi esterni. Sellio offre un server MCP nativo: punta l'agente (ad esempio Claude, in esecuzione in Claude Desktop o in qualsiasi client MCP) all'URL del server e potrà interrogare e creare record nel tuo CRM. È ideale per un agente di prospezione che crea automaticamente lead e contatti. Tutto avviene nel contesto del tenant della chiave API e rispetta le validazioni e i permessi (RBAC) del CRM.

Prerequisiti

• Un client MCP (Claude Desktop, o qualsiasi app/agente che parli MCP via HTTP).
• In Sellio, accesso come amministratore per generare la chiave API in Impostazioni → API e sviluppatori.

1) Genera una chiave API

1. Apri Impostazioni → API e sviluppatori (raggiungibile anche dalla scorciatoia nella barra laterale).
2. Crea una nuova chiave API e copia il valore (inizia con sk_ e viene mostrato una sola volta, quindi trattala come una password).
3. La stessa chiave funziona sia per l'API REST sia per MCP.

2) Punta l'agente al server MCP

L'URL del server MCP è https://IL-TUO-CRM/api/mcp e l'autenticazione è la stessa della REST: l'header Authorization: Bearer sk_...

In Claude Desktop (e nei client che usano il bridge mcp-remote), aggiungi quanto segue al file di configurazione dei server MCP:

3) Strumenti a disposizione dell'agente

• list_objects: individua gli oggetti disponibili (lead, contatti, aziende, opportunità e oggetti personalizzati).
• describe_object: individua i campi di un oggetto: apiName, etichetta, tipo, se è obbligatorio, le opzioni accettate da un select e l'oggetto di destinazione di un lookup. Chiamalo prima di creare o aggiornare.
• list_records: elenca e cerca i record di un oggetto (ricerca, filtri sui campi, ordinamento, paginazione).
• get_record: recupera un record tramite id.
• create_record: crea un record (ad esempio un nuovo lead di prospezione).
• update_record: aggiorna i campi di un record esistente.
• delete_record: sposta un record nel cestino (reversibile). Funziona solo se la chiave API ha il delete scope abilitato, che è disattivato per impostazione predefinita.
• bulk_create_records: crea fino a 500 record in un'unica chiamata, con esito positivo o negativo riportato per elemento.
• bulk_update_records: aggiorna fino a 500 record tramite id in un'unica chiamata, con esito positivo o negativo riportato per elemento.
• export_records: restituisce i record di un oggetto come righe tabellari piatte con colonne stabili, con updated_since e created_since per la sincronizzazione incrementale. Pensato per strumenti di BI e automazione.
• list_activities: elenca le attività di un record (la sua timeline) o quelle più recenti dello spazio di lavoro.
• create_activity: registra un'attività da fare, oppure una chiamata, un'e-mail, una riunione o una nota già avvenuta.
• update_activity: completa, riapre, riprogramma, riassegna o registra l'esito di un'attività.
• delete_activity: elimina un'attività. Richiede il delete scope.
• list_attachments: elenca i file allegati a un record.
• get_attachment: restituisce i metadati di un allegato e un link di download firmato che scade dopo 5 minuti.
• create_attachment_upload_url: passo 1 di un caricamento: restituisce un URL firmato a cui inviare i byte del file con PUT (massimo 25 MB).
• register_attachment: passo 2 di un caricamento: registra il file caricato sul record affinché compaia nella timeline.
• delete_attachment: elimina un allegato e il suo file. Irreversibile, quindi richiede il delete scope.
• list_inventory: saldo di magazzino, quantità riservata e disponibile per prodotto, per un singolo prodotto, oppure solo i prodotti sotto la scorta minima.
• list_line_items: righe di prodotto di un'opportunità (quantità, prezzo, sconto, imposta) e il totale ricalcolato.
• add_line_item: aggiunge una riga di prodotto a un'opportunità. I totali e l'importo dell'opportunità vengono ricalcolati con lo stesso motore usato dalla schermata.
• update_line_item: modifica quantità, prezzo, sconto, imposta, durata o descrizione di una riga di prodotto.
• delete_line_item: rimuove una riga di prodotto da un'opportunità.
• send_marketing_email: invia un'e-mail di marketing (a, oggetto, html) tramite il provider configurato, con il piè di pagina di disiscrizione aggiunto automaticamente.

Riferimento completo dell'API REST e di MCP (endpoint, parametri, formato degli errori, rate limit e scoperta dei campi): vedi l'articolo "Riferimento per sviluppatori: API REST e MCP", qui nel Centro Assistenza.

Come testare

1. Collega l'agente e chiedigli qualcosa come "elenca i miei oggetti CRM": dovrebbe chiamare list_objects e restituire l'elenco.
2. Chiedi "crea un lead di nome Ana Souza con email ana@acme.com": l'agente chiama create_record e restituisce l'id del nuovo record.
3. Conferma nel CRM che il record compaia nell'elenco dell'oggetto.

Risoluzione problemi

• 401 Unauthorized: la chiave API manca o è sbagliata. Generane una nuova in Impostazioni → API e sviluppatori e riconfigura l'agente con Authorization: Bearer sk_...
• L'agente non vede il server: verifica l'URL https://IL-TUO-CRM/api/mcp e, in Claude Desktop, che il blocco mcpServers sia nel file di configurazione e che l'app sia stata riavviata.
• Un'azione è stata negata: MCP rispetta i permessi (RBAC) e le validazioni del CRM, e il messaggio di errore spiega il motivo (campo obbligatorio, permesso mancante, limite del piano, ecc.).
• Vedo solo i miei dati: corretto. Ogni chiave API è isolata al tenant proprietario, quindi l'agente non vede mai i dati di un'altra azienda.

Open this article inside the system →