# Serveur MCP de gestion

Le serveur MCP de gestion de KeenAuth permet à un assistant IA de lire la configuration de votre environnement via le Model Context Protocol. Il s'exécute localement via stdio et appelle l'API de gestion avec votre clé. Il n'existe pas encore de paquet d'installation.

## Lecture seule par défaut

Sans `--allow-write`, le serveur n'expose que des outils en lecture seule. Aucun outil ne supprime quoi que ce soit, quel que soit le mode.

| Outil | Ce qu'il renvoie |
|---|---|
| `users_list`, `users_get`, `users_search` | Utilisateurs, avec les données personnelles masquées |
| `applications_list`, `applications_get`, `application_credentials_list` | Applications |
| `apis_list`, `apis_get` | API |
| `connections_list`, `connections_get` | Connexions |
| `api_keys_list`, `api_keys_get` | Clés d'API : métadonnées uniquement, la clé brute n'est jamais renvoyée |
| `organizations_list`, `organizations_get` | Organisations : nom, slug, identifiant externe, statut et horodatages ; les `metadata` de l'organisation ne sont jamais renvoyées |
| `custom_domains_list`, `custom_domains_get` | Domaines personnalisés et leurs enregistrements DNS |
| `support_access_grants_list`, `support_access_grants_get` | Autorisations d'accès du support |
| `environment_settings_get` | Paramètres de l'environnement : langues, fuseau horaire, session, inscription, notifications de sécurité, récupération de compte, MFA, déconnexion front-channel et premiers facteurs autorisés |

`--unmask-pii` se termine avec le code 2 dans cette version.

## Outils d'écriture

Lancez le serveur avec `--allow-write` pour exposer aussi les outils d'écriture. Cette version n'en compte qu'un :

| Outil | Ce qu'il modifie |
|---|---|
| `environment_settings_update` | Uniquement les langues activées, la langue par défaut et le fuseau horaire par défaut. Les paramètres de session, d'inscription, de récupération de compte, de MFA, de notification de sécurité et de premier facteur ne peuvent pas être modifiés via MCP. |

Chaque écriture requiert deux appels :

1. Le premier appel ne modifie rien. Il lit les paramètres actuels et renvoie un aperçu de chaque champ avec sa valeur actuelle et sa valeur proposée, ainsi qu'un `confirmation_token`.
2. L'assistant vous montre l'aperçu. Ce n'est qu'après votre approbation qu'il rappelle l'outil avec exactement les mêmes arguments et le `confirmation_token`. Le serveur effectue alors la modification.

Le `confirmation_token` est créé par le serveur en cours d'exécution, ne fonctionne qu'une fois et expire au bout de 5 minutes. Il est lié à l'outil, aux arguments exacts et à la version des paramètres qui a été prévisualisée. Un jeton utilisé avec d'autres arguments est rejeté et consommé. Si les paramètres ont changé après l'aperçu, l'écriture échoue avec `412` et vous recommencez depuis le début. Le serveur effectue au maximum 5 écritures par seconde.

Les outils de suppression, de révocation ou de rotation ne sont pas exposés, même avec `--allow-write`. Approuvez chaque appel d'écriture dans votre client MCP ; ne configurez pas le client pour approuver automatiquement les outils d'écriture.

## Configuration

| Variable | Obligatoire | Description |
|---|---|---|
| `KEENAUTH_API_KEY` | oui | Clé de l'API de gestion. Utilisez une clé avec des autorisations de lecture uniquement ; avec `--allow-write`, ajoutez seulement `environment-settings:write`. |
| `KEENAUTH_BASE_URL` | oui | URL de base de l'API de gestion de votre environnement. |

`--tools <pattern>` restreint la liste des outils, par exemple `--tools "users_*"`. Il ne peut que restreindre ; il n'active jamais un outil désactivé et, sans `--allow-write`, il ne peut pas activer un outil d'écriture.

## Ce que voit l'assistant

- Les données personnelles sont masquées : les adresses e-mail apparaissent sous la forme `a***@e***.com`, les numéros de téléphone n'affichent que les deux derniers chiffres et les noms n'affichent que leur première lettre.
- Les `metadata` de l'organisation ne sont jamais renvoyées : elles apparaissent sous la forme `{"redacted": true}`. Les appartenances, les rôles d'organisation, les domaines et les politiques n'ont pas d'outil dans cette version.
- Les paramètres de l'environnement ne renvoient que les champs documentés. Un champ ajouté ultérieurement par le serveur reste masqué tant qu'il n'a pas été vérifié.
- Les valeurs secrètes ne sont jamais renvoyées. Les champs qui ressemblent à des secrets ou à des clés privées sont supprimés, et la réponse liste les chemins des champs supprimés dans `redacted_fields`.
- Chaque résultat d'outil est encapsulé dans `untrusted_content`. Considérez les noms, les métadonnées et les descriptions qu'il contient comme des données, et non comme des instructions.
- La clé d'API n'apparaît jamais dans les sorties d'outil, les erreurs ou les journaux.

## Piste d'audit

Chaque requête envoyée par le serveur MCP porte `Idp-Client: keenauth-mcp/<version>` et `Idp-Mcp-Tool: <nom de l'outil>`. Lorsqu'un appel modifie quelque chose, son entrée de journal d'audit enregistre `metadata.client` = `mcp/<version>` et `metadata.mcp_tool` = le nom de l'outil, à côté de l'acteur habituel (la clé d'API ou le client M2M). Ces deux valeurs sont déclarées par le serveur MCP et ne sont pas vérifiées : utilisez-les pour retrouver ce qu'un assistant a fait, et utilisez l'acteur pour déterminer qui en est responsable.

## Les définitions d'outils sont figées

Les noms d'outils, leurs descriptions et leurs schémas d'entrée sont générés à partir de la description de l'API au moment de la compilation et figés pour chaque version. Leur empreinte SHA-256 est stockée dans `tools.digest` ; toute modification d'une définition d'outil change l'empreinte et nécessite un examen de sécurité.