IntraChat als MCP-Client

Diese Seite beschreibt, wie sich IntraChat, die Plattform von Intra AI, mit einem MCP-Server verbindet, den ein Anbieter selbst betreibt. Sie richtet sich an zwei Lesergruppen: an die Prüferinnen und Prüfer eines Anbieters, die entscheiden, ob IntraChat als OAuth-Client ihres MCP-Servers zugelassen wird, und an die IT-Abteilungen unserer Kunden, die wissen wollen, was beim Verbinden eines Kontos passiert.

Was IntraChat ist#

IntraChat ist der KI-Arbeitsbereich, den Intra AI für ein Kundenunternehmen einrichtet. Jeder Kunde bekommt eine dedizierte Instanz, von uns betrieben: Anwendung, Datenbanken und Speicher werden nicht mit anderen Kunden geteilt. Auf Wunsch läuft die Instanz stattdessen in der eigenen Infrastruktur des Kunden. Entwicklung, Datenhaltung und KI-Inferenz in Deutschland.

Personen, ihre Verbindungen und ihre Tokens gehören zu genau einer Instanz und werden nie mit der Instanz eines anderen Kunden geteilt.

Die Verbindung im Überblick#

Diese Seite beschreibt Clients, die zu einer Instanz gehören: einen Client, den die Instanz selbst registriert, oder einen, den die Administration beim Anbieter anlegt und einträgt.

<slug> wird aus dem Namen des Servers gebildet: in Kleinbuchstaben, Leerzeichen durch Bindestriche ersetzt, jedes Zeichen außer a–z, 0–9 und dem Bindestrich entfernt, mehrere Bindestriche hintereinander zu einem zusammengefasst und Bindestriche am Anfang und Ende entfernt. Ein Server namens Notion bekommt notion, ein Server namens monday.com bekommt mondaycom.

Metadaten ermitteln#

Wird der Server auf einer Instanz eingerichtet, schickt IntraChat eine MCP-Anfrage initialize ohne Token an die Adresse des Servers und liest den Link resource_metadata aus der WWW-Authenticate-Challenge der 401-Antwort (RFC 9728). Fehlt der Link, versucht es /.well-known/oauth-protected-resource mit dem Pfad des Servers, danach ohne.

Die Protected Resource Metadata nennen den Autorisierungsserver. IntraChat liest dessen Metadaten nach RFC 8414, ersatzweise seine OpenID-Connect-Konfiguration, und weist ein Dokument zurück, dessen issuer nicht der genannte Autorisierungsserver ist. Ebenso weist es Protected Resource Metadata zurück, die eine andere Adresse beschreiben als den Server, der gerade eingerichtet wird. Nur wenn es gar keine Protected Resource Metadata gibt, liest es /.well-known/oauth-authorization-server am Ursprung des Servers selbst.

Jeder Endpunkt aus diesen Metadaten muss eine http- oder https-Adresse sein, die nicht auf eine private, Loopback- oder Link-Local-Adresse zeigt. Veröffentlicht ein Anbieter keine Metadaten, sind die Endpunkte stattdessen in der Einrichtung von IntraChat für diesen Anbieter festgelegt.

Nennen die Protected Resource Metadata eine resource, schickt IntraChat sie als Parameter resource nach RFC 8707 mit der Autorisierungsanfrage, dem Code-Tausch und jeder Erneuerung.

Client-Registrierung#

Bietet der Autorisierungsserver einen registration_endpoint an, registriert IntraChat dort einen Client (RFC 7591), mit der Redirect-URI der Instanz, den Grant Types authorization_code und refresh_token, dem Response Type code und den Scopes, die es anfragen wird. Es registriert einen vertraulichen Client mit client_secret_post. Einen öffentlichen Client (none) registriert es nur, wenn der Server none und keine der beiden Secret-Methoden nennt, und nur, wenn der Server S256 in code_challenge_methods_supported aufführt.

Bietet der Server keine Registrierung an, legt die Administration beim Anbieter einen OAuth-Client an, trägt dort die Redirect-URI aus der Einrichtungsanleitung ein und überträgt Client-ID und Secret in IntraChat. Ein solcher Client meldet sich am Token-Endpunkt mit client_secret_post an, wenn der Server diese Methode oder gar keine nennt, sonst mit client_secret_basic.

Einen Client, den die Instanz selbst registriert, registriert sie einmal, speichert ihn und verwendet ihn für jede Person dieser Instanz wieder. Ein eingetragener Client wird genauso gespeichert. IntraChat registriert keinen neuen Client pro Person oder pro Sitzung.

Redirect-URI#

Für einen Client, den die Instanz selbst registriert oder den die Administration einträgt, setzt sich die Redirect-URI aus dem Hostnamen der Instanz und dem Slug des Servers zusammen:

https://<instance-host>/api/v1/integrations/mcp-oauth/<slug>/callback

Bei einem eingetragenen Client ist das die Adresse, die beim Anbieter erlaubt werden muss. Bei der Dynamic Client Registration schickt IntraChat sie in der Registrierungsanfrage mit. Antwortet eine Instanz unter mehreren Hostnamen, funktioniert die Anmeldung unter dem, mit dem sie registriert wurde.

Zustimmung pro Person#

Niemand verbindet ein Konto im Namen einer anderen Person. Jede Person meldet sich beim Anbieter mit ihrem eigenen Konto an und erteilt dort den angefragten Zugriff:

1. Die Person öffnet unter Integrationen in IntraChat die Kachel des Anbieters und fügt eine Verbindung hinzu. Das geht erst, wenn die Integration freigegeben ist, und nur für die Personen, für die sie freigegeben ist. Ist sie freigegeben, auch nur für eine Testgruppe, können sich Administratoren mit globalen Adminrechten zum Testen ebenfalls verbinden.
2. IntraChat erzeugt einen zufälligen state und einen zufälligen PKCE Code Verifier und leitet den Browser zum Autorisierungsendpunkt des Anbieters, mit response_type=code, der Client-ID, der Redirect-URI, den Scopes, code_challenge und code_challenge_method=S256.
3. Der Anbieter leitet den Browser zur Redirect-URI zurück. IntraChat akzeptiert den state nur einmal und nur in dem Browser, der die Anmeldung begonnen hat, und tauscht den Code dann zusammen mit dem Code Verifier am Token-Endpunkt ein.

IntraChat fragt die Scopes an, die seine Einrichtung für diesen Anbieter festlegt, oder, wo sie keine festlegt, die Scopes, die der Server in seinen Metadaten nennt.

Nach dem Tausch versucht IntraChat herauszufinden, zu welchem Konto das Token gehört, damit die Verbindung danach benannt werden kann. Es fragt den Autorisierungsserver per Token Introspection nach RFC 7662 oder über den Userinfo-Endpunkt von OpenID Connect, und zwar am Ursprung des Token-Endpunkts oder an einem Userinfo-Endpunkt, den die Einrichtung von IntraChat für diesen Anbieter festlegt. Bei manchen Anbietern ruft es außerdem mit dem neuen Token der Person ein lesendes Werkzeug des Servers selbst oder die Konto-API des Anbieters auf, um das Konto zu benennen. Antwortet keine dieser Stellen, trägt die Verbindung den Namen des Servers.

Das Verbinden schreibt das Ereignis integration.mcp_oauth.connected in das Audit-Log der Instanz.

Tokens#

• Speicherung: Access Token, Refresh Token und Ablaufzeit liegen pro Person in der Datenbank der Instanz, verschlüsselt mit einem Datenschlüssel, der zu dieser Person gehört. Ein Client Secret liegt im Datensatz des Servers, verschlüsselt mit dem Systemschlüssel der Instanz.
• Verwendung: Jeder Werkzeugaufruf trägt das eigene Access Token der aufrufenden Person als Bearer-Token, nie das einer anderen Person.
• Erneuerung: Liefert der Anbieter expires_in, erneuert IntraChat ein Token, das in weniger als 60 Sekunden abläuft, vor dem Aufruf. Antwortet der Server auf einen Aufruf mit 401, erneuert IntraChat einmal und wiederholt den Aufruf einmal.
• Rotation: Erneuerungen für eine Person und einen Server laufen über alle API-Prozesse der Instanz nacheinander, sodass ein rotierendes Refresh Token nur einmal eingelöst wird. Ein rotiertes Refresh Token wird vor dem neuen Access Token gespeichert.
• Ungültiger Grant: Beantwortet der Token-Endpunkt eine Erneuerung mit invalid_grant, löscht IntraChat die gespeicherten Tokens dieser Person, und sie muss sich neu verbinden. Bei jedem anderen Fehler, etwa einer Zeitüberschreitung oder einer 5xx-Antwort, bleiben die gespeicherten Tokens erhalten.
• Neu verbinden: Eine neue Verbindung ersetzt die bisherigen Tokens der Person vollständig.

Trennen und Widerruf#

Eine Person trennt die Verbindung auf der Kachel des Anbieters unter Integrationen. IntraChat löscht dann die gespeicherten Tokens dieser Person für den Server und schreibt das Ereignis integration.mcp_oauth.revoked in das Audit-Log.

IntraChat ruft den Widerrufsendpunkt des Anbieters (RFC 7009) nicht auf. Der Grant beim Anbieter besteht weiter, bis er abläuft oder die Person die App in ihren Kontoeinstellungen beim Anbieter entfernt.

Entfernt die Administration einen Server, der einen solchen Client nutzt, löscht IntraChat den Server und die gespeicherten Verbindungen aller Personen zu ihm.

Werkzeuge#

IntraChat fragt die Werkzeuge eines Servers mit tools/list ab, gesendet mit dem Token einer verbundenen Person. Bis sich die erste Person verbunden hat, schickt IntraChat keine Anfrage mit Token an den Server und listet keine Werkzeuge. Die Werkzeugliste einer Person gilt für alle Personen der Instanz; ein Werkzeug, das der Tarif einer anderen Person nicht enthält, lehnt der Anbieter ab, wenn diese Person es aufruft.

In IntraChat heißt ein Werkzeug mcp__<slug>__<tool>, zum Beispiel mcp__notion__notion-search.

Welche Werkzeuge ein Agent nutzen darf, wird pro Agent festgelegt: Jeder Agent bekommt pro Server eine Liste von Werkzeugen. Jedes freigegebene Werkzeug können die Einstellungen des Agenten als lesend, als bestätigungspflichtig oder als ohne Nachfrage ausführbar kennzeichnen. Die Kennzeichnung als lesend ist nur eine Bezeichnung und schränkt nichts ein; die Einstellungen für Bestätigung und für Ausführung ohne Nachfrage ändern, wie ein Aufruf abläuft.

• Bestätigung: Ein Werkzeug mit Bestätigung hält die Unterhaltung vor dem Aufruf an und zeigt der Person eine Karte mit dem, was der Agent tun will. Der Aufruf geht erst an den Anbieter, wenn die Person ihn bestätigt. Werkzeuge im Chat beschreibt die Karte.
• Annotationen: Standardmäßig entfernt IntraChat die Werkzeug-Annotationen wie destructiveHint, die der Server eines Anbieters veröffentlicht. Ob ein Aufruf eine Bestätigung braucht, entscheiden die Einstellungen des Agenten, nicht der Server.
• Ohne Nachfrage: Wer einen Agenten baut, kann ein schreibendes Werkzeug ohne Nachfrage laufen lassen. Die Instanz kann das für einzelne Werkzeuge oder ganz verbieten.

Werkzeugergebnisse verarbeitet das Sprachmodell, mit dem die Instanz eingerichtet ist. In unserer Standardkonfiguration betreiben wir offene Modelle, gehostet in Deutschland.

Für die Administration: eine gehostete Integration einrichten#

MCP-Server von Anbietern, für die IntraChat eine Einrichtung mitbringt, stehen im Adminbereich unter Integrationen. Jeder hat eine Schritt-für-Schritt-Anleitung:

1. Schritte beim Anbieter. Bei einem Server mit Dynamic Client Registration gibt es meist keine. Bei einem eingetragenen Client nennt die Anleitung, was du beim Anbieter anlegst, die Scopes mit je einer Begründung und die Redirect-URI, die du dort einträgst.
2. Werte. Mit Dynamic Client Registration registriert sich IntraChat selbst, und du trägst nichts ein. Sonst fügst du Client-ID und Secret ein. Das Speichern registriert den Server auf der Instanz.
3. Freigeben. Mit einer registrierten Integration kann sich noch niemand verbinden, auch die Administration nicht. Gib sie für eine Testgruppe oder für alle frei.

Nach der Freigabe verbindet jede Person ihr eigenes Konto, wie in Integrationen verbinden beschrieben.

Testzugang für die Prüfung durch Anbieter#

Ein Testzugang für die Prüfung durch Anbieter ist auf Anfrage möglich. Schreib an info@intra-ai.de oder nutze das Kontaktformular und nenne den MCP-Server, um den es bei deiner Prüfung geht.