Aggiungere un server MCP personalizzato
Con un server MCP personalizzato colleghi AI-School a una tua applicazione, fonte dati o servizio specializzato. Scegli prima quale trasporto si adatta al luogo d’uso.
Scegli il trasporto giusto
| Trasporto | Web | Mobile | Desktop | Uso |
|---|---|---|---|---|
| Streamable HTTP | Sì | Sì | Sì | Consigliato per server ospitati |
| stdio | No | No | Sì | Processi locali e integrazioni desktop |
| SSE | Solo configurazioni esistenti | Solo configurazioni esistenti | Sì | Trasporto obsoleto; per i nuovi server scegli Streamable HTTP |
Requisiti per Streamable HTTP
Usa l’endpoint pubblico completo, incluso il percorso MCP, ad esempio:
https://mcp.example.nl/mcp
L’endpoint deve:
- usare HTTPS;
- funzionare senza nome utente o password nell’URL;
- non richiedere redirect;
- essere raggiungibile tramite DNS pubblico;
- rispondere a un handshake MCP
initializevalido; - avere un set esplicito di tool consentiti.
Indirizzi locali, indirizzi di rete privati ed endpoint di metadati cloud vengono bloccati. Per questo motivo non puoi registrare un server su localhost dall’app web.
Aggiungere un server
- Apri Preferenze → Strumenti.
- Scegli Aggiungi strumenti o Aggiungi server MCP. Questo pulsante è visibile solo se hai accesso MCP.
- Consulta prima i preset disponibili.
- Scegli Aggiungi un server MCP personalizzato.
- Inserisci nome, endpoint completo e metodo di autenticazione.
- Salva la configurazione e attendi il controllo della connessione.
- Attiva il server per il tuo set di strumenti predefinito.
Un amministratore può anche registrare un server per l’intero ambiente tramite Amministrazione → Impostazioni AI → Strumenti → MCP.
Autenticazione e secret
AI-School supporta OAuth del connettore e secret statici. Token OAuth, token di refresh, chiavi API e password sono memorizzati solo sul server. Una chat riceve solo il connectorId registrato, mai la configurazione segreta.
Se URL o autenticazione cambiano, la nuova configurazione viene verificata di nuovo prima. Se questo controllo fallisce, una configurazione già approvata può rimanere attiva finché il problema non è risolto.
Permessi dei tool
Concedi solo i tool di cui gli utenti hanno realmente bisogno. Un server MCP può offrire azioni di lettura e scrittura, come eliminare file, inviare email o modificare record. AI-School filtra i tool rilevati rispetto alla allowlist lato server, ma il gestore del server resta responsabile di scope e autorizzazione adeguati.
Test locale
Un server stdio locale si testa nell’app desktop. Il renderer non può avviare comandi shell arbitrari: l’installazione avviene tramite un preset approvato o il flusso desktop sicuro. Comando, argomenti, chiavi di ambiente e accesso richiesto vengono mostrati prima dell’installazione.
Risoluzione dei problemi
- Endpoint non raggiungibile: controlla HTTPS, DNS, firewall e il percorso completo
/mcp. - Riconnessione richiesta: rinnova il consenso OAuth o il secret salvato.
- Appartiene a un altro ambiente: registra di nuovo il connettore nell’ambiente corrente.
- Nessun tool visibile: controlla la allowlist dei tool, il tuo accesso MCP e che il server sia attivo.
- Funziona solo su desktop: probabilmente il server usa stdio o un indirizzo locale.
Risorse per sviluppatori
Vedi anche
Durante la modifica viene recuperata la configurazione del server registrato. La chiave salvata resta nascosta: lascia vuoto il campo chiave per mantenerla. Se URL o metodo di autenticazione sono diversi, è necessario riconnettersi. Un errore in un singolo tool MCP non significa che tutti i tool di quel server siano irraggiungibili.