Gestire chiavi API e collegamenti MCP

Con le chiavi API colleghi strumenti esterni e assistenti IA direttamente al tuo workspace Univents. Le chiavi vengono usate per i collegamenti MCP e per le integrazioni esterne, così programmi come Claude Desktop o Cursor possono accedere a eventi, documenti e stato di produzione per tuo conto.

Nel video vedi come collegare Univents tramite MCP a un tuo agente IA come Claude Code e quando conviene invece usare una chiave API.

Riproduci video1:24

I singoli passaggi li trovi qui sotto anche in forma scritta.

Dove trovi le chiavi API

Nel menu principale a sinistra clicca su Integrazioni. Si apre la pagina Tutte le integrazioni con tutte le schede delle integrazioni. Clicca a sinistra sulla categoria Sviluppatori oppure digita «API» nel campo di ricerca in alto, quindi apri la scheda Chiavi API.

La pagina di dettaglio mostra tutte le chiavi esistenti e il pulsante per creare nuove chiavi. Con il link ← Tutte le integrazioni in alto a sinistra puoi tornare in qualsiasi momento alla directory.

Creare una nuova chiave API

1. In alto a destra clicca su Crea nuova chiave.
2. Si apre la finestra Crea nuova chiave API. Nel campo Nome inserisci un nome significativo, ad esempio Claude Desktop o n8n Workflow.
3. Sotto Autorizzazioni trovi due colonne, Segna come letto e Scrittura, con uno scope per ogni area di dati (eventi, richieste, prenotazioni e righe, documenti, contatti e aziende, location). Per impostazione predefinita è selezionato solo mcp:read (accesso IA/MCP, in sola lettura): puoi aggiungere o togliere a piacere altri scope di lettura e scrittura. Almeno uno scope deve restare attivo.
4. Se ti serve l'accesso completo all'intero catalogo di strumenti MCP (lettura e scrittura, con le tue autorizzazioni), attiva separatamente in basso Accesso completo MCP. Univents mostra un avviso e richiede una data di scadenza (massimo 1 anno): questo scope non dura mai a tempo indeterminato.
5. Clicca su Crea.
6. La finestra passa alla vista Chiave API creata. La chiave completa viene mostrata una sola volta. Copiala subito con l'icona di copia accanto.
7. Clicca su Fatto per chiudere la finestra.

Subito dopo la chiave compare nell'elenco con il badge Attivo e un prefisso (ad es. uk_live_abc...).

Autorizzazioni (scope) in sintesi

Ogni scope copre un'area di dati e si può scegliere singolarmente in lettura o in scrittura: la scrittura non include automaticamente la lettura. Se vuoi che uno strumento possa sia leggere sia modificare un'area, seleziona entrambi gli scope.

Con Accesso completo MCP copri molto più di quanto offrano i singoli scope qui sopra: l'intero catalogo di strumenti spazia da eventi, richieste, programmi e personale a documenti, ordini ai fornitori, contatti, contratti e Function Sheet, fino a inventario, attività, report, importazioni, traduzione e serie di appuntamenti.

Configurare la chiave in un client MCP

La chiave generata va inserita nello strumento in uso come token Bearer o chiave API. I passaggi esatti cambiano a seconda del programma:

• Claude Desktop: apri le impostazioni, vai su «MCP Servers» e aggiungi il server Univents con la chiave come parametro apiKey.
• Cursor: inserisci la chiave nell'area di configurazione MCP sotto «Tools & Integrations».
• n8n / Make: usa la chiave in un nodo HTTP come header Authorization nel formato Bearer <chiave>.

Non appena il collegamento è attivo, nell'elenco delle chiavi la voce corrispondente mostra Ultimo utilizzo: con la data dell'ultimo utilizzo.

Revocare o eliminare una chiave

Entrambe le azioni sono disponibili nell'elenco delle chiavi, direttamente su ogni voce:

• Revocata: disattiva subito la chiave. Resta visibile nell'elenco, ma riceve il badge Revocata e non può più essere usata per le richieste. Utile quando vuoi bloccare una chiave compromessa ma continuare a vederne il nome per tenere traccia.
• Elimina (icona del cestino): rimuove completamente la voce della chiave dall'elenco.

Una chiave revocata o eliminata smette di funzionare immediatamente. I client MCP collegati devono essere riconfigurati con una nuova chiave.

Collegare Claude come connector autonomo

Oltre alle chiavi API esiste un secondo modo, più diretto, per collegare Claude a Univents: la scheda Collegamento Claude (categoria IA) sotto Integrazioni. Questa procedura è indipendente dalla chiave API: non viene creata né copiata nessuna chiave, ma consenti l'accesso direttamente in Claude tramite login.

1. In Claude (Claude Desktop o claude.ai) apri le impostazioni dei connector e aggiungi Univents come connector personalizzato.
2. Come indirizzo di collegamento inserisci l'URL mostrato nella pagina di dettaglio della scheda Collegamento Claude sotto Crea un nuovo collegamento.
3. Claude ti reindirizza a Univents. Accedi e autorizza l'accesso al workspace desiderato.
4. Il collegamento compare poi nell'elenco Collegamenti Claude con il nome dell'applicazione e la data di collegamento.

Nella pagina di dettaglio gestisci ogni collegamento singolarmente:

• Cambia workspace sposta un collegamento esistente su un altro dei tuoi workspace, senza doverlo configurare di nuovo in Claude.
• Scollega revoca subito l'accesso: l'applicazione dovrà poi chiedere di nuovo l'autorizzazione in Claude.

Differenze importanti rispetto alla chiave API:

• Il collegamento è legato a te personalmente, non a una chiave visibile a tutti. Solo tu vedi e gestisci i tuoi collegamenti Claude.
• Claude lavora con le tue autorizzazioni nel workspace: non ci sono scope di lettura/scrittura selezionabili separatamente come con la chiave API.
• Questo collegamento è disponibile a partire dal piano Scale e si può provare durante il Periodo di prova. Senza il piano adatto la pagina mostra un avviso con il link per l'upgrade.

Per gli altri client MCP (Cursor, n8n, automazioni proprie) la chiave API resta la strada giusta: funziona ovunque sia possibile inserire un token Bearer.

Quale piano serve

Le chiavi API e i collegamenti MCP fanno parte del piano Scale. Durante il tuo Periodo di prova puoi provarli a fondo: la prova mostra tutte le funzionalità.

Quando il periodo di prova termina, o se passi a un piano senza accesso API, succede automaticamente quanto segue:

• Tutte le chiavi API del workspace vengono disattivate. Nell'elenco compaiono poi con l'indicazione Disattivata per cambio di piano.
• Gli assistenti IA collegati (collegamenti Claude) vengono scollegati e devono chiedere di nuovo l'autorizzazione.
• Le richieste all'interfaccia vengono rifiutate finché l'accesso non è di nuovo disponibile.

Se in seguito attivi Scale, le vecchie chiavi non vengono riattivate: è voluto. Crea semplicemente una nuova chiave e inseriscila nel tuo strumento.

Domande frequenti

Posso rivedere una chiave dopo aver chiuso la finestra? No. Per motivi di sicurezza il valore completo della chiave viene mostrato una sola volta, al momento della creazione. Dopo, nell'elenco resta visibile solo il prefisso. Se hai perso la chiave, creane semplicemente una nuova e revoca la vecchia.

Quante chiavi posso creare? Non c'è un limite fisso. Consiglio: una chiave per ogni strumento collegato, così all'occorrenza puoi revocare singoli collegamenti senza interromperne altri.

Una chiave API può anche creare o modificare dati, o solo leggerli? Sono possibili entrambe le cose. Oltre agli scope di lettura (*:read, mcp:read), per la maggior parte delle aree di dati esiste uno scope di scrittura dedicato (*:write) e c'è Accesso completo MCP (mcp:full) per l'accesso completo in lettura e scrittura all'intero catalogo di strumenti MCP. Solo se in fase di creazione selezioni esclusivamente scope di lettura, la chiave non potrà creare, modificare o eliminare voci.

Quando conviene revocare una chiave invece di eliminarla? Revocare è consigliabile quando vuoi interrompere rapidamente un collegamento attivo e tenere la voce come riferimento. Eliminare ha senso quando la chiave non serve più e vuoi mantenere ordinato l'elenco.

Che differenza c'è tra una chiave API e un collegamento Claude? Una chiave API è un token Bearer con scope di lettura/scrittura scelti a monte, che inserisci in un qualsiasi client MCP. Il collegamento Claude è un login personale direttamente in Claude, senza chiave visibile, e lavora con le tue autorizzazioni nel workspace. I due modi funzionano in modo indipendente: quale usare dipende dal programma che colleghi.