> 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/fr/dev-reference/mcp-server.md).

# Serveur MCP

Serveur MCP RealmJoin : point de terminaison, jetons d'accès MCP, configuration du client, les outils en lecture seule pour l'état de l'appareil et les données logicielles, limite de débit et sécurité.

RealmJoin exécute un [Protocole de contexte de modèle](https://modelcontextprotocol.io/) (MCP) en tant que serveur dans le cadre de la Customer-API de RealmJoin. Les clients MCP, par exemple des assistants IA et des agents d'IDE, s'y connectent avec un jeton d'accès MCP et appellent ses outils pour lire l'état des appareils et les données logicielles de votre tenant.

Tous les outils sont en lecture seule. Le serveur MCP ne peut pas modifier les appareils, les packages, les affectations ou les paramètres.

## Exigences

* Le serveur MCP est activé pour votre tenant. La fonctionnalité est activée par RealmJoin ; contactez le support RealmJoin pour la faire activer.
* La création et la révocation des jetons nécessitent un rôle d'administrateur dans le Portal RealmJoin : le RealmJoin **Administrateur** rôle ou le rôle Entra ID **Global Administrator** rôle (stratégie du Portal `CanAdministerOwnTenant`; il ne peut pas être accordé via [Rôles personnalisés](https://docs.realmjoin.com/fr/administration-et-parametres/permission/custom-roles.md)). Le **Accès MCP** onglet Paramètres ne s'affiche qu'avec ce rôle et lorsque la fonctionnalité est activée.
* Un client MCP qui prend en charge le transport HTTP streamable et peut envoyer un `Authorization` en-tête. Le serveur MCP n'offre pas de connexion OAuth, donc les clients qui se connectent uniquement à des serveurs distants via OAuth ne peuvent pas l'utiliser.

## Point de terminaison et authentification

| Propriété        | Valeur                                   |
| ---------------- | ---------------------------------------- |
| URL              | `https://customer-api.realmjoin.com/mcp` |
| Transport        | Streamable HTTP                          |
| Authentification | `Authorization: Bearer <MCP token>`      |
| Nom du serveur   | `realmjoin`                              |

Le point de terminaison n'accepte que des jetons d'accès MCP. Le nom d'utilisateur et le secret utilisés pour [RealmJoin API](https://docs.realmjoin.com/fr/dev-reference/realmjoin-api/authentication.md) (HTTP Basic) ne sont pas acceptés ici.

Chaque requête est vérifiée pour :

1. Un jeton valide : il existe, n'est ni expiré ni révoqué, et son secret correspond.
2. Un propriétaire autorisé : l'utilisateur qui a créé le jeton a toujours un compte activé et un rôle d'administrateur qui s'applique au tenant (voir [Vérification du propriétaire du jeton](#token-owner-check)).
3. Un tenant actif avec la fonctionnalité de serveur MCP activée.

| Réponse                | Cause                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Non autorisé`     | Aucun jeton Bearer, jeton mal formé, jeton inconnu, expiré ou révoqué, ou le propriétaire du jeton échoue à la vérification du propriétaire. |
| `403 Interdit`         | La fonctionnalité de serveur MCP n'est pas activée pour le tenant, ou le tenant est désactivé.                                               |
| `429 Trop de requêtes` | La limite de débit du tenant est épuisée (voir [Limite de débit](#rate-limit)).                                                              |

## Jetons d'accès MCP

Les jetons d'accès MCP sont gérés dans le Portal RealmJoin sous **Settings** > **Accès MCP**.

### Créer un jeton

{% stepper %}
{% step %}

### Ouvrir l'accès MCP

Dans le Portal RealmJoin, ouvrez **Settings** > **Accès MCP** et cliquez sur **Ajouter nouveau** (icône plus) à côté du champ de recherche.
{% endstep %}

{% step %}

### Nommez le jeton et choisissez sa durée de vie

Dans **Nouveau jeton MCP**, saisissez un **Nom** qui identifie le client ou l'objectif, par exemple `Claude Desktop` (obligatoire, jusqu'à 100 caractères). Sélectionnez **Expire après**: 30, 90 (par défaut), 180 ou 365 jours. Cliquez sur **Créer**.

<figure><img src="https://1100180853-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>Nouveau jeton MCP</p></figcaption></figure>
{% endstep %}

{% step %}

### Copier le jeton

La boîte de dialogue **Jeton MCP créé** affiche le jeton une seule fois. Copiez-le et enregistrez-le dans un coffre-fort de secrets avant de cliquer sur **Terminé**. RealmJoin stocke uniquement un hachage du secret du jeton, donc le jeton ne peut plus être affiché. S'il est perdu, créez un nouveau jeton et révoquez l'ancien.
{% endstep %}
{% endstepper %}

Un jeton a le format `rjm_<tenant ID>.<token ID>.<secret>`. Il est lié au tenant sélectionné dans le Portal lors de la création du jeton et à l'utilisateur qui le crée. Un jeton créé par un administrateur partenaire dans un tenant client donne accès uniquement à ce tenant client.

### Liste des jetons

Le **Accès MCP** l'onglet répertorie tous les jetons du tenant, créés par n'importe quel administrateur, les plus récents en premier. Le champ de recherche filtre par nom et par propriétaire.

<figure><img src="https://1100180853-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>onglet Accès MCP</p></figcaption></figure>

| Colonne              | Contenu                                                                                                                                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nom                  | Le nom saisi lors de la création.                                                                                                                                                                                    |
| Owner                | Nom d'utilisateur principal de l'utilisateur qui a créé le jeton. **Le vôtre** indique vos propres jetons.                                                                                                           |
| Statut               | **Valide**, **Expiré** ou **Révoqué**. En survolant **Révoqué** indique qui a révoqué le jeton.                                                                                                                      |
| Expire               | Heure d'expiration. Les jetons créés avant que l'expiration ne devienne obligatoire affichent **après la prochaine utilisation**: ils obtiennent une expiration de 90 jours à compter de leur prochaine utilisation. |
| Dernière utilisation | Heure de la dernière requête authentifiée, mise à jour au maximum une fois par minute, ou **jamais**.                                                                                                                |
| Créé                 | Heure de création.                                                                                                                                                                                                   |

### Révoquer un jeton

Cliquez sur **Révoquer** dans la ligne du jeton et confirmez. Chaque administrateur peut révoquer chaque jeton valide du tenant, y compris les jetons d'autres utilisateurs. La révocation prend effet à la requête suivante. Les jetons révoqués et expirés restent dans la liste avec leur statut ; ils ne peuvent pas être réactivés.

### Vérification du propriétaire du jeton

Un jeton agit avec les droits d'accès de l'utilisateur qui l'a créé. À chaque requête, RealmJoin vérifie le propriétaire dans son tenant d'origine :

* Le compte utilisateur existe et est activé.
* L'utilisateur possède actuellement un rôle qui accorde `CanAdministerOwnTenant`: le RealmJoin **Administrateur** rôle (voir [Rôles prédéfinis](https://docs.realmjoin.com/fr/administration-et-parametres/permission/pre-defined-roles.md#admin-permissions)) ou le rôle Entra ID actif **Global Administrator** .
* Pour un tenant autre que le tenant d'origine, le tenant d'origine est enregistré comme partenaire de ce tenant.

Le résultat est mis en cache pendant 5 minutes. Un compte désactivé ou un rôle d'administrateur supprimé arrête donc les jetons de l'utilisateur dans un délai de 5 minutes, sans les révoquer. Si la vérification ne peut pas être effectuée, par exemple parce que Microsoft Graph est indisponible, les requêtes sont refusées pendant 1 minute.

{% hint style="warning" %}
La vérification utilise les appartenances actuelles du propriétaire aux groupes et les rôles Active Directory. Si l'accès d'administrateur du propriétaire provient de Privileged Identity Management (PIM), ses jetons ne fonctionnent que lorsque l'appartenance au groupe ou le rôle est activé.
{% endhint %}

## Connecter un client

Configurez le client avec l'URL du point de terminaison et un `Authorization` en-tête qui contient le jeton. Le format de configuration dépend du client. Gardez le jeton hors des fichiers de configuration validés dans le contrôle de source ; utilisez plutôt le mécanisme du client pour les variables d'environnement ou les invites de secret.

{% tabs %}
{% tab title="Générique (JSON mcpServers)" %}
Les clients qui utilisent le `mcpServers` format JSON, avec le jeton pris depuis la variable d'environnement `REALMJOIN_MCP_TOKEN`:

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

La question de savoir si `${...}` les variables sont développées dépend du client.
{% endtab %}

{% tab title="Claude Code" %}

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

Le shell développe `$REALMJOIN_MCP_TOKEN` lorsque la commande s'exécute, et Claude Code stocke l'en-tête résultant dans sa configuration.
{% endtab %}

{% tab title="VS Code" %}
`.vscode/mcp.json`; VS Code demande le jeton au premier démarrage et le stocke dans son stockage sécurisé :

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

{% endtab %}
{% endtabs %}

## Outils disponibles

Tous les outils renvoient du JSON sous forme de texte et ne lisent que les données du tenant auquel le jeton est lié. Les données des appareils proviennent de l'état de l'appareil signalé par l'agent RealmJoin ; les appareils sans l'agent ne sont pas trouvés. Les données logicielles proviennent de [Reporting logiciel](https://docs.realmjoin.com/fr/analyser-et-exporter/software-reporting.md).

| Outil                 | Paramètres                                        | Renvoie                                                                                                 |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `get_tenant_overview` | aucun                                             | Nombres d'appareils et d'utilisateurs actifs et totaux, nombre de packages logiciels, seuil d'activité. |
| `search_devices`      | `requête`                                         | Jusqu'à 25 appareils correspondant à un nom de machine ou à un préfixe d'ID d'appareil.                 |
| `get_device_by_name`  | `nom`                                             | État complet de l'appareil le plus récemment vu portant ce nom.                                         |
| `get_device_state`    | `deviceId`, facultatif `paths`, facultatif `full` | Résumé, sections sélectionnées ou état complet d'un appareil.                                           |
| `list_packages`       | facultatif `recherche`                            | Jusqu'à 50 packages logiciels avec les nombres d'appareils et d'utilisateurs.                           |
| `get_software_report` | `packageId`                                       | Versions installées d'un package avec les nombres d'appareils, d'utilisateurs et d'utilisations.        |

### get\_tenant\_overview

Renvoie :

* `Devices.Active` / `Devices.Total`: appareils vus dans le délai d'activité, et tous les appareils.
* `Users.Active` / `Users.Total`: idem pour les utilisateurs.
* `SoftwarePackages`: nombre de packages RealmJoin dans le tenant.
* `ActivityThreshold`: le seuil temporel pour "actif" (heure actuelle moins la période d'activité du tenant, 90 jours par défaut).

### search\_devices

`requête` correspond à un appareil lorsque le nom de machine le contient (sans distinction de casse) ou que l'ID client RealmJoin, l'ID d'appareil Entra ID ou l'ID d'appareil Intune commence par celui-ci. Renvoie jusqu'à 25 appareils, du plus récemment vu au plus ancien, chacun avec `ClientID`, `UserID`, `MachineName`, `VersionTray` (version de l'agent) et `ServerTimestamp` (dernier check-in). Lorsque davantage d'appareils correspondent, la réponse indique combien correspondent au total.

### get\_device\_by\_name

`nom` est comparé sans distinction de casse au nom d'hôte et au nom de machine ; seules les correspondances exactes comptent. Si plusieurs appareils partagent le nom, celui vu le plus récemment est renvoyé. La réponse contient l'état complet de l'appareil et est tronquée à 20 000 caractères ; utilisez `get_device_state` avec `paths` pour des sections spécifiques.

### get\_device\_state

`deviceId` est un GUID : l'ID client RealmJoin, l'ID d'appareil Entra ID ou l'ID d'appareil Intune.

* Sans `paths` et `full`, la réponse contient ces sections : `ClientID`, `MachineName`, `HostName`, `UserID`, `ServerTimestamp`, `VersionTray`, `OperatingSystem`, `Intune`, `Msoa`, `AzureAD`, `User`.
* `paths` remplace cette sélection par les chemins de propriété de l'état de l'appareil listés, par exemple `Intune`, `BranchCache`, `LocalAdminManagement` ou `CustomStates.PrinterInventory`. Les chemins peuvent contenir des lettres, des chiffres, des traits de soulignement, des tirets, des points et des indices de tableau.
* `full: true` renvoie l'état complet de l'appareil.

Les réponses de plus de 20 000 caractères sont tronquées, avec une note indiquant la longueur totale.

### list\_packages

Répertorie les packages des données de Reporting logiciel dont l'ID de package commence par `generic-` (packages du Package Store), triés par nombre d'appareils, 50 au maximum. `recherche` filtre par une sous-chaîne de l'ID de package, par exemple `chrome`. Chaque entrée contient `PackageId`, `DeviceCount` et `UserCount`.

### get\_software\_report

`packageId` doit correspondre exactement à un ID de package, par exemple `generic-7zip`; utilisez `list_packages` pour le trouver. Renvoie jusqu'à 20 entrées, la version la plus élevée en premier. Chaque entrée contient l'ID du package, `Version`, `Publisher`, le type d'installation, `DeviceCount`, `UserCount`, `LicenseCount`, les nombres d'appareils, d'utilisateurs et de licences basés sur les exécutions, `TotalExecutions` et `LastExecution`.

## Limite de débit

Chaque tenant peut envoyer 60 requêtes par minute au point de terminaison MCP, comptées dans une fenêtre glissante de six segments de 10 secondes. La limite s'applique au tenant, donc tous les jetons d'un tenant la partagent. Les requêtes au-delà de la limite sont rejetées immédiatement avec `429 Trop de requêtes`; elles ne sont pas mises en file d'attente.

Chaque message MCP est une requête HTTP distincte, y compris l'initialisation de session et la liste des outils, donc un client utilise plus d'une requête par appel d'outil. Les requêtes rejetées avec `401` ou `403` ne sont pas comptabilisées.

## Considérations de sécurité

* **Portée d'un jeton :** un jeton donne un accès en lecture à l'état des appareils et aux données logicielles de son tenant, avec les droits d'accès de l'utilisateur qui l'a créé. Toute personne qui détient le jeton peut l'utiliser jusqu'à son expiration ou sa révocation.
* **Données quittant RealmJoin :** les résultats des outils, y compris les noms d'appareil, les ID utilisateur et les autres données d'état de l'appareil, sont transmis au client MCP et, pour les assistants IA, au fournisseur de modèle utilisé par le client. Vérifiez que cela est autorisé pour les données de votre tenant avant de connecter un client.
* **Stockage :** stockez les jetons dans un gestionnaire de mots de passe ou un coffre-fort de secrets, ou dans le stockage sécurisé du client. Ne les validez pas dans le contrôle de source, ne les collez pas dans des tickets ou des discussions, et ne partagez pas un jeton entre plusieurs personnes ou clients.
* **Durée de vie et rotation :** choisissez la durée de vie la plus courte adaptée à l'usage. Pour faire une rotation, créez un nouveau jeton, mettez à jour le client, puis révoquez l'ancien jeton.
* **Révocation :** révoquez les jetons qui ne sont plus utilisés ou qui ont pu être exposés. Chaque administrateur du tenant peut révoquer n'importe quel jeton sur l' **Accès MCP** onglet. Vérifiez **Dernière utilisation** pour trouver les jetons inutilisés.
* **Changements de propriétaire :** lorsque le propriétaire part ou perd le rôle d'administrateur, ses jetons cessent de fonctionner dans les 5 minutes. Révoquez-les quand même afin que la liste affiche leur état réel.
* **Suppression du Tenant :** la suppression d'un tenant supprime tous ses jetons MCP.


---

# 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/fr/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.
