> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Integrazioni personalizzate e MCP

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.

![Il menu del pulsante Aggiungi integrazione con le tre voci Da zero, Connetti MCP remoto e A2A, ciascuna con una riga di spiegazione](/_fern-img/413606e99038b311dad9a7127d4a506665782aa7c99e50747ce5ddfccc103b00.webp)

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.

![La finestra Aggiungi integrazione: in alto la riga Tipo con le tre schede Costruisci integrazione da zero, Connetti MCP remoto e Connetti agente remoto (A2A), qui sulla prima; sotto il nome, la descrizione e il pulsante Crea](/_fern-img/c81a2d04d7610766f921694eb4eb273e477d93dfb55173eda9f3185790c26e5e.webp)

## Le tre vie

#### Costruisci integrazione da zero

Definisci una per una le chiamate HTTP che l'AI potrà fare, con o senza
autenticazione. Per API vostre o di fornitori.

#### Connetti MCP remoto

Colleghi un server Model Context Protocol già esistente e Userbot ne scopre
da solo gli strumenti.

#### Connetti agente remoto (A2A)

Colleghi un agente che vive altrove e parla il protocollo Agent2Agent:
diventa un agente di Userbot.

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:

| Campo                 | Cosa ci scrivi                                                  |
| --------------------- | --------------------------------------------------------------- |
| **Nome azione**       | Un identificativo breve e parlante, per esempio `crea_ticket`   |
| **Metodo**            | GET, POST, PUT, PATCH, DELETE                                   |
| **Descrizione**       | Quando l'AI dovrebbe usare questa azione                        |
| **URL**               | L'indirizzo da chiamare, con i valori variabili come segnaposto |
| **Header** e **Body** | JSON, con gli stessi segnaposto. Il body non compare sulle GET  |

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:

```
POST  https://api.interno.it/tickets
Body  {"titolo": "{{args.titolo}}", "priorita": "{{args.priorita}}"}
```

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.

> **Warning**
>
> 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.

![La finestra con il tipo Connetti MCP remoto: il campo URL del server compilato, Aggiungi header sotto e il pulsante Verifica connessione evidenziato](/_fern-img/95c441a30773f3a16f42ef6075a85ebf0dfd2362dd4f1a6c3cec44e1f8dedb04.webp)

#### Verifica la connessione

**Verifica connessione** interroga il server e apre l'**Anteprima server**:
quanti strumenti ha scoperto e, per ognuno, descrizione e parametri. Se
qualcosa non va, sotto il campo compare il messaggio di errore del server.

![L'anteprima dopo una verifica riuscita: il nome e la versione del server e gli strumenti scoperti, ciascuno con la sua descrizione](/_fern-img/22c65f948af6aaba50ca21340035b3010ab546871fb558b703da1ed8d68693b7.webp)

#### Dai un nome e crea

In **Nome e descrizione** scegli un'**Icona** (un'emoji, oppure **Carica
immagine**, JPG, PNG, WebP o GIF fino a 2 MB) e, se vuoi, **Nome
(opzionale)** e **Descrizione (opzionale)**: lasciati vuoti, si prendono dal
server. Poi **Crea**, che compare solo dopo una verifica riuscita.

![Dopo la verifica, a sinistra Nome e descrizione con l'icona e i campi facoltativi, che riprendono il nome del server, e in basso a destra Crea evidenziato](/_fern-img/7bc3672293a6de76833fe629b16c2d3bcc7b1c2d2259ffd18055385c01f22a37.webp)

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.

![La finestra con il tipo Connetti agente remoto (A2A): il campo URL agente o Agent Card compilato, Aggiungi header e il pulsante Verifica connessione evidenziato](/_fern-img/f70141919662ef46ed6b3bc8fe60d91c902e09630f8fea35bfc2fd34afc8877e.webp)

#### Verifica la connessione

**Verifica connessione** legge la scheda e apre l'**Anteprima agente**: le
skill che dichiara, con descrizione ed esempi, la versione, i link a
documentazione, informativa privacy e termini di servizio. **Visualizza
JSON** mostra la scheda completa.

![L'anteprima dell'agente remoto dopo la verifica: nome, versione e descrizione letti dalla sua scheda e le skill dichiarate, con le loro etichette](/_fern-img/5ad4347988c27aa577c64b67b73694f0b6995a2c407a2973782800dd7301d1f9.webp)

#### Dai un nome e crea

**Nome (opzionale)** e **Descrizione (opzionale)** cambiano come l'agente
appare in Userbot; se li lasci vuoti si usano quelli della scheda. Poi
**Crea**.

![Dopo la verifica, Nome e Descrizione facoltativi già proposti dalla scheda dell'agente e, in basso a destra, Crea evidenziato](/_fern-img/02d47d030814a134c6fc597aa24a01dab39621ab7ef3e290d4ffff48fba7895c.webp)

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.

> **Warning**
>
> 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.