MCPServer

Ambito: namespaced · Modalità: catalog (incluso, con licenza) · external (gratuito)

Un MCPServer definisce un singolo server Model Context Protocol che una o più ChatUI possono usare. Definiscilo una volta e fai riferimento a esso da qualsiasi ChatUI tramite spec.mcpRefs — l'operatore lo collega per te a LibreChat (l'endpoint Agents).

Spec

Campo	Tipo	Descrizione
mode	enum catalog | external (obbligatorio)	Server incluso oppure endpoint gestito dall'utente
catalog	string	Chiave del server incluso (mode=catalog), ad es. websearch
external	object	Endpoint gestito dall'utente (mode=external)
displayName	string	Il nome del server mostrato in LibreChat (per default la chiave del catalogo o il nome della CR)
serverInstructions	string	Sostituisce le istruzioni sugli strumenti rivolte al modello

external

Campo	Descrizione
url	L'endpoint MCP (ad es. http://host:8080/mcp)
type	Trasporto: streamable-http (predefinito) o sse
inCluster	Forza il trattamento tramite allowlist SSRF. Omettilo per il rilevamento automatico dall'host (DNS del servizio / IP privato)
timeoutMs	Timeout per richiesta (predefinito 60000)
headersSecretRef	Secret nello stesso namespace le cui chiavi diventano header HTTP (iniettati tramite env, mai scritti nella configurazione generata)
oauth	Autenticazione OAuth 2.0 verso un endpoint MCP protetto (con licenza: mcp-oauth) — vedi Autenticazione OAuth

external.oauth (con licenza: mcp-oauth)

Imposta esattamente uno tra interactive e onBehalfOf (una regola di validazione lo impone). Senza la licenza mcp-oauth l'MCPServer risulta Refused (MCPOAuthUnlicensed) e una ChatUI che vi fa riferimento resta non collegata.

Campo	Descrizione
interactive	Flusso authorization-code + PKCE per utente (ogni utente autorizza una volta presso l'IdP)
interactive.authorizationURL	Endpoint di autorizzazione dell'IdP. Facoltativo — omettilo (insieme a tokenURL) per lasciare che LibreChat lo rilevi automaticamente dai metadati del server
interactive.tokenURL	Endpoint dei token dell'IdP (facoltativo, vedi sopra)
interactive.clientSecretRef	Secret nello stesso namespace che contiene il client ID (client-id) e, per i client confidenziali, il client secret (client-secret). Iniettato tramite env, referenziato come ${…} — mai inserito inline. Omettilo per un client pubblico/PKCE
interactive.scopes	Scope richiesti all'IdP (uniti da spazi)
interactive.tokenExchangeMethod	default_post (client secret nel body) o basic_auth
onBehalfOf	Scambio di token on-behalf-of silenzioso della sessione SSO dell'utente (nessuna richiesta all'utente)
onBehalfOf.scopes	Scope downstream da richiedere (obbligatorio, non vuoto), ad es. api://<client-id>/<permission>

Modalità

• catalog (con licenza: bundled-mcp-catalog) — l'operatore distribuisce il server incluso come un'unica release condivisa e con conteggio dei riferimenti per l'intero cluster (in navique-mcp-system) e collega ogni ChatUI che vi fa riferimento al suo Service interno al cluster. Senza licenza (Community) ⇒ l'MCPServer risulta Refused (nessun deploy) e una ChatUI che vi fa riferimento semplicemente attende. Il primo server incluso è websearch (ricerca web enterprise: SearXNG + scraping + PII + reranking). L'ingombro si regola a livello di cluster tramite PlatformConfig.spec.mcp (full predefinito, oppure minimal).
• external (gratuito / Community) — punta a un endpoint MCP che gestisci tu stesso. Le destinazioni interne al cluster vengono rilevate automaticamente e ricevono l'allowlist SSRF di LibreChat (mcpSettings), così gli indirizzi privati sono raggiungibili.

Allowlist SSRF (automatica)

LibreChat blocca le chiamate MCP verso indirizzi privati/interni al cluster a meno che non siano in allowlist. Se ne occupa l'operatore: quando almeno uno dei server referenziati è interno al cluster, genera un blocco mcpSettings di primo livello il cui allowedDomains elenca l'origine di ogni server referenziato (un'allowlist globale — anche i server pubblici devono essere elencati, altrimenti verrebbero bloccati) e il cui allowedAddresses esenta gli host interni al cluster. Non devi configurare nulla.

Esempio — ricerca web inclusa

apiVersion: core.navique.com/v1alpha1
kind: MCPServer
metadata:
  name: websearch
  namespace: forge
spec:
  mode: catalog
  catalog: websearch
---
apiVersion: core.navique.com/v1alpha1
kind: ChatUI
metadata:
  name: forge-ui
  namespace: forge
spec:
  # … gateway/mongo/meili/secrets …
  mcpRefs:
    - { name: websearch }

Esempio — external (interno al cluster, con autenticazione)

apiVersion: core.navique.com/v1alpha1
kind: MCPServer
metadata:
  name: internal-docs
  namespace: forge
spec:
  mode: external
  external:
    url: http://docs-mcp.team.svc.cluster.local:8080/mcp
    headersSecretRef: { name: docs-mcp-auth }   # keys → HTTP headers

Autenticazione OAuth (con licenza)

Funzionalità con licenza: mcp-oauth. Collega le ChatUI a server MCP che richiedono OAuth 2.0. Due modalità — scegline una per server:

• Interattiva (authorization-code + PKCE). Ogni utente autorizza una volta presso l'IdP (una richiesta "OAuth Required" una tantum nel menu della chat); i token vengono conservati cifrati e rinnovati automaticamente. Funziona con qualsiasi provider. Le credenziali del client provengono da un Secret e non vengono mai scritte nella configurazione generata. Poiché l'IdP reindirizza il browser alla UI, la ChatUI deve essere esposta tramite spec.ingress affinché il callback venga risolto.
• On-behalf-of (OBO). LibreChat scambia silenziosamente il token della sessione SSO esistente dell'utente con un token downstream — nessuna richiesta all'utente, nessun client secret. La ChatUI deve avere spec.sso configurato (il token scambiato è quello del login SSO). Ideale per server basati su Entra/OpenID.

Esempio — OAuth interattivo

apiVersion: core.navique.com/v1alpha1
kind: MCPServer
metadata:
  name: salesforce
  namespace: forge
spec:
  mode: external
  external:
    url: https://api.salesforce.com/platform/mcp/v1/…
    oauth:
      interactive:
        authorizationURL: https://login.salesforce.com/services/oauth2/authorize
        tokenURL: https://login.salesforce.com/services/oauth2/token
        scopes: [mcp_api, refresh_token]
        clientSecretRef: { name: salesforce-mcp-oauth }  # keys: client-id, client-secret

Esempio — on-behalf-of (Entra)

apiVersion: core.navique.com/v1alpha1
kind: MCPServer
metadata:
  name: graph
  namespace: forge
spec:
  mode: external
  external:
    url: https://mcp.example.com
    oauth:
      onBehalfOf:
        scopes: ["api://<client-id>/Files.Read"]
# The referencing ChatUI must have spec.sso configured.

Note

• Fare riferimento a un qualsiasi server MCP abilita automaticamente l'endpoint Agents di LibreChat (gli strumenti MCP sono utilizzabili solo tramite gli Agents).
• Web Search e Code Interpreter nativi vengono disattivati dall'operatore, e gli utenti (amministratori inclusi) non possono aggiungere né disattivare server MCP dalla UI — solo la configurazione dell'operatore li definisce.

Status

{ phase, url (resolved endpoint), transport, inCluster, serverName, conditions, observedGeneration }. Nome breve mcp.