# Serveur MCP > Connectez Claude, Codex, Cursor et d'autres clients MCP à vos hubs Thalovant grâce au serveur MCP publié par Thalovant. Source: https://docs.thalovant.com/fr/developers/mcp/ --- {/* Last Edit: Claude Opus 5.5 - 2026-09-28 - Motive: Canadian French translation of developers/mcp.mdx; terms per docs/french-glossary.md (AMF, serveur), and review fixes. */} Utilisez le serveur MCP de Thalovant lorsqu'un client MCP doit découvrir des hubs, provisionner des hubs et des groupes de runtime, créer des identités de client, interroger un hub, lire les analyses ou travailler avec la mémoire au moyen de Thalovant. MCP signifie Model Context Protocol. Ce protocole donne aux agents locaux et aux passerelles d'agents distantes une façon standard d'appeler les outils de Thalovant. ## En un coup d'œil | Élément | Valeur | | --- | --- | | nom dans le registre MCP | `io.github.thalovant/thalovant-mcp` | | paquet npm | `@thalovant/mcp-server` | | version actuelle | `0.6.1` | | image de conteneur | `ghcr.io/thalovant/thalovant-mcp:0.6.3` | | transports | stdio et Streamable HTTP | | nombre d'outils | 46 par défaut; 48 avec les outils destructifs activés; 23 en mode lecture seule | | chemin local | idéal pour Claude Desktop, Codex, Cursor et les agents de bureau | | chemin distant | idéal pour les passerelles d'agents hébergées et les plateformes d'agents partagées | | licence | MIT | ## Choisir un transport | Transport | Quand l'utiliser | Commande de démarrage | | --- | --- | --- | | stdio | Le client MCP s'exécute sur la même machine que le processus du serveur. | `npx --yes @thalovant/mcp-server@0.6.3 --stdio` | | Streamable HTTP | Des clients MCP distants se connectent en HTTP à `/mcp`. | `docker run ghcr.io/thalovant/thalovant-mcp:0.6.3` | Commencez avec stdio pour un agent personnel. Utilisez Streamable HTTP lorsque le serveur est déployé derrière vos propres mécanismes d'authentification, journaux et contrôles réseau. ## Connexions au runtime du hub Les outils de runtime du hub passent par le SDK Node, en WSS, en HTTPS ou en MQTT sur TLS; chaque connexion est chiffrée et authentifiée avant tout envoi. Les transports MCP stdio et Streamable HTTP décrivent la connexion entre l'agent et MCP; ils ne choisissent pas le protocole du hub. Conservez le répertoire de configuration privé du SDK Node entre les redémarrages du processus MCP ou du conteneur, pour que ses clés enregistrées survivent. Par défaut, il s'agit de `~/.config/thalovant` sous Linux et macOS, de `$XDG_CONFIG_HOME/thalovant` lorsque cette variable est définie, ou de `%APPDATA%\Thalovant` sous Windows. Un fichier d'identité personnalisé ou un `configPath` ne le déplace pas. Consultez [Clés enregistrées](/fr/developers/identity-files/#clés-enregistrées). Les appels au runtime qui utilisent le même point de terminaison de hub et la même clé d'accès sont sérialisés dans un même processus MCP, et le nettoyage réel de la connexion doit se terminer avant que le suivant commence. L'attente du bail d'identité est limitée à six secondes; un appel en file d'attente qui expire ou qui est annulé ne s'exécute jamais plus tard. Si le nettoyage échoue, cette identité reste indisponible dans le processus, pour qu'un nouvel outil ne puisse pas réutiliser un état de session incertain. Utilisez `thalovant_ask` ou `thalovant_query` lorsqu'une requête a besoin de sa réponse : des appels d'outil distincts pour l'envoi et l'attente ne partagent pas de connexion persistante, et une attente qui utilise la même identité peut retarder un envoi ultérieur. La simple inspection d'une identité n'ouvre ni ne ferme de session de hub. Utilisez des identités de runtime distinctes pour des processus MCP séparés, ou coordonnez leur usage de l'identité de l'extérieur. L'annulation d'une requête MCP est transmise à l'établissement de la connexion au runtime, à Ask, à Query et aux attentes d'événements. L'annulation met fin à l'attente de l'appelant. Une action, une entrée de code, une émission d'événement ou une opération d'inventaire déjà commencée peut quand même se terminer; son identité reste occupée jusqu'à la fin de l'opération et du nettoyage de la connexion. L'annulation n'annule pas une requête déjà publiée et ne la rejoue pas automatiquement. Utilisez une identité dédiée pour chaque processus MCP ou autre client qui s'exécute de façon indépendante. En particulier, ne réutilisez pas une identité qui sert déjà la session HTTP d'une autre application : le nouveau client attendrait une session qui appartient à l'autre. Conservez l'identité de hub enregistrée, et confirmez tout changement avec le propriétaire du hub avant de l'accepter. ## Configuration d'un agent local La découverte des hubs publics fonctionne sans identifiants Thalovant. Les outils de l'espace de travail privé et les outils de runtime ont besoin d'identifiants Thalovant côté serveur. Depuis la version `0.1.9`, un jeton d'API à portée limitée dans `THALOVANT_API_TOKEN` est la façon recommandée d'authentifier le serveur : la configuration ne contient ainsi jamais le mot de passe de votre compte. Créez le jeton sur la [page API Tokens](/fr/account/api-tokens/) du tableau de bord, avec ces portées pour accéder à l'ensemble des outils : | Portée | Outils qui en ont besoin | | --- | --- | | `hubs:read` | Découverte des hubs, détails d'un hub, catalogue de la place de marché et lectures des groupes de runtime. | | `hubs:inspect` | Inventaire d'un groupe de runtime, vue de la place de marché du groupe, capacités du runtime d'un hub, `thalovant_list_hub_skills` et `thalovant_list_hub_skill_history`. Accordée automatiquement par `hubs:read`. | | `hubs:write` | Outils de provisionnement des hubs et des groupes de runtime, ainsi que `thalovant_install_hub_skill`, `thalovant_update_hub_skill` et `thalovant_remove_hub_skill`. Forfaits payants. | | `clients:write` | `thalovant_create_client_identity`. | | `memory:read` | Lectures de la liste, du résumé et des éléments de mémoire. Tous les forfaits. | | `memory:write` | Création, mise à jour et suppression d'éléments de mémoire. Tous les forfaits; le forfait Free conserve un seul élément de mémoire. | Un assistant en lecture seule n'a besoin que de `hubs:read` et `memory:read`. Les jetons ont une portée limitée, sont révocables et affichent leur dernière utilisation sur la page API Tokens. Les portées de hub s'impliquent les unes les autres. `hubs:write` accorde `hubs:read`, qui accorde `hubs:inspect`; un jeton créé avec `hubs:read` couvre donc déjà tous les outils de découverte. Votre forfait détermine les portées que vous pouvez accorder. Le forfait Free couvre `hubs:read`, les portées de client et les portées de mémoire : un agent sur ce forfait peut donc exécuter les outils Discovery, parcourir le catalogue de la place de marché, appeler `thalovant_create_client_identity` et utiliser les outils Memory. Le forfait Free conserve un seul élément de mémoire; un deuxième `thalovant_create_memory_item` échoue donc avec HTTP 409 et le code `memory_limit`. Le forfait Free permet aussi un seul jeton actif à la fois. Un jeton d'API du forfait Free ne peut pas du tout porter `hubs:write`. L'API vérifie d'abord le forfait : sur Free, les outils Provisioning échouent donc avec HTTP 402 et le message de mise à niveau, plutôt qu'avec une erreur de portée. Consultez [Provisionner des hubs](/fr/developers/provisioning/#lire-402-avant-403). Les appels du serveur à l'API Thalovant comptent dans la limite de débit des jetons et les quotas d'appels de votre forfait; un agent très actif peut donc les atteindre. Au-delà de la limite, les appels renvoient HTTP 429 avec un en-tête `Retry-After`. La [page API Tokens](/fr/account/api-tokens/) présente le tableau par forfait et les codes d'erreur correspondants. Pour les hôtes MCP stdio qui utilisent une configuration de serveur en JSON, comme Claude Desktop ou Cursor : ```json { "mcpServers": { "thalovant": { "command": "npx", "args": ["--yes", "@thalovant/mcp-server@0.6.3", "--stdio"], "env": { "THALOVANT_API_TOKEN": "tvpat_...", "THALOVANT_PROFILE": "prod", "THALOVANT_API_URL": "https://api.thalovant.com" } } } } ``` Pour l'authentification au plan de contrôle, le serveur essaie d'abord `THALOVANT_API_TOKEN`, puis `THALOVANT_ACCESS_TOKEN`, puis une connexion avec `THALOVANT_EMAIL` et `THALOVANT_PASSWORD`. Lorsqu'un jeton est défini, le serveur n'appelle jamais le point de terminaison de connexion. Un jeton de contrôle par principal correspondant a préséance sur ces identifiants partagés. L'outil `thalovant_config_status` indique, dans son champ `controlPlaneAuthMode`, le mode que déclare l'environnement : `api-token`, `access-token`, `email-password` ou `none`. Les valeurs des jetons n'apparaissent jamais dans sa sortie. Ne collez pas de jetons Thalovant, de mots de passe, de fichiers d'identité ni de liens de configuration dans une conversation. Configurez-les dans l'environnement du serveur MCP ou dans des fichiers protégés. ### Configurer une identité de hub Un jeton d'API permet à MCP d'appeler l'API Thalovant. Les outils de runtime ont aussi besoin d'une identité de client qui contient la clé d'accès, le mot de passe et les points de terminaison de ce hub. En stdio local, utilisez l'une de ces sources : | Source | Arguments des outils de runtime | | --- | --- | | Identité JSON téléchargée et protégée | `identityFile` avec le chemin sur la machine du serveur MCP | | Profil YAML du SDK | `configPath` et/ou `profile`; sinon, la configuration par défaut et `THALOVANT_PROFILE` s'appliquent | | Identité du SDK dans l'environnement | `fromEnv: true`, avec les variables d'identité du SDK configurées dans l'environnement du serveur | Le serveur peut aussi créer une identité avec `thalovant_create_client_identity` : fournissez l'UUID du hub et un nom de fichier comme `agent.json` dans `savePath`, puis utilisez le `savedIdentityPath` retourné dans les appels au runtime. Le serveur écrit l'identité complète dans le répertoire protégé et retourne un résumé caviardé. Par exemple, une fois l'identité placée à ce chemin, appelez `thalovant_ask` avec des arguments d'outil comme ceux-ci : ```json { "identityFile": "/path/to/private/agent.json", "protocol": "https", "text": "What time is it?", "timeoutMs": 30000 } ``` Le protocole par défaut est `wss`. Les valeurs explicites `https` et `mqtt` exigent que ce transport soit activé dans l'identité et sur le hub. `thalovant_identity_status` vérifie l'identité chargée sans se connecter; `thalovant_healthcheck` se connecte et s'authentifie avant de signaler l'état du runtime. ## Restrictions de destination de l'API Les jetons d'API et les identifiants par mot de passe configurés sont liés à l'origine d'API configurée. Le `apiUrl` d'un outil authentifié ne peut pas choisir une autre origine : le serveur rejette la substitution avant de la contacter. Pour une API autohébergée, configurez son URL avec les identifiants correspondants, soit pour tout le serveur, soit pour le principal authentifié. Les origines équivalentes après normalisation sont acceptées. La découverte publique anonyme peut utiliser une URL personnalisée lorsqu'aucun identifiant d'API n'est configuré pour cet appelant. Les requêtes au plan de contrôle refusent les redirections, y compris celles qui renverraient un corps de connexion. Les requêtes authentifiées et les corps de requête exigent HTTPS; HTTP n'est permis que pour les points de terminaison de développement explicites `localhost`, `127.0.0.1` ou `[::1]`. Les URL d'API ne peuvent pas contenir d'identifiants intégrés. Lorsqu'un ancien point de terminaison redirige, définissez directement l'URL d'API finale. ## Configuration HTTP distante Le conteneur exécute Streamable HTTP sur le port `3000` et sert MCP à `/mcp`. ```bash export MCP_HTTP_AUTH_TOKEN="$(openssl rand -hex 32)" docker run --rm \ -p 127.0.0.1:3000:3000 \ -e MCP_HTTP_AUTH_TOKEN \ -e MCP_HTTP_ALLOWED_HOSTS="127.0.0.1:3000,localhost:3000" \ ghcr.io/thalovant/thalovant-mcp:0.6.3 ``` Les clients se connectent à : ```text http://127.0.0.1:3000/mcp Authorization: Bearer ``` Des vérifications d'état sont offertes à `/healthz` et `/readyz`. Configurez le client avec le même jeton que celui stocké dans `MCP_HTTP_AUTH_TOKEN`. Cet exemple donne accès à MCP; ajoutez les identifiants Thalovant par principal décrits plus bas avant d'utiliser les outils privés ou de runtime. Les routes d'état HTTP décrivent le processus MCP, tandis que `thalovant_healthcheck` vérifie une connexion à un hub. Pour les appels au runtime dans un conteneur, montez un répertoire privé et persistant pour les clés enregistrées du SDK à `/home/thalovant/.config/thalovant`, ou définissez `XDG_CONFIG_HOME` sur une racine de configuration montée. L'utilisateur `thalovant` du conteneur doit pouvoir écrire dans ce répertoire; protégez les fichiers d'identité montés avec des permissions réservées au propriétaire. Pour un point de terminaison public, définissez les valeurs exactes de l'URL publique, de l'hôte et de l'origine : ```bash export MCP_PUBLIC_URL="https://mcp.example.com" export MCP_HTTP_ALLOWED_HOSTS="mcp.example.com" export MCP_HTTP_ALLOWED_ORIGINS="https://agent.example.com" ``` ## Authentification et identifiants 1. **Gardez l'authentification bearer activée.** Par défaut, le mode HTTP exige `MCP_HTTP_AUTH_TOKEN` ou `MCP_HTTP_AUTH_TOKENS`. 2. **Utilisez la validation OAuth pour les serveurs distants partagés.** Définissez `MCP_HTTP_AUTH_MODE=jwt` avec JWKS, ou utilisez `MCP_HTTP_AUTH_MODE=introspection` pour les jetons opaques. 3. **Associez les utilisateurs à des identifiants Thalovant.** Utilisez `THALOVANT_PRINCIPAL_CREDENTIALS_FILE` ou `THALOVANT_PRINCIPAL_CREDENTIALS_DIR`. 4. **Désactivez les identifiants partagés sur les serveurs multiutilisateurs.** Gardez `THALOVANT_ALLOW_SHARED_CREDENTIALS=false`. 5. **Définissez la politique des outils.** Utilisez `MCP_TOOL_ALLOWLIST` et `MCP_TOOL_DENYLIST` pour les contrôles à l'échelle du serveur. 6. **Envoyez les journaux d'audit vers un endroit durable.** Définissez `MCP_AUDIT_LOG=stderr`, ou définissez `MCP_AUDIT_LOG=file` avec `MCP_AUDIT_LOG_FILE`. Utilisez `MCP_AUDIT_LOG=both` avec un chemin de fichier pour les deux destinations. Un chemin de fichier seul laisse la journalisation désactivée. Les arguments `identityFile`, `configPath`, `profile` et `fromEnv` des appelants distants sont désactivés par défaut. Configurez l'identité sur le serveur pour chaque principal authentifié, selon le [format de fichier d'identifiants](https://github.com/thalovant/thalovant-mcp/blob/v0.2.0/examples/principal-credentials.sample.json). En mode répertoire, les fichiers se nomment `.json`; une entrée correspondante du répertoire a préséance sur le fichier d'identifiants partagé. `MCP_HTTP_ALLOW_CLIENT_CREDENTIAL_PATHS=true` autorise les chemins choisis par l'appelant et devrait être réservé aux déploiements privés de confiance. Le serveur publie les métadonnées de ressource protégée OAuth à cette adresse : ```text https://mcp.example.com/.well-known/oauth-protected-resource ``` ## Groupes d'outils `thalovant_config_status`, `thalovant_list_public_hubs`, `thalovant_get_public_hub`, `thalovant_list_hubs` et `thalovant_get_hub`. `thalovant_identity_status`, `thalovant_healthcheck`, `thalovant_intent_inventory`, `thalovant_ask`, `thalovant_query`, `thalovant_send_action`, `thalovant_send_code`, `thalovant_emit_event` et `thalovant_wait_for_event`. `thalovant_list_memory_items`, `thalovant_get_memory_summary`, `thalovant_get_memory_item`, `thalovant_create_memory_item`, `thalovant_update_memory_item` et `thalovant_delete_memory_item`. `thalovant_create_client_identity`, `thalovant_get_operation` et `thalovant_get_analytics_overview`. `thalovant_list_marketplace_skills`, `thalovant_list_runtime_group_marketplace`, `thalovant_list_runtime_group_inventory`, `thalovant_list_runtime_groups`, `thalovant_get_runtime_group`, `thalovant_get_runtime_group_config` et `thalovant_get_hub_runtime_capabilities`. `thalovant_create_hub`, `thalovant_update_hub`, `thalovant_release_hub`, `thalovant_create_runtime_group`, `thalovant_update_runtime_group`, `thalovant_update_runtime_group_config`, `thalovant_release_runtime_group`, `thalovant_install_runtime_group_skill` et `thalovant_uninstall_runtime_group_skill`. `thalovant_set_hub_rating` et `thalovant_clear_hub_rating`. Ces outils exigent `hubs:write`, qu'un jeton du forfait Free ne peut pas porter : sur Free, évaluez les hubs dans le tableau de bord, ou utilisez un jeton d'un forfait Home ou supérieur. `thalovant_list_hub_skills`, `thalovant_list_hub_skill_history`, `thalovant_install_hub_skill`, `thalovant_update_hub_skill` et `thalovant_remove_hub_skill`. L'historique est offert à partir de `0.2.0`; les autres outils, à partir de `0.1.23`. `thalovant_create_client_identity` ne retourne aucun élément secret de l'identité dans la sortie de la conversation. Utilisez `savePath` lorsque vous voulez que l'identité complète soit écrite dans un fichier local avec le mode `0600`. Le chemin est résolu à l'intérieur de `THALOVANT_MCP_IDENTITY_DIR` (un répertoire de configuration sûr par défaut); un `savePath` absolu situé hors de cette base, ou qui utilise `..` pour en sortir, est rejeté avant la création de tout identifiant. Les groupes Skill discovery et Provisioning, ainsi que les deux outils de suppression optionnels décrits plus bas, sont offerts. La découverte est en lecture seule et fonctionne avec tous les forfaits. Le provisionnement exige `hubs:write` et un forfait payant. Pour le processus complet, la règle de l'etag et le tableau des erreurs, consultez [Provisionner des hubs](/fr/developers/provisioning/). `thalovant_update_hub` exige l'`etag` actuel du hub en entrée et n'accepte ni `name`, ni `namespace`, ni `domain`, puisque ces valeurs sont fixées à la création. Appelez d'abord `thalovant_get_hub` et transmettez le champ `etag` du corps de sa réponse. Le groupe Hub skills gère les compétences du groupe de runtime que sélectionne un hub, ce qui touche chaque hub qui partage ce groupe. Chaque outil prend l'UUID du hub dans `hubId`; les trois outils d'écriture prennent aussi l'identifiant de la compétence dans `skill`. `thalovant_install_hub_skill` accepte une `version` facultative (par défaut `latest`), `thalovant_update_hub_skill` en exige une, et `thalovant_remove_hub_skill` n'accepte aucune `version`. Les trois outils d'écriture retournent l'opération acceptée; passez `wait: true` pour la sonder toutes les 2 secondes selon la sémantique de `thalovant_get_operation`, avec un budget de sondage de 120 000 ms, sauf si `timeoutMs` indique autre chose. `thalovant_list_hub_skills` retourne l'enveloppe de la route, avec les lignes sous `data`; cet outil et le nouvel outil d'historique restent visibles en mode lecture seule. Le parcours dans l'application, les routes et le tableau des erreurs se trouvent à la page [Ajouter une compétence à un hub](/fr/manage/add-a-skill-to-a-hub/). Les requêtes et le sondage des compétences de hub passent par le SDK Node publié. Les vérifications d'annulation MCP s'appliquent toujours, et aucune nouvelle lecture d'état ne commence après l'échéance du sondage. L'échéance du sondage n'annule pas une requête HTTP déjà en cours. Si une lecture d'état échoue après l'acceptation d'une écriture, l'erreur de l'outil conserve l'identifiant de l'opération; suivez-la avec `thalovant_get_operation` au lieu de soumettre l'écriture de nouveau. ## Découverte du runtime et requêtes routées `thalovant_intent_inventory` lit le hub au moyen de son identité de runtime configurée. Fournissez de 1 à 20 étiquettes de langue et, au besoin, un `timeoutMs` par requête; sa réponse comprend les gestionnaires de repli, `fallbacks_known` et une table `may_answer`. L'établissement de la connexion peut être annulé; l'inventaire utilise ensuite des budgets par requête ou par lot, et une sonde de repli facultative distincte d'au plus 1,5 seconde. Il n'y a pas d'échéance totale unique pour l'inventaire. Une découverte inconnue ne signifie pas que le hub ne peut pas répondre. Consultez [la découverte des intentions](/fr/concepts/hub-intents/). `thalovant_query` envoie une requête routée et recueille les réponses en cascade correspondantes jusqu'à la fin ou jusqu'à son échéance. L'outil retourne les mêmes champs de réponse normalisés qu'Ask et ignore les réponses d'une autre requête. Comme Ask, il peut déclencher des actions sur le hub et il est masqué en mode lecture seule. Réutilisez un `sessionId` d'un appel à l'autre pour conserver le contexte de la conversation; chaque appel d'outil possède tout de même sa propre connexion et son propre nettoyage. Laissez `requestId` et `queryId` prendre les valeurs générées par défaut, ou fournissez de nouvelles valeurs pour chaque opération logique, y compris après une annulation. Ces identifiants mettent les réponses en correspondance et ne rendent pas les actions répétées idempotentes. `thalovant_wait_for_event` offre une attente d'événement bornée, plutôt qu'un flux d'événements persistant du SDK. `thalovant_get_operation` lit une opération retournée par le provisionnement. Vérifiez son état typé avant de considérer la ressource comme prête; `requested`, `committed` et `applied` sont des états intermédiaires. `failed` et `timed_out` signalent une fin sans succès. ## Outils destructifs `thalovant_delete_hub` et `thalovant_delete_runtime_group` sont désactivés par défaut. Ils ne sont pas seulement bloqués lorsqu'on les appelle : ils ne sont jamais enregistrés, n'apparaissent donc jamais dans la liste des outils, et un modèle ne peut ni les voir ni tenter de les utiliser. Supprimer un hub supprime aussi ses clients et ses ACL dépendants, et rien de tout cela n'est réversible. Un jeton de plan de contrôle à longue durée de vie associé à un outil de suppression toujours visible représente une catégorie de risque différente de celle d'un outil de lecture ou de mise à jour; ces deux outils sont donc optionnels. Pour les activer, définissez la variable d'environnement avant le démarrage du serveur : ```bash export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true" ``` | Règle | Valeur | | --- | --- | | Valeurs vraies acceptées | `1`, `true`, `yes` et `on`, en majuscules ou en minuscules. | | Toute autre valeur | Laisse les outils désactivés, y compris une variable non définie, vide, `0` et `false`. | | Moment de la lecture | À la construction du serveur. Redémarrez le processus du serveur avec l'environnement mis à jour après l'avoir modifié. | | Comment confirmer | `thalovant_config_status` indique `destructiveToolsEnabled` et liste les outils que contrôle l'indicateur. | Ce mécanisme est volontairement distinct de `MCP_TOOL_ALLOWLIST` et `MCP_TOOL_DENYLIST`. Ces derniers sont des filtres appliqués au moment de l'appel, où une liste d'autorisation vide signifie « tout autoriser » : ils ne peuvent donc pas exprimer un outil qui reste désactivé tant que quelqu'un ne l'active pas, ni masquer un outil de la liste des outils. Une fois l'indicateur défini, les outils de suppression redeviennent des outils ordinaires et la politique s'applique toujours; les deux couches se combinent donc : ```bash # Register delete tools, then deny their use to every principal. export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true" export MCP_TOOL_DENYLIST="thalovant_delete_hub,thalovant_delete_runtime_group" ``` Un refus global s'applique à chaque principal; le `allowedTools` d'un principal ne peut pas le contourner. Pour refuser un outil seulement à certains principaux, utilisez leurs entrées `deniedTools` et retirez cet outil de la liste de refus globale. La suppression d'un hub exige un etag actuel non vide; une valeur périmée échoue avec HTTP 412. La suppression d'un groupe de runtime échoue avec HTTP 409 tant qu'il est le groupe par défaut de l'espace de travail ou que des hubs y sont encore rattachés. Laissez ces outils désactivés, sauf si un agent a une vraie raison de supprimer des ressources Thalovant. La suppression d'un hub est irréversible. ## Restreindre les sources et les outils Depuis la version `0.1.11`, trois autres variables d'environnement restreignent ce que fera le serveur, en plus du verrou des outils destructifs décrit plus haut. Comme ce verrou, chacune est lue au démarrage du serveur et signalée par `thalovant_config_status`. **Les sources de compétences hors catalogue sont désactivées par défaut.** `thalovant_install_runtime_group_skill` installe à partir du catalogue révisé de la place de marché. Une source `git` ou une URL exécute du code que le catalogue n'a jamais révisé; ces sources sont donc rejetées, à moins que vous ne les activiez : ```bash export THALOVANT_ENABLE_GIT_SKILL_SOURCES="true" ``` Lorsque l'indicateur n'est pas défini, un `sourceType` hors catalogue échoue avec une erreur claire côté client qui nomme la variable, et aucun appel au plan de contrôle n'est fait. `thalovant_config_status` indique `gitSkillSourcesEnabled`. **Les fichiers d'identité restent dans un seul répertoire.** Lorsque `thalovant_create_client_identity` écrit dans `savePath`, le chemin est confiné à `THALOVANT_MCP_IDENTITY_DIR`; un agent ne peut donc pas déposer un fichier d'identifiants à un emplacement arbitraire, comme un dossier synchronisé ou un arbre de travail git. `thalovant_config_status` indique `identityDir`. **Le mode lecture seule masque tous les outils d'écriture.** Définissez `THALOVANT_MCP_READONLY="true"` pour n'enregistrer que les outils marqués en lecture seule, notamment la découverte, les lectures de mémoire, les analyses, l'état de l'identité, les vérifications d'état et les attentes d'événements. Ce mode masque aussi `thalovant_ask`, `thalovant_query` et les outils d'action, de code et d'émission d'événements, parce qu'une requête au hub peut déclencher des actions. `thalovant_config_status` indique `readOnly`. ## Erreurs des outils Lorsque l'API Thalovant refuse un appel au plan de contrôle, l'erreur de l'outil commence par le message d'une ligne du SDK, qui nomme le statut HTTP et peut être tronqué. Les lignes suivantes donnent la réponse complète de l'API : | Ligne | Contenu | | --- | --- | | `code:` | Le code lisible par machine de l'API, comme `platform_image_required` ou `plan_limit`. | | `detail:` | La phrase complète. Elle n'apparaît que si la première ligne a dû la raccourcir. | | `fields:` | Tous les autres membres du corps de l'erreur, en JSON compact, avec le même caviardage des secrets que les autres sorties d'outil. Pour `platform_image_required`, il s'agit de `allowed_images`, `allowed_repositories` et `refused_images`. | Un refus `platform_image_required` ou `plan_limit` reçoit un conseil qui lui correspond, et non le conseil général sur les portées, puisque l'ajout d'une portée ne change rien à l'un ou à l'autre. Ce comportement est arrivé avec la version `0.5.3`. ## Règles de validation des entrées Depuis la version `0.1.8`, le serveur valide les entrées des outils selon les mêmes limites que celles qu'applique l'API Thalovant : les valeurs invalides échouent donc avec une erreur claire côté client, au lieu d'une erreur 422 opaque de l'API. | Règle | Valeur | | --- | --- | | Taille de page de `thalovant_list_public_hubs` | Plafonnée à 48, comme le point de terminaison des hubs publics. `thalovant_list_hubs`, qui est authentifié, garde sa limite de 100. | | Références de hub dans les outils authentifiés | `thalovant_get_hub` et `thalovant_create_client_identity` exigent l'UUID du hub. Les slugs ne sont acceptés que par les outils de hubs publics, comme `thalovant_get_public_hub`. | | `title` d'un élément de mémoire | 160 caractères ou moins. | | `content` d'un élément de mémoire | 4096 caractères ou moins. | | `source` d'un élément de mémoire | 64 caractères ou moins. | | `consentScope` d'un élément de mémoire | 128 caractères ou moins. | | `consentVersion` d'un élément de mémoire | 64 caractères ou moins. | | `retentionPolicy` d'un élément de mémoire | 64 caractères ou moins. | | `query` d'une liste de mémoire | 240 caractères ou moins. | | `protocol` du runtime | `wss` (par défaut), `https` ou `mqtt`. | | `text` d'Ask, `payload` d'une action, `value` d'un code | Chaînes non vides, jusqu'à 20 000 caractères. Le `payload` d'une action est une seule chaîne, et non une commande et un objet séparés. | | `timeoutMs` du runtime | De 1 000 à 300 000 ms lorsque l'option existe; par défaut, 30 000 ms pour Ask et les attentes d'événements, et 10 000 ms pour les vérifications d'état. | `thalovant_ask` retourne `text`, `displayText`, `utterances`, `handled`, `ok`, `sessionId`, `requestId`, `displayItems`, `events` et, s'il y a lieu, `failureEvent`. Les outils d'action, de code et d'émission d'événements confirment que l'événement a été envoyé; ils n'attendent pas de réponse du hub. ## Problèmes courants | Symptôme | À vérifier d'abord | | --- | --- | | Claude ou Codex n'arrive pas à démarrer le serveur | Vérifiez que Node.js 20 ou une version plus récente est installé et que la commande utilise `npx --yes @thalovant/mcp-server@0.6.3 --stdio`. | | Les outils de hubs publics fonctionnent, mais les outils d'API privés échouent | Configurez `THALOVANT_API_TOKEN` ou un jeton de contrôle par principal correspondant, puis vérifiez `thalovant_config_status`. | | Les outils d'API fonctionnent, mais les outils de runtime échouent | Configurez une identité de hub distincte, avec son mot de passe et ses points de terminaison; un jeton d'API seul ne suffit pas. | | Le nettoyage de la session de runtime précédente a échoué | Ce processus bloque l'identité. Terminez et vérifiez le nettoyage de la session de hub précédente avant de réutiliser cette identité; redémarrer MCP ne prouve pas à lui seul que la session est fermée. | | La connexion s'ouvre, mais l'authentification expire | Vérifiez qu'aucun autre client n'utilise la même identité, et fermez le client qui possède la session existante avant de réessayer. | | L'accès au runtime échoue après un redémarrage du processus ou du conteneur | Restaurez les clés enregistrées d'origine et vérifiez les identifiants de l'identité. Ne supprimez pas les identités de hub enregistrées pour réessayer. | | Un outil échoue avec une erreur de portée | Recréez le jeton sur la page API Tokens avec les portées dont le groupe d'outils a besoin. | | La création d'un élément de mémoire échoue avec HTTP 409 `memory_limit` sur le forfait Free | Le forfait Free conserve un seul élément de mémoire. Supprimez l'élément existant, ou passez au forfait Home pour une mémoire illimitée. | | Les outils de provisionnement échouent avec HTTP 402 sur le forfait Free | L'API vérifie le forfait avant les portées. Passez à un forfait supérieur, puis créez un jeton avec `hubs:write`. | | Les outils d'évaluation échouent avec HTTP 403 sur le forfait Free | L'évaluation exige `hubs:write`, qu'un jeton du forfait Free ne peut pas porter. Évaluez le hub dans le tableau de bord, ou utilisez un jeton d'un forfait Home ou supérieur. | | `thalovant_install_runtime_group_skill` renvoie HTTP 402 sur un forfait payant | La compétence est une entrée payante du catalogue que le forfait ne couvre pas. Appelez d'abord `thalovant_list_runtime_group_marketplace` et vérifiez `installable` et `purchase_required`. | | `thalovant_update_hub` renvoie HTTP 412 | L'`etag` est absent ou périmé. Appelez de nouveau `thalovant_get_hub` et transmettez l'`etag` du corps de sa réponse. | | `thalovant_install_hub_skill` renvoie HTTP 409 ou 404 | Un 409 (`skill_version_already_installed`) signifie que le hub a déjà cette compétence dans cette version; publiez une autre version pour la mettre à jour. Un 404 avec le code `hub_without_runtime_group` signifie que le hub n'est pas encore dans un groupe de runtime; un 404 sans code signifie que `hubId` est inconnu, souvent parce qu'il s'agit d'un slug plutôt que de l'UUID. | | Les outils de suppression sont absents de la liste des outils | Ils sont optionnels. Définissez `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS` et redémarrez le serveur. Consultez [Outils destructifs](#outils-destructifs). | | Les appels renvoient HTTP 429 | Le jeton a atteint la limite de débit ou le quota d'appels de son forfait. Attendez l'intervalle indiqué par `Retry-After`, puis réessayez. | | HTTP renvoie 401 | Envoyez `Authorization: Bearer ` et vérifiez que le jeton correspond à la configuration du serveur. | | HTTP renvoie 403 pour un client dans un navigateur | Ajoutez l'origine exacte à `MCP_HTTP_ALLOWED_ORIGINS`. | | Les utilisateurs distants voient les mêmes données Thalovant | Configurez des identifiants par principal et gardez les identifiants partagés désactivés. | | Un outil risqué ne devrait pas être accessible | Ajoutez-le à `MCP_TOOL_DENYLIST`, ou utilisez une politique `deniedTools` par principal. | ## Pour la suite Consultez [Fonctions des SDK](/fr/developers/sdk-functions/) lorsque vous voulez les noms des méthodes du SDK Thalovant sous-jacent. Consultez [Provisionner des hubs](/fr/developers/provisioning/) lorsqu'un agent doit créer des hubs et des groupes de runtime. Consultez [Fichiers d'identité](/fr/developers/identity-files/) lorsque les outils de runtime ont besoin d'identifiants de hub enregistrés. ## Historique des compétences d'un runtime partagé `thalovant_list_hub_skill_history` accepte `hubId` et un `limit` entier facultatif de 1 à 200 (50 par défaut). L'outil retourne les événements et les opérations de compétences les plus récents, y compris les versions, les horodatages, les acteurs et les champs de résultat. L'outil est en lecture seule et reste accessible lorsque `THALOVANT_MCP_READONLY` est activé. Les outils de compétences de hub sélectionnent le groupe de runtime rattaché au hub. **Chaque hub qui partage ce groupe voit les mêmes changements de compétences et le même historique.** Un jeton restreint doit couvrir tous les hubs desservis; `hubs:inspect` suffit pour l'historique. Utilisez `thalovant_get_operation` pour inspecter une écriture acceptée plutôt que de la répéter lorsque l'attente échoue. ## Indications de requête, audio et mises à jour de configuration `thalovant_ask` accepte `sttLang`, un `pipeline` ordonné et `location` (`city` est obligatoire; `region`, `country`, `timezone`, `latitude` et `longitude` sont facultatifs). Ces indications s'appliquent à cette requête sans modifier la configuration du runtime enregistrée. Omettez les indications inutilisées; un pipeline vide est ignoré, et les chaînes de langue ou de ville vides sont rejetées. Ask et Query retournent la langue, les métadonnées audio et `droppedMedia`. L'audio hexadécimal intégré reste hors de la sortie texte. Définissez `includeAudio: true` pour recevoir des blocs audio MCP distincts pour les formats reconnus, ou des blocs de ressource binaire intégrée pour les formats inconnus. Avant la collecte, le SDK limite les extraits à 4 Mio chacun et à 16 Mio par réponse. La lecture relève du client; le serveur ne récupère jamais les chemins ou les URL audio fournis par une compétence. `thalovant_intent_inventory` accepte `speakable`, `sentence`, `slots` et `exampleLimit`. La limite d'exemples va de 1 à 20 par langue, avec une valeur par défaut de 2. Les patrons bruts restent accessibles; les exemples rendus retirent les formulations facultatives et conservent le classement d'origine par phrase complète. `thalovant_update_runtime_group_config` utilise `merge: true` par défaut, avec une précondition de révision, et ne réessaie que sur HTTP 412, jusqu'à trois tentatives au total. L'outil exige les portées `hubs:read` et `hubs:write` et un forfait payant. Passez `merge: false` seulement pour un remplacement inconditionnel voulu, qui exige la portée `hubs:write`, un forfait payant et une coordination avec les autres rédacteurs. Les anciennes API sans prise en charge des révisions échouent avant une écriture par fusion. Consultez [les mises à jour de configuration](/fr/developers/provisioning/). Le SDK Node sous-jacent rejette, avant l'écriture, les fusions protégées qui contiennent des entiers hors de la plage sûre de JavaScript, y compris dans les personas fournis. Il rejette aussi les valeurs non finies et les exposants numériques enregistrés qui dépassent la capacité des nombres JavaScript, ce qui évite leur conversion en `null`. Utilisez des identifiants sous forme de chaînes, ou un client qui prend en charge les entiers sans perte, pour ces valeurs de configuration. Définissez `sentence: true` pour rendre les exemples d'inventaire avec les valeurs d'exemple des emplacements selon la locale, les majuscules et la ponctuation. Cette option implique le rendu prononçable. Des `slots` explicites remplacent les valeurs d'exemple de la locale, la sélection régionale suit la correspondance d'OVOS, et la limite compte les exemples rendus uniques et non vides. Les locales inconnues conservent le texte brut. Les patrons bruts restent dans la réponse d'inventaire. Le serveur gère SIGTERM et SIGINT en fermant ses sessions MCP et ses connexions HTTP, y compris dans le conteneur publié. L'arrêt comporte une échéance d'échec de dix secondes si le nettoyage se bloque. ## Sortie d'inventaire présentable `thalovant_intent_inventory` ajoute un objet `presentation` à côté de ses champs de découverte natifs, de ses exemples et de ses indications de capacité à répondre. Cet objet regroupe les intentions sous des titres de compétences lisibles et comprend `languages_present` ainsi qu'un ordre explicite des langues des intentions. Les titres sont dérivés des identifiants; les locales du catalogue restent vides et les métadonnées du hub restent inconnues lorsque le runtime ne peut pas les fournir. Les phrases observées ne prouvent pas la prise en charge d'une locale du catalogue. Les notes conservent les requêtes refusées ou sans réponse, ainsi que la prise en charge inconnue des replis. Le serveur ne partage ni cache d'inventaire sur disque ni session gérée entre les appelants. Chaque appel d'outil conserve son bail d'identité et son cycle de nettoyage existants. ## Revendication des réponses Les résumés des réponses du runtime comprennent `pipelineIds`, `skillIds` et `claimed`, calculés par le SDK Node 0.7.1. Les identifiants de pipeline et de compétence sont des chaînes non vides, dans l'ordre de première apparition, sans doublons. Une réponse réussie qui ne contient que des identifiants de pipeline comportant le texte `fallback` (sensible à la casse) est signalée comme non revendiquée. Toute étape autre qu'un repli rend une réponse réussie revendiquée. Les réponses réussies des anciens hubs sans marques d'étape restent revendiquées. Les réponses en échec ou non traitées ne sont jamais revendiquées. Les marques mal formées qui ne sont pas des chaînes sont ignorées. Servez-vous-en comme d'un indice pour décider de poursuivre ou non une conversation. Le texte de repli et l'état de réussite existant sont conservés. Ces marques ne constituent pas une identité de pair vérifiée et ne doivent pas autoriser d'actions.