ALBERT | AI als MCP-Server verwenden

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins ALBERT | AI Agents. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

Sie können agorum core pro in Kombination mit ALBERT | AI Suite als MCP-Server einsetzen. Bei der Installation von ALBERT | AI Suite wird das Konfigurationsprojekt agorum.ai.agents.mcp automatisch mitinstalliert, das dafür notwendig ist.

Hinweis: Eine Anfrage über MCP läuft mit den Rechten des Benutzers, zu dem das verwendete Token gehört. ALBERT | AI arbeitet also auch hier im Rechtekontext dieses Benutzers, und jede Aktion ist protokollierbar.

MCP-Server-Verbindungsinformationen

Wenn Sie ALBERT | AI Agents installiert und eingerichtet haben, können Sie den agorum core pro Server auch als MCP-Server verwenden.

Sie können über folgende URL auf den MCP-Server zugreifen. Tragen Sie dazu für den Platzhalter SERVER die Adresse oder den Namen Ihres agorum core pro Servers ein.

https://<SERVER>.agorum.com/api/rest/custom/agorum.ai.agents.mcp

Welche Werkzeuge ein Client sieht

Welche KI-Werkzeuge über den MCP-Server angeboten werden, hängt an zwei Dingen: an den Rechten des Benutzers, zu dem das Token gehört, und an der Werkzeuggruppe, die für diesen Zugang eingerichtet ist.

Für externe KI-Agenten sind zwei Werkzeuggruppen vorgesehen – eine für das Arbeiten mit agorum core pro und eine für das Entwickeln darin. Beschrieben sind sie unter ALBERT | AI Agents Tools-Bibliothek.

Hinweis: Auch verschachtelte Werkzeuge eines eingebundenen fremden MCP-Servers stehen externen MCP-Clients zur Verfügung, etwa die Shell- und Playwright-Werkzeuge der ALBERT | AI Sandbox.

Hinweis: Die Werkzeugsuche hat eine Obergrenze. Wird sie erreicht, erscheint ein Eintrag im Serverprotokoll, so bleibt eine unvollständige Werkzeugliste nicht unbemerkt.

Zusätzlich benötigen Sie ein JSON Web Token (JWT) für den Benutzer, mit dem die Verbindung hergestellt werden soll. Die Benutzerberechtigungen sind relevant dafür, welche KI-Tools zur Verfügung stehen. Das JWT-Token können Sie in Ihrem agorum core pro Server erzeugen, wenn Sie im Hauptmenü Administration > Werkzeuge > JWT-Generator öffnen.

Beispielverbindung mit dem MCP Inspector

Im folgenden Beispiel wird der MCP Inspector verwendet, um zu zeigen, wie agorum core pro als MCP-Server eingesetzt werden kann. Der MCP Inspector wird als Client verwendet, um KI-Tools im agorum core MCP-Server aufzurufen.

Hinweis: Der MCP Inspector ist ein externes Entwickler-Werkzeug zum Testen und Debuggen von MCP-Servern. Es handelt sich um einen interaktiven Tester mit grafischer Oberfläche, der speziell dafür entwickelt wurde, die Funktionalität von MCP-Servern zu überprüfen. Die vorliegende Dokumentation beschreibt lediglich eigene Erfahrungen im Umgang mit dem MCP Inspector und erhebt keinen Anspruch auf Aktualität und Vollständigkeit.

Voraussetzung:

Der MCP Inspector ist eine Node.js-Anwendung. Sie müssen Node.js in einer aktuellen Version installiert haben, um den MCP Inspector zu verwenden.

Stellen Sie sicher, dass Node.js in einer aktuellen Version installiert ist. Öffnen Sie eine Konsole und geben Sie Folgendes ein:
```
node -v
```
Führen Sie in der geöffneten Konsole folgenden Befehl aus:
```
npx @modelcontextprotocol/inspector
```
Nach Ausführen des Befehls in der Konsole öffnet sich die Weboberfläche des MCP Inspector automatisch in Ihrem Browser oder Sie bekommen die entsprechende URL im Terminal angezeigt.
Der Transport Type in der Weboberfläche des MCP Inspector muss Streamable HTTP sein, nur Streamable HTTP wird für den Client-Zugriff auf den agorum core pro MCP-Server unterstützt.
Geben Sie in der Weboberfläche des MCP Inspector die URL des agorum core pro Servers an.
```
http://<SERVER>.agorum.com/api/rest/custom/agorum.ai.agents.mcp
```
Erzeugen Sie in der agorum core pro Bedienoberfläche ein JWT für Ihren Benutzer unter > Administration > Werkzeuge > JWT-Generator. Verwenden Sie einen Benutzer für den API-Aufruf, der Zugriff auf die KI-Tools hat. Die Zugriffsrechte des Benutzers sind relevant dafür, welche KI-Tools verwendet werden können.
Kopieren Sie das JWT in das Feld Bearer Token in der Weboberfläche des MCP Inspector.
Klicken Sie in der Weboberfläche des MCP Inspector Connect, um die Verbindung zu agorum core pro herzustellen.

Ergebnis: Der MCP Inspector stellt die Verbindung her. Ein Eintrag initialize erscheint in der History.
Klicken Sie im Bereich Tools auf List Tools, um die Liste der verfügbaren KI-Tools abzurufen, die von ALBERT | AI agents angeboten werden.

Ergebnis: Der MCP Inspector ruft die verfügbaren KI-Tools ab. Ein Eintrag tools/list erscheint in der History. Die Liste der Tools wird im Bereich Tools angezeigt.
Testen Sie beliebige Tools aus der Tools-Liste. Wenn Sie auf ein Tool in der Liste klicken, werden die Beschreibung und ggf. die Eingabeparameter auf der rechten Fensterseite angezeigt. Wählen Sie etwa das Tool agorum_ai_agents_library_basic_get_exif aus, geben Sie als ID die UUID eines Bildes im agorum core Server an und klicken Sie Run Tool.

Ergebnis: Die EXIF-Metadaten des Bildes werden angezeigt. Sie haben mit dem MCP Inspector den Client-Zugriff auf ein KI-Tool getestet, das über den agorum core pro MCP-Server zur Verfügung steht.

Verwenden eines ALBERT | AI KI-Tools im MCP Inspector

Bilder im externen Agent

Werkzeuge wie get_object_as_image oder die Bildschirmaufnahme legen ein Bild nur in den Verlauf von ALBERT | AI. Früher gab der MCP-Server ein solches Ergebnis unverändert weiter, sodass ein externer Agent wie Claude Code oder Codex nur einen Link als Text erhielt. Jetzt liefert der MCP-Server diese Bilder als MCP-Bildinhalt, den der Client seinem Modell als Bild zeigt. Das gilt auch für Bilder angebundener MCP-Werkzeuge, etwa Screenshots aus Playwright.

Große Bilder werden wie im Chat verkleinert: Ist ein Bild größer als 1 MB oder hat es mehr als 2000 Pixel, erzeugt ALBERT | AI ein JPG-Preview, dessen längere Kante 1920 Pixel misst. Das Preview darf höchstens 5 MB groß sein.
GIF-Anhänge kommen wie im Chat als Bild an. Ist ein GIF größer als 5 MB, erscheint statt des Bildes ein Hinweis.
Ergebnisse angebundener MCP-Werkzeuge, die kein Feld isError tragen, werden unverändert weitergegeben, sofern jeder Eintrag der Inhaltsliste einen Typ hat. Das Feld ist in MCP optional; die Playwright-Werkzeuge der Sandbox lassen es weg. Alles andere wird wie bisher als Text verpackt.

Es kommt kein Bild an

Wenn ein externer Agent trotz Bildwerkzeug kein Bild erhält, prüfen Sie Folgendes:

Der Client zeigt MCP-Bildinhalte nicht. Der MCP-Server sendet das Bild als MCP-Bildinhalt. Zeigt Ihr Client solche Inhalte nicht an oder gibt er sie nicht an das Modell weiter, sehen Sie nur den Text des Werkzeugergebnisses.
Das Plugin ALBERT | AI Agents ist veraltet. Vor der Änderung kam bei einem externen Agent nur ein Link als Text an. Aktualisieren Sie das Plugin auf die aktuellste Version.
Statt des Bildes steht ein Hinweis im Ergebnis. Das Bild konnte nicht angehängt werden, etwa weil es nicht mehr verfügbar ist, das Preview zu groß ist oder ein GIF über 5 MB liegt. Der Hinweis nennt den Grund.

Tokenerfassung bei Werkzeugaufrufen über die MCP-Schnittstelle

Sie können agorum core auch selbst als MCP-Server bereitstellen, sodass externe Anwendungen die KI-Tools von agorum core über die MCP-Schnittstelle aufrufen. Werkzeugaufrufe, die auf diesem Weg bei agorum core eingehen, werden bei der Tokenzählung berücksichtigt.

Ein über die MCP-Schnittstelle eingehender Werkzeugaufruf wird als Output-Tokens erfasst. Grundlage der Zählung sind das aufgerufene Werkzeug und die dabei übergebenen Angaben (also der Name des Werkzeugs und seine Parameter). Das Ergebnis des Werkzeugaufrufs fließt nicht in die Zählung ein. Bisher blieben solche Aufrufe bei reiner MCP-Nutzung ohne Auswirkung auf die Tokenzählung.
Der auf diese Weise entstandene Anteil wird zusätzlich in einem eigenen Zähler erfasst. Dieser Zähler dient ausschließlich als Grundlage für die Nutzungsmeldung und fließt nicht in Ihre Lizenzabrechnung ein.
Ist für das Nutzungsprotokoll ein KI-Handler global hinterlegt und aktiv (siehe Usage Protocol/Nutzungsstatistiken protokollieren), wird dieser Anteil zusätzlich als eigene Nutzungsaufzeichnung an die dort hinterlegten Endpunkte gemeldet – bei mehreren Endpunkten an alle. Der Handler selbst bleibt dabei unverändert.
Werkzeugaufrufe aus dem ALBERT-Chat und aus Agenten sind hiervon nicht betroffen: Dort werden die Output-Tokens weiterhin unverändert über die KI-Antwort gezählt. Eine doppelte Zählung findet nicht statt.