Assistant IA et tokens applicatifs

Cet écran est accessible depuis le menu Développer - Utiliser l'IA.

Il permet de connecter un assistant conversationnel (Claude Code, Claude Desktop, ...) à Onyx, via un "serveur MCP". Le serveur MCP est un petit programme qui s'exécute sur le poste de l'utilisateur et qui fait le lien entre l'assistant et Onyx : les questions sont posées en français, et l'assistant consulte Onyx au nom de l'utilisateur.

L'écran est composé de deux onglets :

• "Tokens applicatifs", pour créer et révoquer les jetons d'accès ;
• "Assistant IA", qui rappelle le périmètre de l'assistant et la procédure d'installation.

Ce que l'assistant ne fera jamais

L'assistant est en lecture et en écriture sur la configuration, mais il ne pilote aucune exécution. Il ne peut pas :

• exécuter un script, une requête SQL ou une commande ;
• démarrer ou arrêter un traitement, ni activer une planification ;
• supprimer quoi que ce soit ;
• révéler la valeur d'un secret (il peut indiquer quels secrets existent, jamais ce qu'ils contiennent) ;
• ouvrir un accès réseau : il s'exécute sur le poste de l'utilisateur et n'ouvre aucun port. Ce qu'il crée dans Onyx arrive inactif, à l'utilisateur de l'activer.

Enfin, il ne peut rien faire que l'utilisateur ne puisse déjà faire lui-même : il agit avec les droits de la personne qui a créé le token, ni plus ni moins.

Les tokens applicatifs

Un token applicatif permet à un programme (un assistant IA via le serveur MCP, un script, un job planifié) d'appeler Onyx au nom d'un utilisateur, sans son mot de passe. Il porte exactement les permissions de cet utilisateur, évaluées à chaque appel : un droit retiré à la personne est retiré au token au même instant. Il est révocable à tout moment.

Le token identifie également son tenant : il n'est jamais nécessaire de saisir un nom de tenant dans le client.

Créer un token

Dans l'onglet "Tokens applicatifs", deux informations sont demandées :

• Nom

  Texte libre, 100 caractères au maximum. Il sert à savoir quel client reconfigurer le jour où le token est révoqué (par exemple "MCP sur mon portable"). Le nom est obligatoire.

• Validité

  Durée au terme de laquelle le token expire. Quatre choix sont proposés : 30 jours, 90 jours, 365 jours, ou "N'expire jamais". La valeur par défaut est 90 jours.

Sélectionner ensuite le bouton "Nouveau token".

Le token s'affiche alors dans une fenêtre "Token créé". Il n'est affiché qu'une seule fois : Onyx n'en conserve qu'une empreinte, il est donc impossible de le réafficher par la suite. Le copier immédiatement avec le bouton de copie, puis fermer la fenêtre avec "J'ai copié le token". En cas de perte, il faut révoquer le token et en créer un autre.

Un token commence toujours par onyx_pat_.

Consulter et révoquer les tokens

Le tableau situé sous le formulaire ne présente que les tokens de l'utilisateur connecté. Il comporte les colonnes suivantes :

Les tokens expirés restent affichés : ils expliquent pourquoi un client a cessé de fonctionner.

Pour révoquer un token, sélectionner le bouton "Révoquer" sur la ligne concernée et confirmer. Tout client qui l'utilise cesse de fonctionner. La révocation est définitive : il n'existe ni modification ni réactivation d'un token.

Mettre en place le serveur MCP

L'onglet "Assistant IA" récapitule la procédure et affiche les valeurs propres à l'instance, avec un bouton de copie pour chacune.

1. Créer un token dans l'onglet "Tokens applicatifs" et le copier.

2. L'enregistrer dans un fichier nommé .env, à un emplacement lisible par le seul utilisateur. L'adresse affichée dans l'écran est celle de l'API de l'instance, et non celle de l'interface web : la recopier telle quelle et ne remplacer que la ligne du token.

ONYX_API_URL=https://adresse-de-mon-api-onyx
ONYX_TOKEN=onyx_pat_…

3. Indiquer à l'assistant où trouver le serveur. Dans Claude Code, il s'agit d'un fichier .mcp.json placé dans le projet ; dans Claude Desktop, de claude_desktop_config.json. La variable ONYX_ENV_FILE doit pointer sur le fichier créé à l'étape précédente.

{
  "mcpServers": {
    "onyx": {
      "command": "uvx",
      "args": ["--from", "ads-onyx-mcp", "onyx-mcp-server"],
      "env": { "ONYX_ENV_FILE": "C:/Users/vous/onyx/.env" }
    }
  }
}

4. Vérifier l'installation avant de s'y fier. La commande ci-dessous contrôle le token, les droits et l'adresse, et nomme ce qui ne va pas.

uvx --from ads-onyx-mcp onyx-mcp-server --check

Aucune installation préalable n'est nécessaire : uvx récupère lui-même le programme.

La documentation complète du serveur MCP, ainsi que la configuration des assistants autres que Claude, sont disponibles sur pypi.org/project/ads-onyx-mcp (opens in a new tab).

Droits nécessaires

Deux permissions encadrent cet écran, dans l'arborescence des droits d'un rôle sous "Pages" :

• Utiliser l'IA : donne accès à l'écran et à l'onglet "Assistant IA" ;
• Tokens applicatifs : donne en plus accès à l'onglet "Tokens applicatifs", donc à la création et à la révocation des tokens.

Un utilisateur qui ne dispose que de la première permission peut lire la procédure d'installation, mais ne peut pas créer de token.