AI Bot – Porta il tuo server MCP

Documentazione Gestione del sito
,
1

:bookmark: Questa guida spiega come connettere server Model Context Protocol (MCP) esterni agli agenti Discourse AI, consentendo a qualsiasi provider di strumenti compatibile con MCP di essere utilizzato direttamente all’interno del bot AI.

:person_raising_hand: Livello utente richiesto: Amministratore

Cos’è “Bring Your Own MCP”?

Model Context Protocol è uno standard aperto (originariamente proposto da Anthropic) che permette agli agenti AI di comunicare con server di strumenti esterni tramite un’interfaccia standard HTTP/JSON-RPC. Un server MCP espone un menu di “strumenti” — funzioni con input tipizzati — che un LLM può chiamare per eseguire azioni.

Discourse AI agisce ora come client MCP. Registri qualsiasi server MCP HTTPS nel pannello di amministrazione, Discourse ne scopre gli strumenti disponibili e tali strumenti diventano cittadini di prima classe all’interno di qualsiasi agente AI tu scelga. Non è necessario scrivere JavaScript; gli strumenti sono definiti dal server remoto.

Questo differisce dagli strumenti script personalizzati che richiedono la scrittura di JavaScript eseguito all’interno di Discourse. Con MCP porti un server esterno già in esecuzione.

Riepilogo

  • Registra un server MCP (URL + autenticazione opzionale)
  • Discorse scopre automaticamente e memorizza nella cache gli strumenti del server
  • Assegna il server a uno o più agenti AI
  • Opzionalmente limita quali strumenti può utilizzare ogni agente
  • Gli strumenti sono chiamati dall’LLM a runtime, instradati attraverso Discourse al server esterno

Registrazione di un server MCP

Naviga in:

Admin → Plugins → Discourse AI → Tools → scheda MCP servers → New MCP server

Compila i seguenti campi:

Campo Descrizione
Name Un’etichetta leggibile dall’uomo (mostrata nell’editor dell’agente e nei log)
Description A cosa serve questo server (riferimento per l’amministratore)
URL L’endpoint HTTPS del server MCP — deve essere un URL HTTPS pubblico, nessun IP privato
Authentication Una tra: Nessuna autenticazione, Credenziali header o OAuth
Timeout (seconds) Quanto tempo Discourse attende per richiesta — default 30, massimo 300
Enabled Interruttore per disabilitare temporaneamente il server senza eliminarlo

:warning: Gli URL devono utilizzare HTTPS. localhost e gli indirizzi privati RFC-1918 sono bloccati (la protezione SSRF è applicata lato server).

Opzioni di autenticazione

Nessuna autenticazione

Il server è raggiungibile pubblicamente. Nessuna credenziale viene inviata.

Credenziali header

Un valore segreto viene iniettato come header HTTP in ogni richiesta.

  1. Crea prima una Credential in Admin → AI → Credentials
  2. Selezionala come Credential nel modulo del server MCP
  3. Imposta il nome dell’Auth header (default: Authorization)
  4. Imposta il prefisso opzionale dello Auth scheme (default: Bearer)

L’header di richiesta inviato al server MCP sarà:

Authorization: Bearer <il-tuo-valore-segreto>

Puoi modificare sia il nome dell’header che lo schema per adattarti a qualsiasi stile di autenticazione richiesto dal tuo server (ad esempio, X-Api-Key: <valore> lasciando lo schema vuoto).

OAuth

Discourse implementa un flusso completo OAuth 2.0 + PKCE come client MCP. Questo supporta server MCP che proteggono i propri strumenti dietro OAuth.

Passaggi di configurazione:

  1. Imposta Authentication su OAuth
  2. Scegli Client registration:
    • Client metadata document (default) — Discourse pubblica i propri metadati del client OAuth su https://your-site.com/discourse-ai/mcp/oauth/client-metadata. Se il server MCP supporta RFC 7591 Dynamic Client Registration, Discourse si registrerà automaticamente
    • Manual client credentials — inserisci il tuo OAuth client ID pre-registrato e scegli una credenziale OAuth client secret
  3. Opzionalmente imposta OAuth scopes (separati da spazi)
  4. Salva il server
  5. Clicca Connect — Discourse ti reindirizzerà attraverso la pagina di autorizzazione del provider
  6. Dopo aver autorizzato, verrai reindirizzato all’amministrazione e lo stato mostrerà Connected

Opzioni OAuth avanzate (attiva “Show advanced options”):

Opzione Scopo
OAuth authorization params Oggetto JSON unito alla richiesta di autorizzazione (es. {"access_type":"offline"})
OAuth token params Oggetto JSON unito alle richieste di scambio token
Require refresh token Fallisce la connessione se il provider non restituisce un refresh token

Discourse aggiorna automaticamente i token di accesso prima della scadenza e riprova in caso di 401 se è disponibile un refresh token.

Test della connessione

Prima di assegnare un server a un agente, utilizza il pulsante Test connection nel modulo dell’editor. Questo inizializza immediatamente una sessione MCP, chiama tools/list e restituisce:

  • Protocol version MCP negoziata
  • Numero di strumenti scoperti
  • Nomi di tutti gli strumenti

Se il test fallisce, il messaggio di errore dal server (o un indicatore di timeout) viene mostrato in linea.

Come Discourse scopre gli strumenti

Discourse segue la specifiche MCP 2025-03-26. La sequenza di connessione è:

Discourse → POST /  { method: "initialize", params: { protocolVersion, capabilities, clientInfo } }
Server    → { result: { protocolVersion, capabilities } } + header Mcp-Session-Id
Discourse → POST /  { method: "notifications/initialized" }   (handshake sessione completato)
Discourse → POST /  { method: "tools/list", session_id: … }
Server    → { result: { tools: [ { name, description, inputSchema } … ] } }

Le definizioni degli strumenti sono memorizzate nella cache per 1 ora per server. Dopo la scadenza della cache, un processo in background la aggiorna in modo trasparente. La chiave della cache è per sito/per server, quindi le installazioni multi-sito sono isolate.

Puoi anche attivare manualmente un aggiornamento cliccando Test connection — questo recupera sempre i dati live.

Lo stato di salute del server (healthy / error) viene aggiornato ad ogni aggiornamento della cache.

Assegnazione dei server MCP agli agenti AI

Una volta registrato un server, assegnalo a un agente:

  1. Vai in Admin → Plugins → Discourse AI → Agents e modifica o crea un agente
  2. Scorri fino alla sezione MCP servers (sotto la sezione Tools regolare)
  3. L’elenco mostra tutti i server MCP abilitati con il loro conteggio strumenti e il costo token stimato
  4. Attiva un server — ora è disponibile per quell’agente

Suggerimento: Per impostazione predefinita, tutti gli strumenti di un server sono resi disponibili all’agente. La stringa locale lo dice bene: “Selected MCP servers expose all of their tools by default. Narrow them per agent to reduce token usage and keep tool choice focused.”

Selezione di strumenti specifici per agente

Avere dozzine di strumenti disponibili aumenta il costo token di ogni messaggio (ogni definizione di strumento viene inviata al modello nel prompt di sistema). Per mantenere le cose snelle:

  1. Nell’editor dell’agente, accanto a un server MCP assegnato, clicca Choose tools
  2. Una finestra modale mostra ogni strumento attualmente esposto dal server, con la sua descrizione e l’elenco dei parametri
  3. Seleziona solo gli strumenti di cui l’agente ha bisogno
  4. Clicca Salva — l’agente vedrà ora solo il sottoinsieme selezionato

La tabella di join ai_agent_mcp_servers memorizza selected_tool_names come array JSONB. Un array vuoto significa “tutti gli strumenti abilitati”.

Naming degli strumenti e risoluzione dei conflitti

I nomi degli strumenti MCP devono essere unici all’interno dell’elenco strumenti di un singolo agente (inclusi gli strumenti integrati e script personalizzati dell’agente). Discourse gestisce i conflitti automaticamente:

  • Se due server MCP diversi espongono uno strumento con lo stesso nome, Discourse li namespace: servername__toolname
  • Se uno strumento integrato di Discourse e uno strumento MCP condividono un nome, anche lo strumento MCP viene namespace
  • Se ci sono ancora collisioni dopo il namespace, viene aggiunto un suffisso numerico (_2, _3, …)

Il function_name utilizzato nella chiamata LLM può quindi differire dal tool_name grezzo sul server MCP. Questo è gestito in modo trasparente — la classe dello strumento MCP memorizza sempre il tool_name_value originale separatamente e lo utilizza quando chiama il server.

Come funzionano le chiamate agli strumenti a runtime

Quando l’LLM decide di utilizzare uno strumento MCP:

  1. Riutilizzo sessione: Discourse cerca un ID sessione MCP memorizzato nella cache per questo server nel contesto corrente del bot (context.mcp_state). Le sessioni sono create per catena di risposta del bot e riutilizzate tra le chiamate agli strumenti allo stesso server.
  2. Inizializza se necessario: Se non esiste una sessione, viene eseguito un nuovo handshake initialize + notifications/initialized.
  3. Chiamata: POST / con { method: "tools/call", params: { name: tool_name, arguments: params } }
  4. Scadenza sessione: Se il server restituisce 404 (sessione scaduta), Discourse si ri-inizializza automaticamente e riprova una volta.
  5. Normalizzazione risposta: Gli elementi di contenuto MCP di tipo text vengono concatenati. Gli elementi non testo vengono serializzati in JSON. structuredContent è JSON formattato in modo leggibile.
  6. Risultato errore: Se il server restituisce isError: true, il bot riceve un messaggio di errore invece di un risultato.

La risposta del server può essere JSON semplice o un flusso SSE — Discourse gestisce entrambi.

Visualizzazione del costo token

Nell’editor dell’agente, ogni server MCP assegnato mostra un numero di token stimato. Questo viene calcolato utilizzando il tokenizer OpenAI cl100k_base applicato alla firma JSON completa di ogni strumento (nome + descrizione + schema di input). Questa è un’approssimazione — il costo effettivo dipende dal tokenizer del tuo LLM.

La suddivisione del costo token viene mostrata per aiutarti a prendere decisioni informate su quali server e strumenti assegnare a un dato agente.

Risoluzione dei problemi

Sintomo Cosa controllare
Test connection fallisce con timeout Aumenta Timeout (seconds). Il default è 30. Se il server è lento nell’inizializzazione, prova 60–120.
Test ha successo ma gli strumenti non appaiono nell’agente Assicurati che il server sia Enabled e che l’agente lo abbia attivato nella sua sezione MCP servers.
Stato OAuth mostra “Needs attention” L’ultimo errore OAuth viene mostrato nel modulo dell’editor. Cause comuni: refresh token scaduto (clicca Reconnect), il server ha restituito scope inaspettati o l’URL dei metadati del client non è raggiungibile dal tuo server.
I nomi degli strumenti sembrano myserver__sometool Normale — un altro strumento (integrato o da un altro server) aveva lo stesso nome. L’LLM vede e utilizza automaticamente questo nome namespace.
Salute mostra “error” dopo un periodo Il processo di aggiornamento in background non è riuscito a raggiungere il server. Controlla /logs sul tuo sito e verifica che il server MCP sia raggiungibile dall’host di Discourse.
Gli strumenti hanno smesso di funzionare a metà conversazione Scadenza sessione. Discourse riprova automaticamente una volta per chiamata allo strumento, ma se il server si riavvia costantemente, accorcia il suo TTL sessione o investiga i log lato server.

Per un debug più approfondito, abilita l’accesso alle trascrizioni AI tramite ai_bot_debugging_allowed_groups ed esamina l’intero registro della conversazione.

Riferimento tecnico

Dettagli protocollo MCP

Proprietà Valore
Protocol version 2025-03-26
Transport HTTP POST (JSON-RPC 2.0)
Supporto SSE Sì (per streaming delle risposte tools/call)
Gestione sessione Header HTTP Mcp-Session-Id
Max response body 5 MB
Client User-Agent Discourse AI MCP Client / <versione>

Supporto JSON Schema

Discourse risolve le seguenti costruzioni JSON Schema nelle definizioni inputSchema degli strumenti prima di passarle all’LLM:

  • $ref — risolto rispetto a $defs / definitions dello schema radice
  • allOf — unito (proprietà e array required sono uniti)
  • anyOf / oneOf — viene utilizzata la prima variante non null

File sorgente rilevanti

Argomenti correlati

:bulb: La funzione Discourse-as-MCP-server (discourse/discourse-mcp) è il complemento di questa: permette a client AI esterni (Claude Code, Cursor, ecc.) di leggere e scrivere il tuo sito Discourse. Questa guida è l’inverso — permette ai tuoi agenti Discourse AI di chiamare server MCP esterni.

3 Mi Piace
Bring your own MCP!