# Aggiungi uno strumento o un server MCP

> Installa una ricetta, crea una richiesta HTTP o collega un server MCP remoto.

## Prima di iniziare

Ti servono un workspace business e l’accesso come owner o editor della dashboard. Per strumenti HTTP autenticati, prepara un [profilo credenziali](/it/docs/tools/credentials). Per MCP, procurati l’URL HTTPS del server.

## Installa una ricetta

1. Apri **Strumenti** e scegli **Aggiungi strumenti**.
2. Cerca il servizio e seleziona il suo pacchetto di connettori.
3. Controlla gli strumenti e le chiavi credenziale richieste.
4. Scegli **Aggiungi strumenti** per installare il pacchetto.
5. Crea il primo profilo credenziali quando richiesto.

Una ricetta fornisce richieste già pronte. Associa il profilo ovunque venga eseguito il connettore. Quando un pacchetto installato offre un aggiornamento, controlla le modifiche e scegli **Aggiorna connettore**.

## Crea uno strumento HTTP

1. Scegli **Porta il tuo** nel catalogo e seleziona **Crea strumenti a mano**.
2. Dai un nome al gruppo di integrazione e crea il suo primo strumento.
3. Descrivi l’azione e quando l’AI deve usarla.
4. Imposta il metodo HTTP e l’endpoint HTTPS.
5. Scegli il metodo di autenticazione e una chiave credenziale salvata.
6. Usa **Inserisci** per aggiungere valori forniti dall’agente a URL, header o body della richiesta.
7. Definisci nome, tipo, descrizione e, dove serve, valori ammessi di ogni input.
8. Controlla la richiesta e il livello di approvazione suggerito.
9. Scegli **Crea strumento**.

Il template della richiesta combina gli argomenti forniti dall’agente con le credenziali del profilo associato. Botchi inserisce i valori delle credenziali durante l’esecuzione; il modello non li riceve.

Per partire da una specifica, scegli invece **Importa un file OpenAPI**. Importa un file JSON/YAML OpenAPI 3.x o Swagger 2.0, poi controlla server HTTPS, chiavi credenziale, endpoint, input e rischi di lettura e scrittura. Il parsing avviene localmente nel browser; la creazione del connettore e degli strumenti selezionati è atomica.

> **Attenzione** — Una **Chiamata di test** esegue una richiesta reale. Controlla metodo, identità di destinazione e argomenti prima di provare una scrittura o eliminazione.

## Rendi facoltativo un argomento

1. Deseleziona **Obbligatorio** per l’input, oppure chiedi all’Assistente della dashboard di impostare required a false.
2. Inserisci il placeholder come valore completo dove l’omissione deve rimuovere quel valore.
3. Prova sia argomenti forniti sia omessi.

Per un input omesso chiamato limit, un placeholder completo come `{{args.limit}}` rimuove il parametro query, l’header, la proprietà di un oggetto JSON o l’intero body. Percorsi, valori composti ed elementi di array richiedono comunque un valore. Botchi non inserisce valori predefiniti. I booleani facoltativi nel tester offrono Non inviato, true e false.

Non chiamare un input `executionTargetId`: Botchi lo riserva alla selezione dell’identità e rifiuta nuovi salvataggi. Rinominalo negli strumenti precedenti prima di aggiungere profili credenziali. Uno strumento precedente che lo usa funziona solo finché il connettore non ha un profilo; aggiungerne uno lo rende indisponibile agli agenti finché non rinomini il parametro.

## Collega un server MCP

1. Apri **Aggiungi strumenti** e cerca il provider, oppure incolla l’URL HTTPS del server.
2. Seleziona il server.
3. Segui la configurazione rilevata: nessuna autenticazione, accesso al provider o chiave API.
4. Completa l’accesso al provider nel popup se è richiesto OAuth.
5. Controlla gli strumenti rilevati nella pagina del connettore.

Botchi salva e rinnova i token OAuth. Gli strumenti del server sono utilizzabili da agenti, passaggi strumento dei workflow e Assistente della dashboard.

**Cerca nella directory MCP pubblica** apre separatamente i server non verificati. Controlla il dominio dell’operatore mostrato. La proprietà del dominio dimostra chi gestisce il server, non la qualità o sicurezza degli strumenti. I provider che limitano OAuth ai client AI approvati possono risultare non disponibili.

Gli strumenti MCP partono con la raccomandazione di chiedere approvazione, indipendentemente dai rischi dichiarati dal server. Controlla la [policy degli strumenti dell’agente](/it/docs/agents/tools) prima di consentire l’esecuzione automatica.

## Fornisci la tua app OAuth

Se la registrazione automatica dell’app viene rifiutata:

1. Crea un’app OAuth nella console sviluppatori del provider.
2. Apri **App pre-registrata (avanzato)** nelle impostazioni del server MCP.
3. Copia l’URI di callback di Botchi nell’app del provider.
4. Inserisci client ID, client secret se richiesto e scope.
5. Usa il controllo degli scope obbligatori per selezionare quelli richiesti dal server.
6. Salva il nuovo client ID per avviare l’accesso.

Aggiungi altri scope pubblicati solo quando servono. Se l’accesso fallisce, correggi il problema segnalato di URI di reindirizzamento, scope o approvazione dell’app prima di riprovare.

## Risolvi i problemi di sincronizzazione

1. Apri il connettore MCP segnalato in **Richiede attenzione**.
2. Consulta **Strumenti** per vedere gli strumenti esclusi e i motivi quando il server è sincronizzato parzialmente.
3. Scegli **Risincronizza** dopo aver corretto il server o la connessione.

| Limite del catalogo | Massimo |
| --- | --- |
| Server MCP collegati | 10 per workspace |
| Strumenti caricati per server | Primi 300 |
| Nome dello strumento | 256 byte |
| Schema di input per strumento | 256 KiB |
| Schemi di input totali per server | 1 MiB |

Gli strumenti caricati continuano a funzionare durante una sincronizzazione parziale; un workflow che usa uno strumento escluso fallisce indicando il motivo. I cataloghi abilitati più vecchi di un’ora vengono aggiornati prima dell’uso. Gli aggiornamenti falliti conservano l’ultimo catalogo riuscito e riprovano dopo una pausa.

Un errore di schema incompatibile avvia un aggiornamento e richiede una nuova esecuzione; Botchi non ripete automaticamente l’operazione. Gli strumenti rimossi falliscono esplicitamente. I loro nomi non vengono mai riassegnati e i riferimenti esistenti tornano a funzionare se ricompare lo stesso strumento.

## Correlati

- [Gestisci i profili credenziali](/it/docs/tools/credentials)
- [Assegna strumenti e imposta le approvazioni](/it/docs/agents/tools)
- [Usa strumenti nei workflow](/it/docs/workflows/build)
- [Collega un client AI a Botchi](/it/docs/mcp)