Integrazioni personalizzate e MCP
Collegare un sistema che non è nel catalogo: le tre vie disponibili e quando usarle.
Il catalogo copre gli strumenti diffusi. Non copre il gestionale scritto in casa, il servizio interno, l’API di un fornitore che usate solo voi, l’agente che un altro team ha costruito su un’altra piattaforma. Per quelli l’integrazione la definisci tu.
Si parte da Integrazioni → Aggiungi integrazione, che apre un menu con tre voci: Da zero, Connetti MCP remoto e A2A. Il pulsante lo vede solo chi ha il permesso Creare integrazioni, che di norma hanno Editor e Admin.
Le integrazioni create stanno nella scheda Create da me, che mostra tutte quelle dell’area di lavoro. Da lì in poi si usano in chat richiamandole con @, e nei workflow come blocchi della categoria Integrazioni. Gli agenti remoti diventano invece agenti a tutti gli effetti.
Le tre vie
Il criterio di scelta è breve:
- Il sistema espone già un server MCP, vostro o del fornitore? Usa MCP: non descrivi niente a mano e gli strumenti restano allineati al server.
- Hai un’API HTTP e ti servono poche operazioni precise (crea ticket, cerca cliente, aggiorna stato)? Costruiscila da zero.
- Vuoi delegare un intero compito a un agente esterno, che ragiona e risponde da solo? Collegalo come A2A. La differenza con MCP è questa: MCP ti dà singoli strumenti che usa l’AI di Userbot, A2A ti dà un agente con il suo modello e i suoi strumenti.
Nella finestra di creazione la riga Tipo ti lascia cambiare idea anche dopo aver scelto dal menu.
Costruire da zero
Dopo aver dato nome e descrizione all’integrazione, la configurazione ha due sezioni.
Autenticazione. Tre modalità: Nessuna, API Key (indichi il nome
dell’header, per esempio X-API-Key, e il valore) e Bearer Token. Le
credenziali si scrivono una volta e non vengono più rimostrate: quando ci torni
vedi dei puntini, e lasciando il campo vuoto resta quella salvata.
Azioni. Ogni azione è una chiamata HTTP, e si descrive con questi campi:
I segnaposto disponibili sono due: {{args.chiave}} per i valori che l’AI passa
al momento della chiamata, {{auth.chiave}} per le credenziali salvate. Un
esempio completo:
Il campo che determina se l’integrazione funzionerà è la descrizione, non l’URL: è l’unica cosa che l’AI legge per decidere se quell’azione è quella giusta. Scrivila come diresti a un collega nuovo: «apre un ticket di assistenza; usala quando il cliente segnala un guasto e non c’è già un ticket aperto». Una descrizione come «chiamata tickets» non le basta a scegliere bene.
Un’azione HTTP costruita a mano non ha un test da superare: appena la salvi diventa uno strumento a disposizione dell’AI, indirizzo sbagliato compreso. Prima di farla usare ad altri, richiamala tu in una chat con @ e falla eseguire almeno una volta guardando cosa succede sul sistema di destinazione.
Collegare un server MCP
MCP è il protocollo con cui un sistema espone i propri strumenti a un’AI in modo standard. Se il vostro l’ha già, non c’è niente da descrivere.
Il server deve essere remoto, raggiungibile dai server di Userbot, e parlare il trasporto Streamable HTTP. Un server che gira sul portatile di qualcuno, o dentro la rete aziendale senza un indirizzo raggiungibile, va esposto prima.
Inserisci l'indirizzo
Nel campo URL del server metti l’indirizzo del server MCP che ti ha dato chi lo gestisce. Se servono, aggiungi gli Header, coppie nome/valore usate di solito per l’autenticazione: i valori salvati non vengono rimostrati.
Gli strumenti che l’AI potrà usare sono esattamente quelli trovati dalla verifica, e l’elenco viene memorizzato in quel momento. Se sul server ne aggiungete o ne cambiate, apri l’integrazione, Modifica, e premi Connetti server perché Userbot li veda.
Collegare un agente remoto (A2A)
Agent2Agent è il protocollo con cui un agente si presenta e riceve compiti da un altro. L’agente remoto pubblica una Agent Card, una scheda che dice chi è e cosa sa fare. Oltre al permesso Creare integrazioni serve poter creare agenti.
Inserisci l'indirizzo
In URL agente o Agent Card metti l’indirizzo dell’agente oppure quello
diretto della sua scheda, di solito /.well-known/agent-card.json sul suo
dominio. Se manca https:// viene aggiunto da solo. Aggiungi gli Header
se l’agente richiede un’autenticazione.
Nella pagina Agenti compare un nuovo agente, segnato come Agente remoto (A2A). Si usa in chat come gli altri, e si può scegliere come sotto-agente di un agente multiplo: il turno viene passato al server remoto, che risponde con il suo modello e i suoi strumenti. Da Userbot puoi cambiare nome, descrizione, icona e condivisione; il comportamento lo decide il server remoto.
L’agente non si elimina dalla pagina Agenti: sparisce quando elimini l’integrazione.
Prima di metterla in mano a tutti
Un’integrazione personalizzata è disponibile a tutta l’area di lavoro: chi la crea decide, di fatto, cosa l’AI potrà fare su quel sistema.
- Provala tu, prima. Un errore su un’azione usata da tutti lo scoprono i colleghi, e su un sistema che scrive lo scoprono i vostri clienti.
- Usa credenziali dedicate a Userbot, con i permessi minimi necessari, non quelle di un amministratore.
- Esponi solo le operazioni che servono davvero. Un endpoint di cancellazione aggiunto «per completezza» prima o poi verrà chiamato.
- Le azioni delle integrazioni personalizzate non hanno l’interruttore Chiedi conferma: se un’operazione non deve partire senza un controllo umano, non esporla.
L’eliminazione di un’integrazione personalizzata è definitiva e non si annulla. Le azioni collegate smettono di funzionare in chat e nei workflow che le usano, e un agente remoto A2A sparisce insieme all’integrazione.