Custom MCP Server

Mit Custom MCP Servern kannst Du eigene Funktionalitäten in MeinGPT integrieren. Verbinde Deinen Server über eine URL und erweitere die Fähigkeiten Deiner Assistenten.

Für interne bzw. On-Premise-Systeme nutze das übergreifende Muster On-Premise Connections.

Server-Konfiguration

Um einen Custom MCP Server zu integrieren, benötigst Du eine Endpunkt-URL. Es gibt zwei Transportmöglichkeiten:

HTTP Streaming (Empfohlen)

https://ihr-server.com/mcp

Diese Methode nutzt HTTP Streaming für eine effiziente Echtzeit-Kommunikation.

Server-Sent Events (SSE)

https://ihr-server.com/sse

Alternative Methode mit Server-Sent Events für die Kommunikation.

Server-Integration

Es gibt zwei Wege, einen Custom MCP Server hinzuzufügen:

Beide Wege führen zum selben Formular.

Felder im Formular

Authentifizierungsoptionen

Custom MCP Server unterstützen drei unabhängige Authentifizierungsmechanismen: statische Header, Autorisierung (OAuth) und JWT Identity Forwarding. Du kannst sie kombinieren, beachte aber den Abschnitt „Priorität" weiter unten, wenn mehrere denselben Header betreffen.

Welche Anmeldung passt zu welchem Server?

Ob ein Server OAuth und die automatische Registrierung unterstützt, steht in dessen Dokumentation oder beim Betreiber.

Statische Header

Füge in der MCP-Server-Konfiguration einen oder mehrere eigene HTTP-Header hinzu (z. B. Authorization: Bearer <dein-token>) unter Eigene Header. Nutze dies für Server, die durch einen statischen API-Key geschützt sind, oder durch ein statisches Token am Rand (z. B. eine WAF oder ein Reverse Proxy vor deinem MCP-Endpunkt).

Autorisierung

Das Feld Autorisierung in der MCP-Server-Konfiguration bietet drei Modi:

• Keine – keine Anmeldung, oder die Header unten tragen bereits die Zugangsdaten.
• OAuth: automatisch registrieren (DCR) – MeinGPT registriert sich selbst beim Server; jede Person meldet sich mit dem eigenen Konto an. Funktioniert mit den meisten Servern.
• OAuth: eigener Client – für Server ohne automatische Registrierung. Registriere MeinGPT einmal in deren Admin-Konsole (Client-ID, Client-Secret, Authorization-Endpunkt, Token-Endpunkt, Authentifizierung am Token-Endpunkt); jede Person meldet sich danach mit dem eigenen Konto an.

Manueller OAuth-Client einrichten

Wählst Du OAuth: eigener Client, klappen zusätzliche Felder auf. Die Werte dafür stammen aus der Admin-Konsole des Ziel-Systems, in der Du MeinGPT einmal als OAuth-Anwendung registrierst.

Die Redirect-URL, die Du dort einträgst, lautet:

https://<deine-MeinGPT-Adresse>/oauth/callback

Auf der MeinGPT-Cloud ist das https://app.meingpt.com/oauth/callback. Betreibst Du MeinGPT unter einer eigenen Domain, nimm diese Adresse mit demselben Pfad. Ohne exakt eingetragene Redirect-URL bricht der Server die Anmeldung ab.

Danach füllst Du in MeinGPT diese Felder:

Die Zugangsdaten hängen an genau diesem Connector, nicht an der URL. Zwei Personen können denselben Server mit unterschiedlichen OAuth-Anwendungen anlegen, ohne sich gegenseitig zu überschreiben.

Das Wählen eines OAuth-Modus allein öffnet noch kein Autorisierungsfenster. Wie bei anderen Connectoren (siehe Connectoren aktivieren) startet der OAuth-Ablauf erst, wenn MeinGPT den Server tatsächlich verwenden will – also wenn Du im Chat mit dem Assistenten eine Anfrage stellst, für die er das Tool aufruft. Du bekommst dann im Chat eine Aufforderung mit einer Verbinden-Schaltfläche; erst ein Klick darauf öffnet die Autorisierungsseite des MCP-Servers. Alternativ kannst Du die Verbindung ohne Chat manuell auslösen: Öffne Einstellungen → Verbindungen, suche den Connector und klicke dort auf Verbinden. Ein vollständiges Beispiel mit Screenshots findest Du unter Mit n8n MCP verbinden.

Priorität

Wenn Du sowohl einen statischen Authorization-Header konfigurierst als auch die Autorisierung auf einen OAuth-Modus setzt und die Verbindung erfolgreich zustande kommt, übernimmt OAuth den Authorization-Header — Dein statischer Wert wird dann nicht gesendet. Beide Optionen schließen sich in der Konfigurationsoberfläche nicht gegenseitig aus; setze daher nicht beide für denselben Server, es sei denn, OAuth soll nach erfolgreicher Verbindung Vorrang haben. JWT Identity Forwarding ist davon nicht betroffen, da es im separaten Header X-meinGPT-JWT gesendet wird (siehe unten).

Das Formular weist Dich direkt darauf hin: Sobald ein Header Authorization heißt (Groß-/Kleinschreibung egal) und die Autorisierung nicht auf Keine steht, erscheint unter der Header-Zeile in Rot „OAuth setzt diesen Header selbst. Dieser Wert wird ignoriert.“ Speichern kannst Du trotzdem — der Hinweis blockiert nichts, denn derselbe Header ist ja legitim, sobald Du zurück auf Keine wechselst. Siehst Du ihn, hast Du die Wahl: Autorisierung auf Keine setzen, um mit dem Header zu authentifizieren, oder den Header löschen und OAuth die Arbeit machen lassen.

Server für Kolleginnen und Kollegen freigeben

Ein eigener MCP-Server gehört zunächst nur Dir: Er taucht unter Einstellungen → Verbindungen in Deinem Konto auf, und niemand sonst sieht ihn. Es gibt keine Freigabe direkt am Server – der Weg führt über einen Assistenten.

Wie sich die Verbindung danach für Deine Kolleg:innen verhält, hängt von der Authentifizierungsart ab:

• Statischer Header (fester Token / API-Key): Die Verbindung wirkt wie eine gemeinsame, zentrale Verbindung. Sobald Du den Server mit statischem Header zu einem Assistenten hinzufügst, nutzen alle berechtigten Nutzer:innen desselben Assistenten automatisch diesen Token mit – ohne eigene Einrichtung oder Anmeldung. Du stellst damit faktisch das gemeinsame „Service-Konto" für alle bereit. Beachte: Alle agieren dann mit denselben Berechtigungen dieses Tokens; wähle ihn deshalb so eng wie möglich auf das, was tatsächlich gebraucht wird.
• OAuth: Hier authentifiziert sich jede Person einzeln, wie im folgenden Ablauf beschrieben.
• JWT Identity Forwarding: Wird automatisch an jede Anfrage angehängt, für wen auch immer den Assistenten gerade nutzt – dafür ist keine eigene Einrichtung, Anmeldung oder ein Verbinden-Schritt nötig. Das funktioniert unabhängig von und zusätzlich zu den beiden anderen Mechanismen: Ob JWT aktiviert ist, ändert nichts daran, ob zusätzlich eine persönliche OAuth-Anmeldung erforderlich ist.

Bei OAuth gilt zusätzlich: Nach dem Verbinden erscheint der Server auch bei Deinen Kolleginnen und Kollegen unter Einstellungen → Verbindungen, dort mit dem Abzeichen Geteilt. Solche Einträge sind schreibgeschützt: URL, Header und Autorisierung lassen sich nicht ändern und der Eintrag nicht löschen – möglich ist nur Trennen, was die eigene Anmeldung widerruft. Konfiguration und Löschen bleiben bei der Person, die den Server angelegt hat.

Bei einem manuellen OAuth-Client gilt das genauso: Die eine hinterlegte Client-ID mit Secret ist die Registrierung von MeinGPT beim Ziel-System – sie ist kein Nutzerkonto und gibt keine Daten frei. Wer den Assistenten nutzt, meldet sich damit trotzdem persönlich an.

Beispiel: OpenProject verbinden

OpenProject bietet einen MCP-Server, aber keine automatische Client-Registrierung – ein typischer Fall für den manuellen OAuth-Client. Der MCP-Server ist ein Enterprise-Add-on von OpenProject und muss dort freigeschaltet sein.

Signierte Nutzeridentität (optional)

Das übergreifende Konzept ist hier dokumentiert: JWT Identity Forwarding.

Für eigene MCP-Server kannst Du in der MCP-Konfiguration den Schalter Signierte Nutzeridentität aktivieren. Wenn aktiv, sendet MeinGPT bei jedem Request zusätzlich:

X-meinGPT-JWT: <signed-jwt-token>

Der Token enthält u. a. folgende Claims:

• sub (User-ID)
• email
• username
• aud (Organization-ID)
• organizationName
• role
• teams

Wenn Du den Token serverseitig verifizieren möchtest, nutze die zentrale Doku: JWT Identity Forwarding oder Security & Authentication Proxy.

Best Practices

• Sicherheit: Verwende HTTPS für alle Server-Verbindungen
• Monitoring: Überwache die Server-Performance und -Verfügbarkeit
• Fehlerbehandlung: Implementiere Fallback-Optionen für Serverausfälle
• Dokumentation: Dokumentiere Server-spezifische Funktionen und Parameter

Fehlerbehebung

Fehler „Invalid state parameter" oder „OAuth flow expired" beim Verbinden

Beim Klick auf Verbinden startet MeinGPT eine Autorisierung, die 10 Minuten gültig ist und nur einmal verwendet werden kann. Dauert die Anmeldung beim Ziel-System länger (z. B. wegen einer Freigabe durch eine Administratorin oder einen Administrator, MFA oder einem offenen Tab), oder rufst Du die Rückkehr-Seite ein zweites Mal auf (Neuladen, Zurück-Schaltfläche, Link erneut öffnen), lehnt MeinGPT die Anmeldung mit „Invalid state parameter" oder „OAuth flow expired" ab. Die Verbindung kann dabei trotzdem schon gespeichert worden sein; ein Schaden ist nicht entstanden.

So gehst Du vor:

1. Öffne Einstellungen → Verbindungen und prüfe, ob der Connector bereits als Verbunden angezeigt wird. Dann ist nichts weiter zu tun.
2. Schließe sonst das alte Autorisierungsfenster bzw. den alten Tab.
3. Suche den Connector in Einstellungen → Verbindungen und klicke erneut auf Verbinden (oder stelle im Chat noch einmal eine Anfrage, die das Tool nutzt).
4. Schließe die Anmeldung beim Ziel-System innerhalb von 10 Minuten ab und lass die Seite danach in Ruhe, bis MeinGPT sie weiterleitet.

Muss die Freigabe im Ziel-System durch eine andere Person erfolgen, kläre diese zuerst und starte die Verbindung erst danach.

Warnung „Einige Tools konnten nicht geladen werden"

Erscheint diese Warnung unter einer Chat-Antwort, ließ sich mindestens ein für den Chat aktiver Konnektor – ein Custom MCP Server oder ein fertiger Konnektor wie Make – beim Start der Anfrage nicht laden. Das ist ein anderer Fehlerfall als ein fehlgeschlagener Tool-Aufruf (siehe unten): Es wurde noch kein Tool aufgerufen, deshalb gibt es keine aufklappbare Tool-Aufruf-Kachel im Chat.

Die zweite Zeile der Warnung nennt den betroffenen Konnektor, zum Beispiel „Fehlgeschlagene Tools: Make“. Den Grund zeigt MeinGPT im Chat nicht an; er lässt sich derzeit nur in den Backend-Logs nachvollziehen. Prüfe zuerst selbst:

• Verbindungsstatus: Öffne Einstellungen → Verbindungen und sieh nach, ob der betroffene Konnektor dort noch als „Verbunden“ geführt wird. Bei OAuth-Servern (automatisch registriert oder eigener Client) löscht MeinGPT die gespeicherten Zugangsdaten automatisch, wenn ein Token abgelaufen ist und sich nicht erneuern lässt (z. B. weil der Server kein Refresh Token ausstellt oder das Refresh selbst fehlschlägt) – der Konnektor steht dann wieder auf „Nicht verbunden“, und ein Klick auf Verbinden meldet Dich neu an. Fehlt dem angeforderten Scope das für Refresh Tokens nötige Element (häufig offline_access oder ein Server-spezifisches Äquivalent), tritt dieser Fall regelmäßig ein – ergänze den Scope in der Connector-Konfiguration entsprechend. Dieser Zustand zeigt sich im Chat nicht zwingend als Fehlermeldung: Der Assistent ruft das Tool dann einfach nicht mehr auf und weicht stattdessen z. B. auf eine manuelle Nachfrage aus, statt die abgelaufene Verbindung sichtbar zu melden.
• Erreichbarkeit und Antwortzeit: Ist die MCP-URL von MeinGPT aus erreichbar (kein interner Hostname ohne On-Premise Connections, kein abgelaufenes TLS-Zertifikat)? MeinGPT wartet für Verbindungsaufbau und Tool-Liste insgesamt höchstens 30 Sekunden; ein langsamerer Server gilt als fehlgeschlagen.
• Umfang der Tool-Liste: Ein Server wird komplett übersprungen, wenn er mehr als 100 Tools meldet, die Tool-Liste auf mehr als 20 Seiten verteilt ist, die Tool-Definitionen größer als 1 MB sind, aus mehr als 10.000 Einzelelementen bestehen oder tiefer als 64 Ebenen verschachtelt sind. Gezählt wird jeder einzelne Wert der Definitionen – Objekte, Listen, Texte, Zahlen –, nicht nur jedes Tool: Ein Parameter mit Typ und Beschreibung ergibt mehrere Einzelelemente. Wenige, sehr ausführlich beschriebene Tools können diese Grenze daher erreichen, obwohl weder 100 Tools noch 1 MB überschritten sind. Bei der Tiefe zählen die Tool-Liste selbst und jedes Tool bereits als Ebene. Über alle aktiven Server eines Chats gilt zusätzlich eine Obergrenze von 2 MB bzw. 20.000 Einzelelementen für Tool-Definitionen; ein Server, der sie überschreiten würde, wird übersprungen. Lässt sich beim Server auswählen, welche Tools oder Szenarien er anbietet, reduziere sie auf die, die Du brauchst.
• Abgelehnte Tools: Hat ein einzelnes Tool eine Definition, die MeinGPT oder das gewählte Modell nicht verarbeiten kann (z. B. ein nicht unterstütztes Eingabeschema oder ein doppelt vorkommender Tool-Name), wird dieses Tool ausgelassen. Die übrigen Tools des Servers werden trotzdem geladen, die Warnung erscheint aber dennoch.
• Bei manuellem OAuth-Client: Stimmen Token-Endpunkt, Authentifizierung am Token-Endpunkt und Scope noch mit der Admin-Konsole des Ziel-Systems überein? Wurde die Client-Registrierung dort zwischenzeitlich widerrufen oder das Secret rotiert? Deckt der angeforderte Scope auch die Tool-Auflistung (Discovery) ab, nicht nur einzelne Tool-Aufrufe – ein zu eng gefasster Scope ist eine der häufigsten Ursachen für diese Warnung bei manuell konfigurierten Servern.

Erneutes Verbinden behebt die letzten drei Punkte nicht. Hast Du bereits neu verbunden und die Warnung bleibt, liegt die Ursache meist nicht an der Anmeldung. Wende Dich dann mit Organisationsname, dem Konnektor-Namen aus der Warnung und dem ungefähren Zeitpunkt eines Chats mit der Warnung an den Support – der genaue Fehler ist aktuell nur über die Backend-Logs einsehbar, nicht über die Nutzeroberfläche.

Lehnt ein MCP-Server eine Anfrage mit 401/403 oder einem authentifizierungsbezogenen Fehler ab, prüfe zuerst, welcher Auth-Mechanismus die Anfrage tatsächlich gesendet hat: Öffne Einstellungen → Verbindungen und schau Dir den Status des Connectors an. Steht er auf „Verbunden", ist OAuth aktiv und hat Vorrang vor einem konfigurierten statischen Authorization-Header (siehe „Priorität" oben) – setze die Autorisierung in der Connector-Konfiguration auf Keine, wenn Du stattdessen mit Deinem statischen Header authentifizieren möchtest, und verbinde anschließend erneut.

Schlägt ein Tool-Aufruf fehl, klicke im Chat auf die entsprechende Tool-Aufruf-Kachel, um sie aufzuklappen. Dort siehst Du die gesendete Anfrage (Request) sowie die Antwort bzw. Fehlermeldung Deines MCP-Servers im Klartext - das ist der schnellste Weg, um die Ursache eines fehlgeschlagenen Aufrufs zu identifizieren, ohne eigene Server-Logs durchsuchen zu müssen.

Große Tool-Ergebnisse: Kürzung und Seitenweise Nachladen

Liefert Dein MCP-Server eine sehr große JSON-Antwort (eine lange Liste von Datensätzen, ein großes Dokument o. Ä.), schickt MeinGPT nicht die komplette Antwort an das Modell. Jedes Tool-Ergebnis wird vor der Anzeige an das Modell auf ein Token-Budget gekürzt (standardmäßig 6.000 Token, etwa 24.000 Zeichen); die vollständige Antwort bleibt gespeichert, und das Modell kann den Rest selbst über das eingebaute Werkzeug expand_tool_result seitenweise nachladen. Dieses Nachladen ist unabhängig von einer eigenen Paginierung Deiner API (z. B. über offset/limit-Parameter) – wenn das Modell über expand_tool_result „Seite 2" liest, ist das nicht dasselbe wie eine zweite Seite der eigentlichen API-Ergebnisse. Werden beide Mechanismen verwechselt, führt das häufig zu falschen Gesamtzahlen oder scheinbar doppelten Datensätzen in der Antwort des Assistenten.

Außerdem entfernt MeinGPT eine kleine, feste Liste struktureller JSON-Schlüssel (z. B. _links, _expandable) aus jedem Tool-Ergebnis, bevor das Modell es sieht – bei den meisten angebundenen Systemen enthalten diese Schlüssel nur Navigationsmetadaten, keine fachlichen Daten. Legt die API Deines Servers dort jedoch tatsächliche Feldwerte ab – etwa bei einer HAL+JSON-API, bei der _links.status, _links.project, _links.type oder _links.assignee den lesbaren Namen eines Referenzfelds enthalten und nicht nur einen Link –, sind diese Werte für den Assistenten nicht sichtbar. Wirken Referenzfelder nur bei manchen Datensätzen „leer", oder behauptet der Assistent, Status/Verantwortliche/Projekt/Typ seien nicht gesetzt, obwohl Du sie in der Rohantwort der API siehst, solltest Du das prüfen: Lass Deinen MCP-Server (oder eine vorgeschaltete Projektion) diese Werte unter einem anderen Schlüsselnamen als _links zurückgeben, z. B. direkt am Datensatz (status_name, assignee_name, ...).

Um Kürzungen und Tokenverbrauch generell zu reduzieren, halte Tool-Antworten schlank: projiziere auf die Felder, die der Assistent tatsächlich braucht, statt das komplette Rohobjekt des Zielsystems zurückzugeben. Hinweise dazu findest Du unter MCP-Tools entwickeln.

Nächste Schritte

• JWT Identity Forwarding: das übergreifende Konzept hinter der signierten Nutzeridentität
• MCP Tooling bauen: eigenen MCP-Server mit FastMCP entwickeln, statt einen bestehenden anzubinden
• Verbindung zu n8n MCP: vollständiges Beispiel für einen Custom MCP Server mit OAuth