Serveur MCP

Connectez Claude, Codex, Cursor et d'autres clients MCP à vos hubs Thalovant grâce au serveur MCP publié par Thalovant.

View as Markdown Open in Claude Open in ChatGPT

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

GitHubCode source, exemples, notes de sécurité et métadonnées de version.

SDK NodeLe serveur MCP s'appuie en coulisse sur le SDK Node de Thalovant.

Points de terminaison du hubComprenez le trafic WSS, HTTPS et MQTT du hub qu'utilisent les outils de runtime.

Fichiers d'identitéStockez les identifiants du hub pour les outils de runtime.

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/[email protected] --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.

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 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.

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 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 :

{
  "mcpServers": {
    "thalovant": {
      "command": "npx",
      "args": ["--yes", "@thalovant/[email protected]", "--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.

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 :

{
  "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.

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 à :

http://127.0.0.1:3000/mcp
Authorization: Bearer <token>

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 :

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

Gardez l’authentification bearer activée. Par défaut, le mode HTTP exige MCP_HTTP_AUTH_TOKEN ou MCP_HTTP_AUTH_TOKENS.
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.
Associez les utilisateurs à des identifiants Thalovant. Utilisez THALOVANT_PRINCIPAL_CREDENTIALS_FILE ou THALOVANT_PRINCIPAL_CREDENTIALS_DIR.
Désactivez les identifiants partagés sur les serveurs multiutilisateurs. Gardez THALOVANT_ALLOW_SHARED_CREDENTIALS=false.
Définissez la politique des outils. Utilisez MCP_TOOL_ALLOWLIST et MCP_TOOL_DENYLIST pour les contrôles à l’échelle du serveur.
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. En mode répertoire, les fichiers se nomment <sha256(principal-id)>.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 :

https://mcp.example.com/.well-known/oauth-protected-resource

Groupes d’outils

Découverte

thalovant_config_status, thalovant_list_public_hubs, thalovant_get_public_hub, thalovant_list_hubs et thalovant_get_hub.

Runtime

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.

Mémoire

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.

Espace de travail

thalovant_create_client_identity, thalovant_get_operation et thalovant_get_analytics_overview.

Découverte de compétences

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.

Provisionnement

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.

Évaluations

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.

Compétences de hub

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.

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.

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.

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 :

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 :

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

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 :

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/[email protected] --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.
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 <token>` 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 lorsque vous voulez les noms des méthodes du SDK Thalovant sous-jacent. Consultez Provisionner des hubs lorsqu’un agent doit créer des hubs et des groupes de runtime. Consultez Fichiers d’identité 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.

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.