Aggiungere un proprio server MCP
Con un proprio server MCP colleghi AI-School a un'applicazione, una fonte dati o un servizio specializzato. Scegli prima il trasporto più adatto al luogo di utilizzo.
Scegli il trasporto giusto
| Trasporto | Web | Mobile | Desktop | Uso |
|---|---|---|---|---|
| Streamable HTTP | Sì | Sì | Sì | Raccomandato per server ospitati |
| stdio | No | No | Sì | Processi locali e integrazioni desktop |
| SSE | Solo configurazioni esistenti | Solo configurazioni esistenti | Sì | Trasporto obsoleto; per nuovi server scegli Streamable HTTP |
Requisiti per Streamable HTTP
Usa l'endpoint pubblico completo, incluso il percorso MCP, per 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 con un handshake MCP
initializevalido; - avere un set esplicito di strumenti consentiti.
Indirizzi locali, indirizzi di rete privata e endpoint di metadata cloud sono bloccati. Perciò non puoi registrare un server su localhost dalla webapp.
Aggiungere un server
- Apri Preferenze → Tools.
- Scegli Aggiungi tools o Aggiungi server MCP.
- Dai un’occhiata prima ai preset disponibili.
- Scegli Aggiungi un server MCP personalizzato.
- Inserisci nome, endpoint completo e metodo di autenticazione.
- Salva la configurazione e attendi il controllo di connessione.
- Attiva il server per il tuo set di strumenti predefinito.
Un amministratore può registrare un server per tutto l’ambiente tramite Gestione → Impostazioni AI → Tools → MCP.
Autenticazione e secret
AI-School supporta connector-OAuth e secret statici. Token OAuth, refresh token, 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 prima verificata di nuovo. Se il controllo fallisce, una configurazione precedentemente approvata può rimanere attiva finché il problema non è risolto.
Permessi degli strumenti
Consenti solo gli strumenti di cui gli utenti hanno effettivamente bisogno. Un server MCP può offrire azioni di lettura e scrittura, come cancellare file, inviare email o modificare record. AI-School filtra gli strumenti rilevati con la allowlist lato server, ma l’amministratore del server resta responsabile di scope e autorizzazioni adeguate.
Test locale
Un server stdio locale lo testi nell’app desktop. Il renderer non può avviare comandi shell arbitrari: l’installazione avviene tramite un preset approvato o il flusso desktop protetto. Comando, argomenti, chiavi ambiente e accessi richiesti sono mostrati prima dell’installazione.
Risoluzione dei problemi
- Endpoint non raggiungibile: verifica HTTPS, DNS, firewall e il percorso completo
/mcp. - Richiesta di riconnessione: rinnova il permesso OAuth o il secret salvato.
- Appartiene a un altro ambiente: registra di nuovo il connettore nell’ambiente corrente.
- Nessuno strumento visibile: controlla la allowlist degli strumenti, il tuo accesso MCP e se il server è attivo.
- Funziona solo su desktop: probabilmente il server usa stdio o un indirizzo locale.
