Bring your own MCP server to kagent reference architecture

Panoramica

Questa soluzione risponde alla necessità di un meccanismo standardizzato, sicuro e scalabile per l'integrazione dei server Model Context Protocol (MCP) negli ambienti Distributed Cloud solo software (GDC) con kagent di cui è stato eseguito il deployment come piattaforma AI agentica.

Il problema principale affrontato è la mancanza di un'interfaccia unificata per collegare le applicazioni di modelli linguistici di grandi dimensioni (LLM) a origini dati e strumenti localizzati all'interno di cluster GDC regolamentati. Questa architettura fornisce un framework Bring Your Own (BYO) che consente agli sviluppatori di eseguire il deployment di server MCP personalizzati che espongono funzionalità aziendali specifiche come strumenti per gli agenti AI.

Questa architettura copre i protocolli di comunicazione tra kagent e i server MCP e la topologia dei componenti su GDC. Esclude la logica interna dei server MCP di terze parti.

Il pubblico di destinazione di questo documento include gli amministratori della piattaforma GDC, gli sviluppatori di applicazioni AI e i revisori della sicurezza responsabili dell'approvazione delle integrazioni di strumenti esterni.

Caratteristiche e funzionalità

kagent fornisce un framework flessibile che consente alle organizzazioni di utilizzare server MCP BYO per integrare gli LLM con strumenti locali o proprietari. Grazie a questa funzionalità, gli agenti possono interagire con origini dati specializzate ed eseguire attività complesse all'interno del perimetro di un cluster GDC.

Componenti funzionali e responsabilità

L'architettura include i seguenti componenti funzionali:

  • Piattaforma di agenti AI (kagent): funge da orchestratore centrale. Gestisce il ciclo di vita della sessione dell'agente, indirizza le query degli utenti all'LLM e coordina l'esecuzione degli strumenti tramite il client MCP.
  • LLM: gestisce la comprensione del linguaggio naturale e il ragionamento. Determina quando è necessario uno strumento specifico per soddisfare una richiesta e genera i parametri necessari per chiamare lo strumento.
  • Server MCP: espone strumenti specifici tramite MCP come servizio autonomo. Gestisce la logica di basso livello dell'interazione con i sistemi aziendali o i repository di dati di backend.

Interfacce e flusso di dati

L'architettura end-to-end si basa su interfacce standardizzate per mantenere l'interoperabilità e la sicurezza:

  • Trasporto MCP: kagent comunica con il server MCP utilizzando JSON-RPC standardizzato su un trasporto MCP supportato, come HTTP trasmissibile in streaming (o HTTP con SSE) o stdio. Questa interfaccia definisce il modo in cui gli strumenti vengono rilevati, descritti e richiamati.
  • Flusso di dati: il ciclo di vita della richiesta segue questi passaggi:
    1. L'utente invia un prompt a kagent.
    2. kagent inoltra il prompt all'LLM.
    3. L'LLM identifica una chiamata allo strumento e la restituisce a kagent.
    4. kagent inoltra la richiesta al server MCP.
    5. Il server MCP esegue lo strumento sull'origine dati locale e restituisce il risultato.
    6. kagent invia il risultato all'LLM per generare la risposta finale.

Architettura

Per dimostrare come eseguire il deployment e utilizzare un server MCP BYO, questa architettura di riferimento utilizza l'applicazione open source Nextcloud, il relativo server MCP e l'agente Nextcloud su Solo Enterprise per kagent.

Questo esempio gestisce il modello Gemma 4 utilizzando vLLM.

L'architettura connette Nextcloud, kagent e il modello Gemma 4 all'interno dell'ambiente GDC. In questa configurazione, kagent utilizza Nextcloud come repository di dati in modo che il modello Gemma 4 possa accedere ed elaborare le informazioni in Nextcloud tramite interfacce MCP standardizzate.

Nextcloud è una piattaforma di collaborazione e spazio di archiviazione sul cloud open source in hosting autonomo che supporta il deployment on-premise per aiutarti a mantenere il controllo e la privacy sui dati degli utenti. È un componente di openDesk.

Nextcloud include le seguenti funzionalità:

  • Sincronizzazione e condivisione dei file: archivia i file, sincronizzali su dispositivi desktop e mobili tramite app dedicate e condividili utilizzando i link.
  • Strumenti di produttività: utilizza i client di posta, calendario, contatti e gestione delle attività integrati.
  • Collaborazione: integra suite per ufficio, come Collabora Online o ONLYOFFICE, direttamente in Nextcloud per modificare insieme documenti, fogli di lavoro e presentazioni in tempo reale.
  • Estensibilità: installa i plug-in dall'app store per aggiungere funzionalità come gestori delle password, bacheche Kanban o lettori musicali.

Questa soluzione richiede GDC con kagent e vLLM che gestiscono il modello Gemma 4. Il seguente diagramma illustra la configurazione della convalida:

Configurazione della convalida con GDC, kagent, Nextcloud e vLLM che gestisce Gemma 4.

Materiali aggiuntivi