> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/de/dev-reference/mcp-server.md).

# MCP-Server

RealmJoin MCP-Server: Endpunkt, MCP-Zugriffstoken, Clientkonfiguration, die schreibgeschützten Tools für den Gerätezustand und Softwaredaten, Ratenbegrenzung und Sicherheit.

RealmJoin betreibt einen [Model Context Protocol](https://modelcontextprotocol.io/) (MCP)-Server als Teil der RealmJoin Customer-API. MCP-Clients, zum Beispiel KI-Assistenten und IDE-Agenten, verbinden sich mit ihm mit einem MCP-Zugriffstoken und rufen seine Tools auf, um den Gerätezustand und die Softwaredaten Ihres Tenant zu lesen.

Alle Tools sind schreibgeschützt. Der MCP-Server kann Geräte, Pakete, Zuweisungen oder Einstellungen nicht ändern.

## Voraussetzungen

* Der MCP-Server ist für Ihren Tenant aktiviert. Die Funktion wird von RealmJoin aktiviert; wenden Sie sich an den RealmJoin-Support, um sie aktivieren zu lassen.
* Das Erstellen und Widerrufen von Tokens erfordert eine Administratorrolle im RealmJoin Portal: die RealmJoin **Admin** Rolle oder die Entra ID **Global Administrator** Rolle (Portalrichtlinie `CanAdministerOwnTenant`; sie kann nicht gewährt werden über [Benutzerdefinierte Rollen](https://docs.realmjoin.com/de/administration-and-einstellungen/permission/custom-roles.md)). Die **MCP-Zugriff** Registerkarte wird nur mit dieser Rolle und solange die Funktion aktiviert ist angezeigt.
* Ein MCP-Client, der den Streamable-HTTP-Transport unterstützt und einen benutzerdefinierten `Authorization` Header senden kann. Der MCP-Server bietet keine OAuth-Anmeldung an, daher können Clients, die sich nur über OAuth mit entfernten Servern verbinden, ihn nicht verwenden.

## Endpunkt und Authentifizierung

| Eigenschaft       | Wert                                     |
| ----------------- | ---------------------------------------- |
| URL               | `https://customer-api.realmjoin.com/mcp` |
| Transport         | Streamable HTTP                          |
| Authentifizierung | `Authorization: Bearer <MCP token>`      |
| Servername        | `realmjoin`                              |

Der Endpunkt akzeptiert nur MCP-Zugriffstokens. Der Benutzername und das Secret, die für die [RealmJoin API](https://docs.realmjoin.com/de/dev-reference/realmjoin-api/authentication.md) (HTTP Basic) verwendet werden, werden hier nicht akzeptiert.

Jede Anfrage wird geprüft auf:

1. Ein gültiges Token: Es existiert, ist weder abgelaufen noch widerrufen, und sein Secret stimmt überein.
2. Ein autorisierter Besitzer: Der Benutzer, der das Token erstellt hat, verfügt noch über ein aktiviertes Konto und eine Administratorrolle, die den Tenant erreicht (siehe [Token-Besitzerprüfung](#token-owner-check)).
3. Ein aktiver Tenant, bei dem die MCP-Server-Funktion aktiviert ist.

| Antwort                 | Ursache                                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | Kein Bearer-Token, fehlerhaftes Token, unbekanntes, abgelaufenes oder widerrufenes Token oder der Token-Besitzer besteht die Besitzerprüfung nicht. |
| `403 Forbidden`         | Die MCP-Server-Funktion ist für den Tenant nicht aktiviert oder der Tenant ist deaktiviert.                                                         |
| `429 Too Many Requests` | Das Rate-Limit des Tenant ist ausgeschöpft (siehe [Rate-Limit](#rate-limit)).                                                                       |

## MCP-Zugriffstokens

MCP-Zugriffstokens werden im RealmJoin Portal unter verwaltet **Einstellungen** > **MCP-Zugriff**.

### Ein Token erstellen

{% stepper %}
{% step %}

### MCP-Zugriff öffnen

Öffnen Sie im RealmJoin Portal **Einstellungen** > **MCP-Zugriff** und klicken Sie auf **Neu hinzufügen** (Plus-Symbol) neben dem Suchfeld.
{% endstep %}

{% step %}

### Benennen Sie das Token und wählen Sie seine Laufzeit

In **Neues MCP-Token**, geben Sie einen **Name** ein, das den Client oder den Zweck identifiziert, zum Beispiel `Claude Desktop` (erforderlich, bis zu 100 Zeichen). Wählen Sie **Läuft ab nach**: 30, 90 (Standard), 180 oder 365 Tage. Klicken Sie auf **Erstellen**.

<figure><img src="https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-5eaace9fadaabec3068651837b60d659c666e233%2Fmcp-new-token.png?alt=media" alt="New MCP token dialog with the fields Name and Expires after"><figcaption><p>Neues MCP-Token</p></figcaption></figure>
{% endstep %}

{% step %}

### Token kopieren

Der Dialog **MCP-Token erstellt** zeigt das Token nur einmal an. Kopieren Sie es und speichern Sie es in einem Secret Store, bevor Sie auf **Fertig**. RealmJoin speichert nur einen Hash des Token-Secrets, sodass das Token nicht erneut angezeigt werden kann. Wenn es verloren geht, erstellen Sie ein neues Token und widerrufen Sie das alte.
{% endstep %}
{% endstepper %}

Ein Token hat das Format `rjm_<tenant ID>.<token ID>.<secret>`. Es ist an den Tenant gebunden, der im Portal ausgewählt ist, wenn das Token erstellt wird, und an den Benutzer, der es erstellt. Ein von einem Partneradministrator in einem Kunden-Tenant erstelltes Token gewährt nur Zugriff auf diesen Kunden-Tenant.

### Tokenliste

Die **MCP-Zugriff** Registerkarte listet alle Tokens des Tenant auf, die von einem beliebigen Administrator erstellt wurden, neueste zuerst. Das Suchfeld filtert nach Name und Besitzer.

<figure><img src="https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-e4e64be11dc0e2b77352f58966b158091cbbc968%2Fsettings-mcp-access.png?alt=media" alt="MCP Access settings tab with the token list"><figcaption><p>Registerkarte MCP-Zugriff</p></figcaption></figure>

| Spalte            | Inhalt                                                                                                                                                                                          |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name              | Der bei der Erstellung eingegebene Name.                                                                                                                                                        |
| Owner             | User Principal Name des Benutzers, der das Token erstellt hat. **Ihre** markiert Ihre eigenen Tokens.                                                                                           |
| Status            | **Gültig**, **Abgelaufen** oder **Widerrufen**. Wenn Sie mit der Maus über **Widerrufen** zeigen, wer das Token widerrufen hat.                                                                 |
| Läuft ab          | Ablaufzeit. Tokens, die erstellt wurden, bevor der Ablauf verpflichtend wurde, zeigen **nach der nächsten Verwendung**: Sie erhalten ab ihrer nächsten Verwendung ein Ablaufdatum von 90 Tagen. |
| Zuletzt verwendet | Zeitpunkt der letzten authentifizierten Anfrage, höchstens einmal pro Minute aktualisiert, oder **nie**.                                                                                        |
| Erstellt          | Erstellungszeitpunkt.                                                                                                                                                                           |

### Token widerrufen

Klicken Sie auf **Widerrufen** in der Zeile des Tokens und bestätigen Sie. Jeder Administrator kann jedes gültige Token des Tenant widerrufen, einschließlich Tokens anderer Benutzer. Der Widerruf wird mit der nächsten Anfrage wirksam. Widerrufene und abgelaufene Tokens bleiben mit ihrem Status in der Liste; sie können nicht reaktiviert werden.

### Token-Besitzerprüfung

Ein Token wirkt mit dem Zugriff des Benutzers, der es erstellt hat. Bei jeder Anfrage überprüft RealmJoin den Besitzer in seinem Home-Tenant:

* Das Benutzerkonto existiert und ist aktiviert.
* Der Benutzer besitzt derzeit eine Rolle, die gewährt `CanAdministerOwnTenant`: die RealmJoin **Admin** Rolle (siehe [Vordefinierte Rollen](https://docs.realmjoin.com/de/administration-and-einstellungen/permission/pre-defined-roles.md#admin-permissions)) oder die aktive Entra ID **Global Administrator** Rolle.
* Für einen anderen Tenant als den Home-Tenant ist der Home-Tenant als Partner dieses Tenant registriert.

Das Ergebnis wird 5 Minuten lang zwischengespeichert. Ein deaktiviertes Konto oder eine entfernte Administratorrolle stoppt daher die Tokens des Benutzers innerhalb von 5 Minuten, ohne sie zu widerrufen. Wenn die Prüfung nicht abgeschlossen werden kann, zum Beispiel weil Microsoft Graph nicht verfügbar ist, werden Anfragen für 1 Minute abgelehnt.

{% hint style="warning" %}
Die Prüfung verwendet die aktuellen Gruppenmitgliedschaften und Active Directory-Rollen des Besitzers. Wenn der Administratorzugriff des Besitzers aus Privileged Identity Management (PIM) stammt, funktionieren seine Tokens nur, solange die Gruppenmitgliedschaft oder Rolle aktiviert ist.
{% endhint %}

## Einen Client verbinden

Konfigurieren Sie den Client mit der Endpunkt-URL und einem `Authorization` Header, der das Token überträgt. Das Konfigurationsformat hängt vom Client ab. Halten Sie das Token aus Konfigurationsdateien heraus, die in die Quellcodeverwaltung eingecheckt werden; verwenden Sie stattdessen den Mechanismus des Clients für Umgebungsvariablen oder Secret-Prompts.

{% tabs %}
{% tab title="Allgemein (mcpServers-JSON)" %}
Clients, die das `mcpServers` JSON-Format verwenden, wobei das Token aus der Umgebungsvariable `REALMJOIN_MCP_TOKEN`:

```json
{
  "mcpServers": {
    "realmjoin": {
      "type": "http",
      "url": "https://customer-api.realmjoin.com/mcp",
      "headers": {
        "Authorization": "Bearer ${REALMJOIN_MCP_TOKEN}"
      }
    }
  }
}
```

Ob `${...}` Variablen erweitert werden, hängt vom Client ab.
{% endtab %}

{% tab title="Claude Code" %}

```bash
claude mcp add --transport http realmjoin https://customer-api.realmjoin.com/mcp \\
  --header "Authorization: Bearer $REALMJOIN_MCP_TOKEN"
```

Die Shell erweitert `$REALMJOIN_MCP_TOKEN` wenn der Befehl ausgeführt wird, und Claude Code speichert den resultierenden Header in seiner Konfiguration.
{% endtab %}

{% tab title="VS Code" %}
`.vscode/mcp.json`; VS Code fragt beim ersten Start nach dem Token und speichert es in seinem Secret-Speicher:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "realmjoin-mcp-token",
      "description": "RealmJoin MCP token",
      "password": true
    }
  ],
  "servers": {
    "realmjoin": {
      "type": "http",
      "url": "https://customer-api.realmjoin.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:realmjoin-mcp-token}"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Verfügbare Tools

Alle Tools geben JSON als Text zurück und lesen nur Daten des Tenant, an den das Token gebunden ist. Gerätedaten stammen aus dem Gerätezustand, den der RealmJoin Agent meldet; Geräte ohne den Agenten werden nicht gefunden. Softwaredaten stammen aus [Software Reporting](https://docs.realmjoin.com/de/analysieren-and-exportieren/software-reporting.md).

| Tool                  | Parameter                                            | Gibt zurück                                                                                     |
| --------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `get_tenant_overview` | keine                                                | Aktive und gesamte Geräte- und Benutzeranzahlen, Anzahl der Softwarepakete, Aktivitätsschwelle. |
| `search_devices`      | `Abfrage`                                            | Bis zu 25 Geräte, die mit einem Maschinennamen oder Geräte-ID-Präfix übereinstimmen.            |
| `get_device_by_name`  | `Name`                                               | Vollständiger Gerätezustand des zuletzt gesehenen Geräts mit diesem Namen.                      |
| `get_device_state`    | `deviceId`, optional `Pfade`, optional `vollständig` | Zusammenfassung, ausgewählte Abschnitte oder der vollständige Gerätezustand eines Geräts.       |
| `list_packages`       | optional `Suche`                                     | Bis zu 50 Softwarepakete mit Geräte- und Benutzeranzahlen.                                      |
| `get_software_report` | `packageId`                                          | Installierte Versionen eines Pakets mit Geräte-, Benutzer- und Nutzungsanzahlen.                |

### get\_tenant\_overview

Gibt zurück:

* `Devices.Active` / `Devices.Total`: Geräte, die innerhalb der Aktivitätsschwelle gesehen wurden, und alle Geräte.
* `Users.Active` / `Users.Total`: dasselbe für Benutzer.
* `SoftwarePackages`: Anzahl der RealmJoin-Pakete im Tenant.
* `ActivityThreshold`: der Grenzzeitpunkt für "aktiv" (aktuelle Zeit minus dem Aktivitätszeitraum des Tenant, standardmäßig 90 Tage).

### search\_devices

`Abfrage` stimmt mit einem Gerät überein, wenn der Maschinenname es enthält (Groß-/Kleinschreibung wird ignoriert) oder die RealmJoin-Client-ID, die Entra-Geräte-ID oder die Intune-Geräte-ID damit beginnt. Gibt bis zu 25 Geräte zurück, zuletzt gesehen zuerst, jeweils mit `ClientID`, `UserID`, `MachineName`, `VersionTray` (Agentenversion) und `ServerTimestamp` (letzter Check-in). Wenn mehr Geräte übereinstimmen, gibt die Antwort an, wie viele insgesamt übereinstimmen.

### get\_device\_by\_name

`Name` wird ohne Berücksichtigung der Groß-/Kleinschreibung mit dem Hostnamen und dem Maschinennamen verglichen; nur exakte Übereinstimmungen zählen. Wenn mehrere Geräte denselben Namen haben, wird das zuletzt gesehene zurückgegeben. Die Antwort enthält den vollständigen Gerätezustand und wird bei 20.000 Zeichen abgeschnitten; verwenden Sie `get_device_state` mit `Pfade` für bestimmte Abschnitte.

### get\_device\_state

`deviceId` ist eine GUID: die RealmJoin-Client-ID, die Entra-Geräte-ID oder die Intune-Geräte-ID.

* Ohne `Pfade` und `vollständig`, enthält die Antwort diese Abschnitte: `ClientID`, `MachineName`, `HostName`, `UserID`, `ServerTimestamp`, `VersionTray`, `OperatingSystem`, `Intune`, `Msoa`, `AzureAD`, `User`.
* `Pfade` ersetzt diese Auswahl durch die aufgeführten Eigenschaftspfade des Gerätezustands, zum Beispiel `Intune`, `BranchCache`, `LocalAdminManagement` oder `CustomStates.PrinterInventory`. Pfade können Buchstaben, Ziffern, Unterstriche, Bindestriche, Punkte und Array-Indizes enthalten.
* `full: true` gibt den vollständigen Gerätezustand zurück.

Antworten, die länger als 20.000 Zeichen sind, werden abgeschnitten, mit einem Hinweis, der die Gesamtlänge angibt.

### list\_packages

Listet Pakete der Software-Reporting-Daten auf, deren Paket-ID mit `generic-` (Package Store-Pakete), nach Geräteanzahl sortiert, höchstens 50. `Suche` filtert nach einer Teilzeichenfolge der Paket-ID, zum Beispiel `chrome`. Jeder Eintrag enthält `PackageId`, `DeviceCount` und `UserCount`.

### get\_software\_report

`packageId` muss genau mit einer Paket-ID übereinstimmen, zum Beispiel `generic-7zip`; verwenden Sie `list_packages` um es zu finden. Gibt bis zu 20 Einträge zurück, höchste Version zuerst. Jeder Eintrag enthält die Paket-ID, `Version`, `Publisher`, den Installationstyp, `DeviceCount`, `UserCount`, `LicenseCount`, die Geräte-, Benutzer- und Lizenzanzahlen basierend auf Ausführungen, `TotalExecutions` und `LastExecution`.

## Rate-Limit

Jeder Tenant kann 60 Anfragen pro Minute an den MCP-Endpunkt senden, gezählt in einem gleitenden Fenster aus sechs 10-Sekunden-Abschnitten. Das Limit gilt für den Tenant, sodass alle Tokens eines Tenant es gemeinsam nutzen. Anfragen über dem Limit werden sofort abgelehnt mit `429 Too Many Requests`; sie werden nicht in eine Warteschlange gestellt.

Jede MCP-Nachricht ist eine separate HTTP-Anfrage, einschließlich Sitzungsinitialisierung und Tool-Auflistung, sodass ein Client mehr als eine Anfrage pro Tool-Aufruf verwendet. Anfragen, die mit `401` oder `403` abgelehnt werden, zählen nicht.

## Sicherheitsaspekte

* **Geltungsbereich eines Tokens:** ein Token gewährt Lesezugriff auf den Gerätezustand und die Softwaredaten seines Tenant, mit dem Zugriff des Benutzers, der es erstellt hat. Jeder, der das Token besitzt, kann es verwenden, bis es abläuft oder widerrufen wird.
* **Daten, die RealmJoin verlassen:** Tool-Ergebnisse, einschließlich Gerätenamen, Benutzer-IDs und anderer Gerätezustände, werden an den MCP-Client und, bei KI-Assistenten, an den Modellanbieter weitergegeben, den der Client verwendet. Prüfen Sie, ob dies für die Daten Ihres Tenant zulässig ist, bevor Sie einen Client verbinden.
* **Speicherung:** Speichern Sie Tokens in einem Passwortmanager oder Secret Store oder im Secret-Speicher des Clients. Checken Sie sie nicht in die Quellcodeverwaltung ein, fügen Sie sie nicht in Tickets oder Chats ein und teilen Sie ein Token nicht zwischen mehreren Personen oder Clients.
* **Laufzeit und Rotation:** Wählen Sie die kürzeste Laufzeit, die für den Einsatz passt. Um zu rotieren, erstellen Sie ein neues Token, aktualisieren Sie den Client und widerrufen Sie dann das alte Token.
* **Widerruf:** Widerrufen Sie Tokens, die nicht mehr verwendet werden oder möglicherweise offengelegt wurden. Jeder Administrator des Tenant kann jedes Token auf der **MCP-Zugriff** Registerkarte widerrufen. Prüfen Sie **Zuletzt verwendet** um ungenutzte Tokens zu finden.
* **Besitzerwechsel:** wenn der Besitzer geht oder die Administratorrolle verliert, funktionieren seine Tokens innerhalb von 5 Minuten nicht mehr. Widerrufen Sie sie trotzdem, damit die Liste ihren tatsächlichen Status anzeigt.
* **Tenant-Löschung:** das Löschen eines Tenant löscht alle seine MCP-Tokens.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/de/dev-reference/mcp-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
