docs: add Model Context Protocol (MCP) add-on page (EN + DE)

docs/de/admin/mcp.md

@@ -0,0 +1,149 @@
+# Model Context Protocol (MCP)
+
+Das **MCP-Add-on** ermöglicht einem KI-Client wie Claude, Ihre i-doit-up-CMDB über das [Model Context Protocol](https://modelcontextprotocol.io) zu lesen und zu bearbeiten, den offenen Standard für die Anbindung von KI-Clients an externe Daten.
+Sobald die Verbindung besteht, kann der Client Objekte suchen, Kategorien und Klassen einsehen und, sofern der Schreibzugriff aktiviert ist, CMDB-Inhalte in Ihrem Namen anlegen und aktualisieren.
+Das Add-on läuft als eigener Dienst neben i-doit up und wird über Ihre i-doit-up-URL und ein App-Token angesprochen, sodass jeder Aufruf als echter i-doit-up-Benutzer authentifiziert ist.
+
+Diese Seite beschreibt die In-Produkt-Seite des Add-ons: wo Sie es finden, wie Sie das App-Token erstellen, wie Sie einen KI-Client verbinden, was der Client darf und wie Sie das Zugriffsprotokoll lesen.
+
+## Was das MCP-Add-on leistet
+
+MCP ist ein offener Standard, über den KI-Clients einheitlich mit externen Werkzeugen und Datenquellen sprechen.
+Das i-doit-up-MCP-Add-on implementiert die Serverseite dieses Standards für Ihre CMDB, sodass ein MCP-fähiger Client folgendes kann:
+
+- **Suchen und Lesen** von Objekten, Objektkategorien, Klassen, Dialog-Werten und Berichten.
+- **Anlegen und Aktualisieren** von Objekten, Kategorieeinträgen, Klassen und Dialog-Werten, sofern der Schreibzugriff für den Mandanten aktiviert ist.
+
+Der Client hält nie eine Datenbankverbindung.
+Jede Anfrage läuft über die i-doit-up-API mit dem App-Token, das Sie hinterlegen, sodass der Client genau die Daten sieht und genau die Rechte des Benutzers beachtet, dem das Token gehört.
+
+## Wo Sie die Seite finden
+
+Öffnen Sie das [Benutzermenü](../user/basics/user-menu.md) (Avatar oben rechts) und wählen Sie **Einstellungen**.
+Am unteren Ende der linken Seitenleiste, unterhalb von *Administration*, finden Sie die Gruppe **MCP** mit zwei Einträgen:
+
+- **How to connect**, der Einrichtungsassistent.
+- **Logs**, das Zugriffsprotokoll.
+
+Die Gruppe **MCP** wird vom Add-on beigesteuert und erscheint erst, wenn das Add-on für Ihre Instanz installiert ist.
+Der Eintrag **Logs** wird nur Benutzern angezeigt, die das Recht *MCP Logs access* besitzen, siehe [das Zugriffsprotokoll](#das-zugriffsprotokoll) weiter unten.
+
+## App-Token erstellen
+
+Der Client authentifiziert sich mit einem i-doit-up-**App-Token**.
+Ein Token gehört zu einem Benutzer und trägt dessen Rechte, legen Sie es also auf dem Konto an, als das der KI-Client handeln soll.
+
+1. Gehen Sie zu **Einstellungen → Benutzer** und öffnen Sie den Benutzer, als der der Client handeln soll.
+2. Wechseln Sie auf den Reiter **Apps** und klicken Sie auf **Add app**.
+3. Vergeben Sie einen Namen (zum Beispiel *Claude MCP*) und speichern Sie.
+4. Kopieren Sie das Token aus dem Dialog.
+
+Das Token wird **nur einmal** angezeigt.
+Wenn Sie es verlieren, löschen Sie die App und legen Sie eine neue an, um ein frisches Token zu erhalten.
+
+Das Token läuft nicht von selbst ab.
+Um einen verbundenen Client später zu widerrufen, löschen Sie seine App im Reiter **Apps** und bestätigen Sie *Delete Application*, das Token wird dann innerhalb weniger Minuten ungültig.
+Da das Token die Rechte des Benutzers trägt, verwenden Sie besser einen dedizierten Benutzer mit nur den nötigen Rechten statt eines Administratorkontos.
+
+## KI-Client verbinden
+
+Der Reiter **How to connect** baut Ihnen ein fertiges Verbindungssetup zum Einfügen.
+Sie müssen URL und Header nicht von Hand zusammensetzen.
+
+![Der Reiter How to connect in i-doit up. Schritt 1 wählt die Verbindungsmethode "Authorization header, Streamable HTTP (recommended)", Schritt 2 enthält ein Feld für das App-Token, und Schritt 3 zeigt den generierten Terminal-Befehl "claude mcp add" sowie einen gleichwertigen .mcp.json-Konfigurationsblock, beide bereits mit der MCP-Server-URL und der i-doit-up-Mandanten-URL vorausgefüllt.](../img/admin/mcp-how-to-connect.png)
+
+1. Belassen Sie in **Schritt 1** die Verbindungsmethode auf *Authorization header, Streamable HTTP (recommended)*.
+    Streamable HTTP ist der aktuelle Transport.
+    Das Dropdown bietet außerdem eine ältere SSE-Methode, siehe [Verbindungsmethoden](#verbindungsmethoden) weiter unten.
+2. Fügen Sie in **Schritt 2** das [App-Token](#app-token-erstellen) ein, das Sie erstellt haben.
+    Das Token wird nur zum Bauen des Befehls verwendet und von der Seite nicht gespeichert.
+3. Kopieren Sie in **Schritt 3** entweder den einzeiligen Terminal-Befehl für Claude Code oder den gleichwertigen Konfigurationsblock für eine `.mcp.json`-Datei oder Claude Desktop.
+
+Der generierte Befehl enthält bereits Ihre MCP-Server-URL und Ihre i-doit-up-URL.
+Die i-doit-up-URL wird im Header `X-Idoit-Url` gesendet und identifiziert Ihren Mandanten, das App-Token wird als `Bearer`-Token gesendet:
+
+```bash
+claude mcp add --transport http idoit https://mcp.example.com/mcp \
+    --header "Authorization: Bearer YOUR_APP_TOKEN" \
+    --header "X-Idoit-Url: https://your-instance.example.com"
+```
+
+```json
+{
+    "mcpServers": {
+        "idoit": {
+            "type": "http",
+            "url": "https://mcp.example.com/mcp",
+            "headers": {
+                "Authorization": "Bearer YOUR_APP_TOKEN",
+                "X-Idoit-Url": "https://your-instance.example.com"
+            }
+        }
+    }
+}
+```
+
+### Verbindungsmethoden
+
+Schritt 1 bietet zwei Methoden.
+Welche Sie auch wählen, **Schritt 3** passt Befehl und Konfiguration entsprechend an, der kopierte Block ist also immer korrekt.
+
+| Methode | Transport | Endpunkt | Zugangsdaten |
+|---|---|---|---|
+| **Authorization header, Streamable HTTP** (empfohlen) | Streamable HTTP | `/mcp` | Header `Authorization: Bearer <Token>` und `X-Idoit-Url` |
+| **Authorization header, SSE** | SSE (Legacy) | `/mcp/sse` | dieselben beiden Header |
+
+Die beiden Methoden unterscheiden sich nur im Transport.
+Streamable HTTP ist der aktuelle MCP-Transport.
+SSE ist der ältere Transport, beibehalten für Clients, die Streamable HTTP noch nicht beherrschen.
+Beide erreichen dieselben Tools und senden das App-Token sowie die Mandanten-URL als Request-Header, nie in der URL.
+
+Fügen Sie den Block in Ihren Client ein, starten Sie ihn neu und bitten Sie den Client um eine Leseaktion, etwa das Auflisten der Klassen.
+Der Aufruf erscheint dann innerhalb weniger Sekunden im [Zugriffsprotokoll](#das-zugriffsprotokoll).
+
+## Was der KI-Client darf
+
+Standardmäßig kann der Client Ihre CMDB lesen und, sofern der Schreibzugriff aktiviert ist, verändern.
+
+- **Lese**-Aktionen suchen und sichten Objekte, Objektkategorien, Klassen, Dialog-Werte und Berichte.
+- **Schreib**-Aktionen legen CMDB-Inhalte wie Objekte, Kategorieeinträge, Klassen und Dialog-Werte an, aktualisieren, duplizieren und löschen sie.
+
+Der Schreibzugriff ist eine Einstellung pro Mandant und in der aktuellen Version standardmäßig aktiviert.
+Diese Einstellung ist in der aktuellen Version noch nicht in der Oberfläche verfügbar; damit ein Client nur liest, geben Sie seinem Token einen Benutzer, dessen Rechte keine Änderungen erlauben.
+Jeder Schreibvorgang wird vor der Ausführung im Zugriffsprotokoll festgehalten, sodass Sie stets nachvollziehen können, was der Client geändert hat.
+Da der Client als der Benutzer des Tokens handelt, erreicht er nur Daten, die dieser Benutzer sehen darf, und ändert nur, was dieser Benutzer ändern darf, siehe [Rechte und Berechtigungen](rights-and-permissions.md).
+
+## Das Zugriffsprotokoll
+
+Der Reiter **Logs** zeichnet jeden Tool-Aufruf auf, den die verbundenen Clients gegen Ihren Mandanten machen.
+
+![Das MCP-Zugriffsprotokoll in i-doit up. Eine Überschrift "Access Log" mit der Zeile "4 total events recorded" und den Buttons Refresh und Clear Log, darüber eine Tabelle mit den Spalten Timestamp, Type, Name, User, Parameters und Summary. Vier Zeilen zeigen Tool-Aufrufe: list_reports, search_objects, list_categories und list_classes, jeweils mit dem aufrufenden Benutzer und einer kurzen Ergebniszusammenfassung wie "Returned 89 classes".](../img/admin/mcp-access-log.png)
+
+Jede Zeile zeigt:
+
+| Spalte | Anmerkungen |
+|---|---|
+| **Timestamp** | Wann der Aufruf erfolgte. |
+| **Type** | Die Art des Aufrufs, zum Beispiel *tool* für einen Tool-Aufruf. |
+| **Name** | Das ausgeführte Tool, zum Beispiel `list_classes` oder `search_objects`. |
+| **User** | Der i-doit-up-Benutzer, dessen App-Token verwendet wurde. Das Token selbst wird nie angezeigt. |
+| **Parameters** | Die Argumente, die der Client übergeben hat, zum Beispiel `{"query":"server"}`. |
+| **Summary** | Ein kurzes Ergebnis, zum Beispiel *Returned 89 classes*. |
+
+Die Liste aktualisiert sich nicht von selbst, klicken Sie auf **Refresh**, um sie neu zu laden.
+Das Protokoll bezieht sich auf den aktiven Mandanten, jede i-doit-up-URL hat also ihr eigenes Protokoll, siehe [Mandanten](tenants.md).
+
+**Clear Log** entfernt alle Einträge des Mandanten.
+
+Der Reiter **Logs** ist durch ein Add-on-Recht geschützt, das nicht automatisch vergeben wird, auch nicht an Administratoren, der Eintrag bleibt also verborgen, bis Sie das Recht vergeben.
+Öffnen Sie dazu **Einstellungen → Rechte**, wählen Sie *Add-on rights → MCP* und klicken Sie auf **Neues Recht**.
+Wählen Sie den Benutzer, die Rolle oder die Gruppe, aktivieren Sie **MCP Logs access** (ergänzen Sie **Clear MCP Logs**, um auch das Leeren zu erlauben) und speichern Sie.
+Siehe [Rechte und Berechtigungen](rights-and-permissions.md).
+
+## Siehe auch
+
+- [Add-ons](addons.md): Der MCP-Server wird als Add-on ausgeliefert und mit Ihrer i-doit-up-Instanz registriert.
+- [Rechte und Berechtigungen](rights-and-permissions.md): regeln, wer das Zugriffsprotokoll öffnen und leeren darf.
+- [Mandanten](tenants.md): jede i-doit-up-URL ist ein eigener MCP-Mandant mit eigenem Zugriffsprotokoll.
+- [Benutzerverwaltung](user-management.md): hier wird das App-Token auf einem Benutzerkonto erstellt.
+- [Model Context Protocol](https://modelcontextprotocol.io): der offene Standard, den das Add-on implementiert.

docs/en/admin/mcp.md

@@ -0,0 +1,149 @@
+# Model Context Protocol (MCP)
+
+The **MCP add-on** lets an AI client such as Claude read and work with your i-doit up CMDB over the [Model Context Protocol](https://modelcontextprotocol.io), the open standard for connecting AI clients to external data.
+Once it is connected, the client can search objects, inspect categories and classes, and, when write access is enabled, create and update CMDB content on your behalf.
+The add-on runs as a separate service alongside i-doit up and is reached through your own i-doit up URL and an app token, so every call is authenticated as a real i-doit up user.
+
+This page describes the in-product side of the add-on: where to find it, how to create the app token, how to connect an AI client, what the client may do, and how to read the access log.
+
+## What the MCP add-on does
+
+MCP is an open standard that lets AI clients talk to external tools and data sources in a uniform way.
+The i-doit up MCP add-on implements the server side of that standard for your CMDB, so an MCP-capable client can:
+
+- **Search and read** objects, object categories, classes, dialog values, and reports.
+- **Create and update** objects, category entries, classes, and dialog values, when write access is enabled for the tenant.
+
+The client never holds a database connection.
+Every request goes through the i-doit up API with the app token you provide, so the client sees exactly the data and respects exactly the rights of the user that owns the token.
+
+## Where to find it
+
+Open the [user menu](../user/basics/user-menu.md) (avatar at the top-right) and choose **Settings**.
+At the bottom of the left sidebar, below *Administration*, sits the **MCP** group with two entries:
+
+- **How to connect**, the setup wizard.
+- **Logs**, the access log.
+
+The **MCP** group is contributed by the add-on and only appears once the add-on is installed for your instance.
+The **Logs** entry is shown only to users who hold the *MCP Logs access* right, see [the access log](#the-access-log) below.
+
+## Create an app token
+
+The client authenticates with an i-doit up **app token**.
+A token belongs to one user and carries that user's rights, so create it on the account the AI client should act as.
+
+1. Go to **Settings → Users** and open the user you want the client to act as.
+2. Switch to the **Apps** tab and click **Add app**.
+3. Give the app a name (for example *Claude MCP*) and save.
+4. Copy the token from the dialog.
+
+The token is shown **only once**.
+If you lose it, delete the app and create a new one to get a fresh token.
+
+The token does not expire on its own.
+To revoke a connected client later, delete its app on the **Apps** tab and confirm *Delete Application*, the token then stops working within a few minutes.
+Because the token carries the user's rights, prefer a dedicated user with only the rights the client needs over an administrator account.
+
+## Connect your AI client
+
+The **How to connect** tab builds a ready-to-paste connection setup for you.
+You do not have to assemble the URL or headers by hand.
+
+![The How to connect tab in i-doit up. Step 1 selects the connection method "Authorization header, Streamable HTTP (recommended)", step 2 has a field for the app token, and step 3 shows the generated "claude mcp add" terminal command and an equivalent .mcp.json config block, both pre-filled with the MCP server URL and the i-doit up tenant URL.](../img/admin/mcp-how-to-connect.png)
+
+1. In **Step 1**, leave the connection method on *Authorization header, Streamable HTTP (recommended)*.
+    Streamable HTTP is the current transport.
+    The dropdown also offers a legacy SSE method, see [Connection methods](#connection-methods) below.
+2. In **Step 2**, paste the [app token](#create-an-app-token) you created.
+    The token is only used to build the command and is never stored by the page.
+3. In **Step 3**, copy either the one-line terminal command for Claude Code or the equivalent configuration block for a `.mcp.json` file or Claude Desktop.
+
+The generated command already contains your MCP server URL and your i-doit up URL.
+The i-doit up URL is sent in the `X-Idoit-Url` header and identifies your tenant, and the app token is sent as a `Bearer` token:
+
+```bash
+claude mcp add --transport http idoit https://mcp.example.com/mcp \
+    --header "Authorization: Bearer YOUR_APP_TOKEN" \
+    --header "X-Idoit-Url: https://your-instance.example.com"
+```
+
+```json
+{
+    "mcpServers": {
+        "idoit": {
+            "type": "http",
+            "url": "https://mcp.example.com/mcp",
+            "headers": {
+                "Authorization": "Bearer YOUR_APP_TOKEN",
+                "X-Idoit-Url": "https://your-instance.example.com"
+            }
+        }
+    }
+}
+```
+
+### Connection methods
+
+Step 1 offers two methods.
+Whichever you pick, **Step 3** rewrites the command and the config to match, so the snippet you copy is always correct.
+
+| Method | Transport | Endpoint | Credentials |
+|---|---|---|---|
+| **Authorization header, Streamable HTTP** (recommended) | Streamable HTTP | `/mcp` | `Authorization: Bearer <token>` and `X-Idoit-Url` headers |
+| **Authorization header, SSE** | SSE (legacy) | `/mcp/sse` | the same two headers |
+
+The two methods differ only in the transport.
+Streamable HTTP is the current MCP transport.
+SSE is the older transport, kept for clients that do not yet speak Streamable HTTP.
+Both reach the same tools, and both send the app token and the tenant URL as request headers, never in the URL.
+
+Paste the block into your client, restart it, and ask the client to run a read action such as listing classes.
+The call then appears in [the access log](#the-access-log) within a few seconds.
+
+## What the AI client can do
+
+By default the client can read your CMDB and, when write access is enabled, change it.
+
+- **Read** actions search and inspect objects, object categories, classes, dialog values, and reports.
+- **Write** actions create, update, duplicate, and delete CMDB content such as objects, category entries, classes, and dialog values.
+
+Write access is a per-tenant setting and is enabled by default in the current release.
+This setting is not yet exposed in the user interface, so to keep a client read-only, give its token a user whose rights do not permit changes.
+Every write is recorded in the access log before it runs, so you always have a trail of what the client changed.
+Because the client acts as the token's user, it can only reach data that user is allowed to see and can only change what that user is allowed to change, see [Rights and permissions](rights-and-permissions.md).
+
+## The access log
+
+The **Logs** tab records every tool call the connected clients make against your tenant.
+
+![The MCP access log in i-doit up. A heading "Access Log" with a "4 total events recorded" line and Refresh and Clear Log buttons, above a table whose columns are Timestamp, Type, Name, User, Parameters, and Summary. Four rows show tool calls: list_reports, search_objects, list_categories, and list_classes, each with the calling user and a short result summary such as "Returned 89 classes".](../img/admin/mcp-access-log.png)
+
+Each row shows:
+
+| Column | Notes |
+|---|---|
+| **Timestamp** | When the call was made. |
+| **Type** | The kind of call, for example *tool* for a tool call. |
+| **Name** | The tool that ran, for example `list_classes` or `search_objects`. |
+| **User** | The i-doit up user whose app token was used. The token itself is never shown. |
+| **Parameters** | The arguments the client passed, for example `{"query":"server"}`. |
+| **Summary** | A short result, for example *Returned 89 classes*. |
+
+The log does not refresh on its own, so click **Refresh** to reload it.
+The log is scoped to the active tenant, so each i-doit up URL has its own log, see [Tenants](tenants.md).
+
+**Clear Log** removes all entries for the tenant.
+
+The **Logs** tab is gated by an add-on right that is not granted automatically, not even to administrators, so the entry stays hidden until you grant it.
+To grant it, open **Settings → Rights**, choose *Add-on rights → MCP*, and click **New right**.
+Select the user, role, or group, check **MCP Logs access** (add **Clear MCP Logs** to also allow clearing the log), and save.
+See [Rights and permissions](rights-and-permissions.md).
+
+## Further readings
+
+- [Add-ons](addons.md), the MCP server is an add-on registered with your i-doit up instance.
+- [Rights and permissions](rights-and-permissions.md), control who can open the access log and clear it.
+- [Tenants](tenants.md), each i-doit up URL is a separate MCP tenant with its own access log.
+- [User management](user-management.md), where the app token is created on a user account.
+- [Model Context Protocol](https://modelcontextprotocol.io), the open standard the add-on implements.

i18n/de/mkdocs.yml

@@ -95,6 +95,7 @@ nav:
       - Integrationen:
           - Suite+ Bridge: admin/suite-plus.md
           - servereye Integration: admin/servereye.md
+          - Model Context Protocol (MCP): admin/mcp.md
   - Entwicklerhandbuch:
       - API: dev/api.md
       - Add-ons:

i18n/de/spelling.txt

@@ -241,3 +241,6 @@ Tournamen
 Validierungsfehler
 Verlaufsansicht
 WSL
+MCP
+mcp
+claude

i18n/en/mkdocs.yml

@@ -95,6 +95,7 @@ nav:
       - Integrations:
           - Suite+ bridge: admin/suite-plus.md
           - servereye integration: admin/servereye.md
+          - Model Context Protocol (MCP): admin/mcp.md
   - Developer guide:
       - API: dev/api.md
       - Add-ons:

i18n/en/spelling.txt

@@ -115,3 +115,6 @@ von
 VSCode
 YAML
 Accounty
+MCP
+mcp
+Streamable