AI-Bot – Bring Your Own MCP-Server

Dokumentation Website-Verwaltung
,
1

:bookmark: Diese Anleitung erklärt, wie Sie externe Model Context Protocol (MCP)-Server mit Discourse-AI-Agenten verbinden, sodass jeder MCP-kompatible Tool-Anbieter direkt innerhalb des KI-Bots genutzt werden kann.

:person_raising_hand: Erforderliche Benutzerstufe: Administrator

Was bedeutet “Bring Your Own MCP”?

Model Context Protocol ist ein offener Standard (ursprünglich von Anthropic vorgeschlagen), der es KI-Agenten ermöglicht, über eine standardmäßige HTTP/JSON-RPC-Schnittstelle mit externen Tool-Servern zu kommunizieren. Ein MCP-Server stellt ein Menü an “Tools” bereit – Funktionen mit typisierten Eingaben –, die ein LLM aufrufen kann, um Aufgaben zu erledigen.

Discourse AI fungiert nun als MCP-Client. Sie registrieren jeden HTTPS-MCP-Server im Admin-Bereich, Discourse entdeckt dessen verfügbare Tools, und diese Tools werden zu vollwertigen Bestandteilen innerhalb jedes von Ihnen gewählten KI-Agenten. Es ist kein JavaScript zu schreiben; die Tools werden vom Remote-Server definiert.

Dies unterscheidet sich von benutzerdefinierten Script-Tools, die das Schreiben von JavaScript erfordern, das innerhalb von Discourse ausgeführt wird. Mit MCP bringen Sie einen bereits laufenden externen Server mit.

Zusammenfassung

  • Registrierung eines MCP-Servers (URL + optionale Authentifizierung)
  • Discourse entdeckt und zwischenspeichert die Tools des Servers automatisch
  • Zuweisung des Servers an einen oder mehrere KI-Agenten
  • Optionale Einschränkung der Tools, die jeder Agent nutzen darf
  • Tools werden zur Laufzeit vom LLM aufgerufen und über Discourse an den externen Server weitergeleitet

Registrierung eines MCP-Servers

Navigieren Sie zu:

Admin → Plugins → Discourse AI → Tools → Reiter MCP-Server → Neuer MCP-Server

Füllen Sie die folgenden Felder aus:

Feld Beschreibung
Name Eine für Menschen lesbare Bezeichnung (wird im Agent-Editor und in Protokollen angezeigt)
Beschreibung Wofür dieser Server verwendet wird (Referenz für Administratoren)
URL Der HTTPS-Endpunkt des MCP-Servers – muss eine öffentliche HTTPS-URL sein, keine privaten IPs
Authentifizierung Eine der folgenden Optionen: Keine Authentifizierung, Header-Anmeldeinformationen oder OAuth
Timeout (Sekunden) Wie lange Discourse pro Anfrage wartet – Standardwert 30, Maximum 300
Aktiviert Umschalter, um den Server vorübergehend zu deaktivieren, ohne ihn zu löschen

:warning: URLs müssen HTTPS verwenden. localhost und RFC-1918-private Adressen sind blockiert (SSRF-Schutz wird serverseitig durchgesetzt).

Authentifizierungsoptionen

Keine Authentifizierung

Der Server ist öffentlich erreichbar. Es werden keine Anmeldeinformationen gesendet.

Header-Anmeldeinformationen

Ein geheimer Wert wird bei jeder Anfrage als HTTP-Header eingefügt.

  1. Erstellen Sie zunächst eine Anmeldeinformation unter Admin → KI → Anmeldeinformationen
  2. Wählen Sie diese im Formular für den MCP-Server als Anmeldeinformation aus
  3. Legen Sie den Namen des Auth-Headers fest (Standard: Authorization)
  4. Legen Sie das optionale Auth-Schema-Präfix fest (Standard: Bearer)

Der an den MCP-Server gesendete Anfrage-Header lautet:

Authorization: Bearer <geheimer-wert>

Sie können sowohl den Header-Namen als auch das Schema ändern, um jede von Ihrem Server erforderliche Authentifizierungsart zu unterstützen (z. B. X-Api-Key: <wert>, indem Sie das Schema leer lassen).

OAuth

Discourse implementiert einen vollständigen OAuth 2.0- und PKCE-Flow als MCP-Client. Dies unterstützt MCP-Server, die ihre Tools hinter OAuth schützen.

Einrichtungsschritte:

  1. Setzen Sie die Authentifizierung auf OAuth
  2. Wählen Sie die Client-Registrierung:
    • Client-Metadaten-Dokument (Standard) – Discourse veröffentlicht seine eigenen OAuth-Client-Metadaten unter https://ihre-seite.de/discourse-ai/mcp/oauth/client-metadata. Wenn der MCP-Server die RFC 7591 Dynamic Client Registration unterstützt, registriert sich Discourse automatisch.
    • Manuelle Client-Anmeldeinformationen – Geben Sie Ihre vorregistrierte OAuth-Client-ID ein und wählen Sie eine OAuth-Client-Geheimnis-Anmeldeinformation aus
  3. Optional können Sie OAuth-Berechtigungen (durch Leerzeichen getrennt) festlegen
  4. Speichern Sie den Server
  5. Klicken Sie auf Verbinden – Discourse leitet Sie über die Autorisierungsseite des Anbieters weiter
  6. Nach der Autorisierung werden Sie zum Admin-Bereich zurückgeführt, und der Status zeigt Verbunden

Erweiterte OAuth-Optionen (Umschalter “Erweiterte Optionen anzeigen”):

Option Zweck
OAuth-Autorisierungsparameter JSON-Objekt, das in die Autorisierungsanfrage eingefügt wird (z. B. {"access_type":"offline"})
OAuth-Token-Parameter JSON-Objekt, das in Token-Austauschanfragen eingefügt wird
Refresh-Token erforderlich Verbindungsabbruch, wenn der Anbieter kein Refresh-Token zurückgibt

Discourse aktualisiert Zugriffstoken automatisch vor Ablauf und versucht bei Vorhandensein eines Refresh-Tokens erneut, wenn ein 401-Fehler auftritt.

Testen der Verbindung

Bevor Sie einen Server einem Agenten zuweisen, verwenden Sie die Schaltfläche Verbindung testen im Editor-Formular. Dadurch wird sofort eine MCP-Sitzung initialisiert, tools/list aufgerufen und Folgendes zurückgegeben:

  • Verhandelte MCP-Protokollversion
  • Anzahl der entdeckten Tools
  • Namen aller Tools

Wenn der Test fehlschlägt, wird die Fehlermeldung des Servers (oder ein Timeout-Indikator) inline angezeigt.

Wie Discourse Tools entdeckt

Discourse folgt der MCP-Spezifikation 2025-03-26. Die Verbindungssequenz lautet:

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

Tool-Definitionen werden pro Server für 1 Stunde zwischengespeichert. Nach Ablauf des Caches wird dieser transparent durch einen Hintergrundjob aktualisiert. Der Cache-Schlüssel ist pro Site/pro Server, sodass Installationen mit mehreren Sites isoliert sind.

Sie können eine Aktualisierung auch manuell auslösen, indem Sie auf Verbindung testen klicken – dies lädt immer Live-Daten.

Der Gesundheitsstatus des Servers (healthy / error) wird bei jeder Cache-Aktualisierung aktualisiert.

Zuweisung von MCP-Servern an KI-Agenten

Sobald ein Server registriert ist, weisen Sie ihn einem Agenten zu:

  1. Gehen Sie zu Admin → Plugins → Discourse AI → Agenten und bearbeiten oder erstellen Sie einen Agenten
  2. Scrollen Sie zum Abschnitt MCP-Server (unter dem regulären Tools-Abschnitt)
  3. Die Liste zeigt alle aktivierten MCP-Server mit ihrer Tool-Anzahl und den geschätzten Token-Kosten an
  4. Schalten Sie einen Server ein – er steht nun diesem Agenten zur Verfügung

Tipp: Standardmäßig werden alle Tools eines Servers dem Agenten zur Verfügung gestellt. Die Lokalisierungszeichenfolge sagt es treffend: “Ausgewählte MCP-Server geben standardmäßig alle ihre Tools frei. Schränken Sie sie pro Agent ein, um den Token-Verbrauch zu reduzieren und die Tool-Auswahl fokussiert zu halten.”

Auswahl spezifischer Tools pro Agent

Das Vorhandensein von Dutzenden verfügbarer Tools erhöht die Token-Kosten jeder Nachricht (jede Tool-Definition wird im System-Prompt an das Modell gesendet). Um alles schlank zu halten:

  1. Klicken Sie im Agent-Editor neben einem zugewiesenen MCP-Server auf Tools auswählen
  2. Ein Modal zeigt jedes Tool, das der Server derzeit offenlegt, mit seiner Beschreibung und Parameterliste an
  3. Wählen Sie nur die Tools aus, die dieser Agent benötigt
  4. Klicken Sie auf Speichern – der Agent sieht nun nur noch die ausgewählte Teilmenge

Die ai_agent_mcp_servers-Verbindungstabelle speichert selected_tool_names als JSONB-Array. Ein leeres Array bedeutet “alle Tools aktiviert”.

Tool-Benennung und Konfliktlösung

MCP-Tool-Namen müssen innerhalb der Tool-Liste eines einzelnen Agenten (einschließlich der integrierten und benutzerdefinierten Script-Tools des Agenten) eindeutig sein. Discourse löst Konflikte automatisch:

  • Wenn zwei verschiedene MCP-Server ein Tool mit dem gleichen Namen offenlegen, benennt Discourse sie um: servername__toolname
  • Wenn ein integriertes Discourse-Tool und ein MCP-Tool denselben Namen haben, wird auch das MCP-Tool umbenannt
  • Wenn es nach der Umbenennung immer noch Kollisionen gibt, wird ein numerisches Suffix angehängt (_2, _3, …)

Der in der LLM-Aufruf verwendete function_name kann sich daher vom rohen tool_name auf dem MCP-Server unterscheiden. Dies wird transparent behandelt – die MCP-Tool-Klasse speichert den ursprünglichen tool_name_value separat und verwendet ihn beim Aufruf des Servers.

Funktionsweise von Tool-Aufrufen zur Laufzeit

Wenn das LLM entscheidet, ein MCP-Tool zu verwenden:

  1. Wiederverwendung der Sitzung: Discourse sucht in der aktuellen Bot-Kontext (context.mcp_state) nach einer zwischengespeicherten MCP-Sitzungs-ID für diesen Server. Sitzungen werden pro Bot-Antwortkette erstellt und über Tool-Aufrufe an denselben Server hinweg wiederverwendet.
  2. Initialisierung bei Bedarf: Wenn keine Sitzung existiert, wird ein neuer initialize- und notifications/initialized-Handshake ausgeführt.
  3. Aufruf: POST / mit { method: "tools/call", params: { name: tool_name, arguments: params } }
  4. Sitzungslaufzeitende: Wenn der Server 404 zurückgibt (abgelaufene Sitzung), initialisiert Discourse automatisch neu und versucht es einmal erneut.
  5. Normalisierung der Antwort: MCP-Inhaltselemente vom Typ text werden verkettet. Nicht-Text-Elemente werden JSON-seriellisiert. structuredContent wird als schön formatiertes JSON ausgegeben.
  6. Fehlerergebnis: Wenn der Server isError: true zurückgibt, erhält der Bot eine Fehlermeldung statt eines Ergebnisses.

Die Serverantwort kann reines JSON oder ein SSE-Stream sein – Discourse behandelt beides.

Anzeige der Token-Kosten

Im Agent-Editor zeigt jeder zugewiesene MCP-Server eine geschätzte Token-Anzahl an. Diese wird unter Verwendung des OpenAI-cl100k_base-Tokenizers berechnet, der auf die vollständige JSON-Signatur jedes Tools angewendet wird (Name + Beschreibung + Eingabeschema). Dies ist eine Näherung – die tatsächlichen Kosten hängen vom Tokenizer Ihres LLM ab.

Die Aufschlüsselung der Token-Kosten wird angezeigt, um Ihnen fundierte Entscheidungen darüber zu ermöglichen, welche Server und Tools einem bestimmten Agenten zugewiesen werden sollen.

Fehlerbehebung

Symptom Was zu prüfen ist
Verbindungstest schlägt mit Timeout fehl Erhöhen Sie das Timeout (Sekunden). Standardwert ist 30. Wenn der Server langsam initialisiert, versuchen Sie 60–120.
Verbindungstest erfolgreich, aber Tools erscheinen nicht im Agenten Stellen Sie sicher, dass der Server aktiviert ist und dass der Agent ihn im Abschnitt MCP-Server aktiviert hat.
OAuth-Status zeigt “Benötigt Aufmerksamkeit” Der letzte OAuth-Fehler wird im Editor-Formular angezeigt. Häufige Ursachen: Refresh-Token abgelaufen (Klicken Sie auf “Erneut verbinden”), Server gab unerwartete Berechtigungen zurück oder die Client-Metadaten-URL ist von Ihrem Server aus nicht erreichbar.
Tool-Namen sehen aus wie myserver__sometool Normal – ein anderes Tool (integriert oder von einem anderen Server) hatte denselben Namen. Das LLM sieht und verwendet diesen umbenannten Namen automatisch.
Gesundheitsstatus zeigt nach einer Weile “error” Der Hintergrundaktualisierungsjob konnte den Server nicht erreichen. Überprüfen Sie /logs auf Ihrer Site und stellen Sie sicher, dass der MCP-Server von Discourse-Host aus erreichbar ist.
Tools mitten im Gespräch nicht mehr funktionsfähig Sitzungslaufzeitende. Discourse versucht pro Tool-Aufruf automatisch einmal erneut, aber wenn der Server konsequent neu startet, verkürzen Sie seine Sitzungs-TTL oder untersuchen Sie die serverseitigen Protokolle.

Für eine tiefere Fehlersuche aktivieren Sie den Zugriff auf KI-Transkripte über ai_bot_debugging_allowed_groups und untersuchen Sie das vollständige Gesprächsprotokoll.

Technische Referenz

MCP-Protokoll-Details

Eigenschaft Wert
Protokollversion 2025-03-26
Transport HTTP POST (JSON-RPC 2.0)
SSE-Unterstützung Ja (für Streaming von tools/call-Antworten)
Sitzungsverwaltung Mcp-Session-Id-HTTP-Header
Maximale Antwortgröße 5 MB
Client User-Agent Discourse AI MCP Client / <version>

Unterstützung von JSON-Schemata

Discourse löst die folgenden JSON-Schema-Konstrukte in Tool-inputSchema-Definitionen, bevor sie an das LLM übergeben werden:

  • $ref – wird gegen die $defs / definitions des Root-Schemas aufgelöst
  • allOf – zusammengeführt (Properties- und Required-Arrays werden union-mäßig zusammengeführt)
  • anyOf / oneOf – die erste nicht-null-Variante wird verwendet

Relevante Quelldateien

Verwandte Themen

:bulb: Die Discourse-als-MCP-Server-Funktion (discourse/discourse-mcp) ist das Gegenstück dazu: Sie ermöglicht es externen KI-Clients (Claude Code, Cursor usw.), Ihre Discourse-Site zu lesen und zu schreiben. Diese Anleitung ist das Gegenteil – sie ermöglicht es Ihren Discourse-AI-Agenten, externe MCP-Server aufzurufen.

3 „Gefällt mir“
Bring your own MCP!