TokenLab pour les agents : modèles lisibles par machine, tarification, SDK et MCP

Un agent de codage qui choisit un ID de modèle en mémoire finira par en choisir un qui n'existe plus, et il ne le découvrira qu'après une erreur 404 ou une facture surprenante. Le MCP de TokenLab fournit à l'agent un catalogue en direct à consulter en priorité, afin qu'il puisse vérifier l'ID, le format de requête accepté et le prix avant d'écrire le moindre code d'intégration. Nous avions initialement décrit le serveur comme étant strictement en lecture seule. La documentation observée le 03/10/2026 indique le contraire ; cette version corrige donc ce point et ajoute un flux de travail détaillé.

Points clés à retenir

• Le serveur MCP de TokenLab propose trois profils : catalog (sans clé API), core et full. Seul le profil catalog ne nécessite pas de clé.
• Avec une clé, il peut également envoyer des requêtes de modèle, créer des médias, gérer des fichiers et vérifier des tâches asynchrones. Il n'est pas en lecture seule.
• Utilisez les routes tokenlab.accepted_request_formats, tokenlab.pricing, tokenlab.lifecycle et tokenlab.deliveryAvailability. Ne codez pas en dur l'ordre des recommandations.
• Les fichiers Gemini, les téléchargements reprenables et cachedContents ne sont inclus dans aucun profil MCP.
• Ne collez jamais une clé API dans un prompt ou un argument d'outil.

Ce que le serveur MCP de TokenLab apporte à un agent de codage

Selon la documentation du serveur MCP (observée le 03/10/2026), le serveur MCP de TokenLab permet à un client de parcourir les modèles et prix actuels, d'envoyer des requêtes de modèle, de créer des médias, de travailler avec des fichiers et de vérifier des tâches asynchrones. La documentation liste ces capacités :

• lister les modèles et lire les capacités d'un modèle spécifique (list_models, get_model)
• lire les prix actuels ou comparer plusieurs modèles
• envoyer des Chat Completions, des Responses, des requêtes Anthropic Messages ou Gemini
• évaluer des décisions typées avec evaluate_decisions
• créer ou modifier des images ; créer de la vidéo, de la musique, de la 3D, de la parole, de la transcription ou de la traduction
• télécharger et récupérer des fichiers via l'API /v1/files compatible avec OpenAI
• créer des embeddings ou reclasser (rerank) des documents
• vérifier et annuler les tâches asynchrones prises en charge (get_task_status pour le polling)

La documentation ne liste pas les noms des outils pour la tarification ou l'aperçu de l'API dans cette version. Notre ancien brouillon nommait get_model_pricing et get_api_overview. Vérifiez la liste des outils de votre client connecté avant de vous fier à ces deux noms.

La disponibilité des outils dépend du profil :

Profil	Clé API	Inclus
catalog	Non requise	Liste des modèles, détails des modèles, prix, comparaisons, aperçu de l'API
core	Requise pour les appels payants	Outils courants de chat, décision, média, audio, fichier, tâche, embedding, rerank et traduction
full	Requise pour les appels payants	core plus des API développeur supplémentaires

Commencez par catalog si vous souhaitez uniquement une meilleure sélection de modèles. Utilisez core lorsque le client doit créer du contenu ou appeler un modèle.

Installer le serveur MCP de TokenLab dans votre client

Le package nécessite Node.js 18.17 ou une version ultérieure et npx. Il s'exécute localement via stdio, donc aucune installation globale n'est nécessaire. Sauvegardez d'abord votre configuration active et ajoutez uniquement l'entrée TokenLab. Ces commandes proviennent de la documentation, observée le 03/10/2026.

Claude Code :

claude mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  --scope user \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Codex :

codex mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Cursor (~/.cursor/mcp.json ou .cursor/mcp.json) :

{
  "mcpServers": {
    "tokenlab": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server@0.6.26"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

VS Code utilise .vscode/mcp.json avec une clé servers et "type": "stdio". Claude Desktop utilise la même structure que Cursor dans claude_desktop_config.json. Copiez les deux depuis la page de documentation.

Pour activer les outils payants, créez une clé dans Console → API keys et définissez les deux variables dans l'environnement du serveur :

{
  "env": {
    "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
    "TOKENLAB_MCP_TOOL_PROFILE": "core"
  }
}

Ensuite, redémarrez le client et exécutez claude mcp list ou codex mcp list. Demandez à l'agent d'appeler list_models. Une liste non vide confirme que le package a démarré et a atteint TokenLab. Si une clé réelle se retrouve dans un fichier partagé, un journal ou l'historique du shell, révoquez-la et créez-en une nouvelle.

Flux de travail d'un agent : découvrir, vérifier, appeler

Voici le flux que nous utilisons. Imaginez qu'un agent soit chargé d'ajouter la génération d'images à une application Node.js. Chaque valeur ci-dessous provient de la documentation et des pages de modèles en direct observées le 03/10/2026.

1. Découvrir. Demandez la liste actuelle, avec l'outil MCP ou via HTTP simple :

{ "tool": "list_models", "arguments": { "recommended_for": "image" } }

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

Les valeurs valides pour recommended_for sont image, video, music, 3d, tts, stt, embedding, rerank et translation. Disons que l'agent choisit nano-banana-pro.

2. Vérifier les formats et le prix. Appelez get_model, ou GET /v1/models/nano-banana-pro (API du modèle en direct, observée le 03/10/2026). Il indique :

• formats de requête acceptés : gemini_generate_content, qui correspond à /v1beta/models/{model}:generateContent
• capacités : image-edit, image-to-image, text-to-image
• prix : per_request de 0,067 USD, avec une fourchette de prix de 0,067 à 0,12 (tarification mise à jour le 02/10/2026 à 16:53:30.068Z)

Un agent qui aurait supposé l'utilisation de Chat Completions aurait écrit le mauvais code. Comparez avec gpt-image-2 (API du modèle en direct). Il ne liste aucun format de requête accepté et est facturé au jeton à 3,5 USD en entrée et 21 USD en sortie par million de jetons. La structure de prix diffère selon le modèle, l'agent doit donc la lire pour chaque modèle.

3. Passer l'appel. Pour un modèle de chat, la vérification du format détermine le point de terminaison. gpt-5.6-terra accepte openai_chat_completions et openai_responses (API du modèle en direct, observée le 03/10/2026), le SDK standard fonctionne donc :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)

Envoyez explicitement l'ID du modèle choisi. La documentation indique que TokenLab ne le remplace pas silencieusement. Le client doit demander une approbation avant un appel payant si le prix ou le choix du modèle n'est pas déjà confirmé.

Pour une estimation des coûts, gpt-5.6-terra facture 0,6 USD par million de jetons en entrée jusqu'à 272 000 jetons. Un prompt de 10 000 jetons coûte alors environ 10 000 / 1 000 000 × 0,6 = 0,006 USD pour l'entrée (estimation, avant la sortie). Au-delà de 272 000 jetons en entrée, toute la requête passe au palier supérieur à 1,2 USD en entrée et 5,4 USD en sortie.

Quels champs de l'API des modèles un agent doit-il privilégier pour le routage

Lisez ces informations depuis GET /v1/models/{model} (Obtenir un modèle, observée le 03/10/2026) :

Champ	Ce que cela signifie pour le routage
tokenlab.accepted_request_formats	Quelle famille de points de terminaison utiliser : openai_chat_completions est /v1/chat/completions, openai_responses est /v1/responses, anthropic_messages est /v1/messages
tokenlab.pricing / pricing_unit	Prix public actuel et son unité de facturation, comme per_token ou per_image
tokenlab.max_input_tokens, max_output_tokens	Limites de contexte et de sortie. Pour gpt-5.6-terra : 1 050 000 et 128 000
tokenlab.supported_operations	Opérations telles que text-to-image ou image-to-video
tokenlab.lifecycle	Disponibilité, date de sortie, date de fin de vie, modèle de remplacement
tokenlab.deliveryAvailability	Support verified et official configuré. Un champ manquant signifie inconnu

Deux précautions s'appliquent. Premièrement, un format accepté confirme le point de terminaison, mais les outils et champs individuels peuvent toujours varier selon le modèle. Deuxièmement, deliveryAvailability est un support configuré, pas une garantie en temps réel. Traitez les résultats de recommended_for comme une liste restreinte, car la documentation indique de ne pas se fier à leur ordre.

Pour les prix seuls, GET /v1/models/{model}/pricing est le point de terminaison dédié. Les entrées complexes peuvent comporter des paliers. seedance-2.0, par exemple, a des prix de sortie dépendants de la résolution et de l'entrée vidéo allant de 2,04 à 6,545 USD par million de jetons (API du modèle en direct, observée le 03/10/2026).

Champs d'erreur pour guider la récupération

Sur les erreurs de Chat Completions et Responses compatibles OpenAI, le guide des erreurs (observé le 03/10/2026) liste les champs optionnels did_you_mean, suggestions, hint, retryable et retry_after. Gérez d'abord le statut HTTP et le code. Une erreur 400 model_not_found peut contenir did_you_mean. Montrez-le à l'utilisateur plutôt que d'échanger les modèles silencieusement. Une erreur 503 all_channels_failed peut avoir retryable: false, et la répéter ne servira à rien. Anthropic Messages et Gemini conservent leurs formats d'erreur natifs.

Ce que le serveur MCP ne fait pas

La documentation indique ces limites :

• Il ne change pas le fournisseur de modèle principal de votre client. Utilisez le guide de configuration propre à ce client.
• Il ne couvre pas les fichiers Gemini, les téléchargements reprenables ou cachedContents. Ceux-ci nécessitent des appels HTTP, selon Fichiers et cache Gemini.
• Ce n'est pas le Skill. Le TokenLab Skill installe des instructions avec npx skills add et ne démarre aucun serveur MCP.
• Il ne fait pas de polling pour vous en cas de timeout. Si une vérification de statut expire, ne créez pas une seconde tâche.
• Il ne rend pas les décisions fiables par lui-même. Une réponse Noul issue de evaluate_decisions est une probabilité, pas un booléen. Validez par rapport à vos propres cas étiquetés.

Le profil catalog ne peut effectuer aucun appel payant. Les outils d'image renvoient soit un résultat, soit une tâche, selon le modèle. La vidéo, la musique et la 3D renvoient toujours des tâches.

Où vous avez encore besoin des surfaces HTTP simples

Dans notre pipeline, nous avons conservé les points de terminaison de découverte HTTP aux côtés du MCP pour les agents non-MCP. https://api.tokenlab.sh/llms.txt est un aperçu compact avec une première requête, des points de terminaison courants et des conseils sur les erreurs. La documentation observée le 03/10/2026 ne couvre pas le fichier llms-full.txt ou les fichiers instantanés model-data de notre brouillon précédent. Vérifiez ces URL vous-même avant de dépendre d'elles. Pour le statut en direct et les coûts, consultez le catalogue des modèles public.

FAQ

Ai-je besoin d'une clé API pour utiliser le serveur MCP de TokenLab ?

Non, pas pour la navigation. Le profil catalog liste les modèles, détails, prix et comparaisons sans clé. Les modèles payants ou les requêtes média nécessitent une TOKENLAB_API_KEY dans l'environnement du serveur, avec le profil core ou full.

Avec quel profil MCP dois-je commencer ?

Commencez avec catalog si vous souhaitez uniquement une meilleure sélection de modèles. Passez à core lorsque le client doit appeler des modèles ou créer des médias. Utilisez full uniquement si l'agent a réellement besoin des API développeur supplémentaires.

Quels champs de modèle un agent doit-il privilégier lors du choix d'un modèle ?

Fiez-vous à accepted_request_formats pour le point de terminaison, pricing avec son unité pour le coût, les limites de jetons, supported_operations et lifecycle. Traitez deliveryAvailability comme un support configuré, pas comme une disponibilité en temps réel.

Pourquoi mon agent a-t-il reçu une erreur 503 all_channels_failed ?

L'opération peut ne pas avoir d'approvisionnement dans le palier de livraison sélectionné. Lorsque retryable est false, ne répétez pas la requête. Vérifiez la disponibilité avec GET /v1/models et choisissez un autre modèle avec l'approbation de l'utilisateur.

Le serveur MCP prend-il en charge les fichiers Gemini ou cachedContents ?

Non. La documentation indique que les fichiers Gemini, les téléchargements reprenables et cachedContents nécessitent actuellement des appels HTTP. Les outils de fichiers MCP utilisent l'API /v1/files compatible avec OpenAI.

Créez une clé dans Console → API keys, puis ajoutez le profil catalog à votre client avec les commandes ci-dessus.