Collegare il proprio server MCP a Intric

Intric supporta il Model Context Protocol (MCP), uno standard aperto che consente agli assistenti IA di usare strumenti e fonti di dati esterni. Collegando il proprio server MCP, puoi estendere gli assistenti Intric con strumenti, risorse e prompt personalizzati per i tuoi flussi di lavoro.

Prerequisiti

Prima di collegare un server MCP, verifica quanto segue:

• Il modulo MCP è abilitato per il tuo tenant. Contatta l’amministratore di sistema se non è disponibile.
• Hai i permessi di amministratore nel tenant Intric. Solo gli amministratori possono creare e configurare i server MCP.
• Il server MCP è raggiungibile via HTTPS a un URL pubblico. Gli URL privati o non HTTPS sono bloccati per impostazione predefinita per motivi di sicurezza.
• Sai quale metodo di autenticazione richiede il server MCP: nessuno, chiave API o OAuth 2.0.

Passaggio 1: Creare il record del server MCP

Vai alla sezione Server MCP in Intric.

Clicca su Crea e assegna un nome al server (ad es. «Strumenti CRM interni» o «API di ricerca documenti»).

Il record del server viene creato. Ora puoi configurarlo con URL e autenticazione.

Passaggio 2: Configurare URL del server e autenticazione

Modifica il server appena creato e fornisci:

• URL — L’endpoint HTTPS del server MCP (ad es. https://mcp.tuaazienda.com/mcp).

• Tipo di autenticazione — Scegli uno tra:

  • Nessuna — Nessuna autenticazione richiesta. Adatto a server su reti interne attendibili (se gli URL privati sono abilitati dall’amministratore di sistema).
  • Chiave API — Fornisci una chiave API segreta che Intric invierà come bearer token quando chiama il server. La chiave è crittografata a riposo.
  • OAuth 2.0 — Per server che richiedono autenticazione a livello utente tramite OAuth. Vedi la sezione OAuth sotto per i dettagli.

• Descrizione (facoltativa) — Una descrizione leggibile di ciò che offre il server. Può essere compilata anche automaticamente dai metadati del server.

Quando salvi l’URL, Intric rileva automaticamente le capacità del server — strumenti, risorse, modelli di risorse e prompt disponibili. Puoi anche avviare manualmente questa operazione in qualsiasi momento con l’azione Aggiorna capacità.

Passaggio 3: Abilitare il server MCP come strumento

Una volta collegato il server e rilevate le capacità, devi abilitarlo come strumento per il tenant:

1. Vai alla sezione Strumenti.
2. Trova il server MCP (elencato per nome).
3. Abilitalo per il tenant.

Passaggio 4: Associare lo strumento a un assistente

1. Apri o crea un assistente (in uno Space o come assistente personale).
2. Nella configurazione strumenti dell’assistente, aggiungi lo strumento del server MCP.
3. L’assistente ha ora accesso a tutti gli strumenti, risorse e prompt esposti dal server MCP.

Quando gli utenti interagiscono con l’assistente in una conversazione, può chiamare gli strumenti del server MCP secondo necessità. Le chiamate agli strumenti passano attraverso Intric verso il server, con l’autenticazione configurata applicata automaticamente.

Connessione con OAuth 2.0

Se il server MCP usa OAuth 2.0 per l’autenticazione, Intric supporta l’intero flusso authorization code con PKCE. Ogni utente si autentica individualmente presso il servizio esterno.

Come funziona:

Imposta il tipo di autenticazione su OAuth 2.0 nel record del server MCP.

Rilevamento automatico — Quando possibile, Intric rileva automaticamente gli endpoint OAuth (URL di autorizzazione, URL token, scope supportati) dai metadati del server MCP. Se il server dichiara supporto per i Client ID Metadata Documents (CIMD), Intric si configura come client pubblico automaticamente.

Configurazione manuale — Se il rilevamento automatico non è disponibile, devi fornire:

• OAuth 2.0 Client ID
• OAuth 2.0 Client Secret (se richiesto)
• URL di autorizzazione
• URL token
• URL di revoca (facoltativo)
• Scope (facoltativi)

Autenticazione utente — Ogni utente che vuole usare il server MCP deve completare il flusso OAuth individualmente. Verrà reindirizzato alla pagina di accesso del servizio esterno, concederà l’accesso e tornerà a Intric. L’indicatore di stato sul record del server mostra se l’utente corrente è connesso.

Gestione dei token — Intric gestisce la cache dei token di accesso e il rinnovo automatico tramite refresh token. Gli utenti possono disconnettersi da un server OAuth in qualsiasi momento, revocando i token memorizzati.

Validare una connessione

Dopo aver configurato un server, usa l’azione Valida per verificare se Intric può raggiungerlo e autenticarsi correttamente. Possibili esiti:

Considerazioni sulla sicurezza

• Restrizioni URL — Per impostazione predefinita, Intric consente solo URL HTTPS che risolvono in indirizzi IP pubblicamente instradabili. Ciò previene attacchi SSRF (server-side request forgery). Gli URL privati/interni sono bloccati salvo autorizzazione esplicita dell’amministratore di sistema.

• Segreti crittografati — Le chiavi API e i client secret OAuth sono crittografati a riposo e non sono mai esposti nelle risposte API. L’API indica solo se è impostata una chiave API, non il suo valore.

• Classificazione di sicurezza — Gli strumenti MCP seguono le stesse regole di classificazione di sicurezza degli altri strumenti in Intric. Un assistente può usare uno strumento MCP solo se soddisfa i requisiti di classificazione dello Space a cui appartiene.

• OAuth per utente — Con OAuth 2.0, ogni utente ha il proprio token. Gli utenti possono accedere solo alle risorse esterne che hanno autorizzato individualmente.

• Ambito tenant — I record del server MCP sono limitati al tuo tenant. Non sono condivisi tra tenant.

Risoluzione dei problemi