Grok MCP — Référence des compétences de l'agent
Utilisez ce fichier pour décider quel outil appeler, quel modèle utiliser et quand ne pas appeler Grok du tout.
Il n'y a pas de modèles par défaut — vous transmettez model à chaque appel et vous le choisissez délibérément :
le modèle le moins cher capable d'effectuer la tâche ; montez en gamme uniquement lorsque la qualité est insuffisante.
Quand utiliser Grok MCP vs. le faire vous-même
| Tâche | Utiliser Grok MCP | Faire vous-même |
|---|---|---|
| L'utilisateur demande explicitement Grok | ✅ toujours honorer la demande | — |
| Générer ou modifier une image | ✅ toujours | ✗ la plupart des modèles ne peuvent pas générer d'images |
| Analyser une image de fichier local | ✅ agent(model=..., image_paths=[...]) | ✗ nécessite un fichier sur disque |
| Analyse de grande base de code (>200K tokens) | ✅ agent(model=<grand-contexte>, tools=["read"]) | ✗ limite de contexte |
| Comparer votre réponse avec celle de Grok | ✅ appeler les deux | ✅ appeler les deux |
| Texte général / raisonnement (non sollicité) | ✗ coût inutile | ✅ préférable |
| Génération de code (non sollicitée) | ✗ sauf si votre modèle actuel est indisponible | ✅ préférable |
Règle par défaut : faites-le vous-même d'abord. Recourez à Grok lorsque :
- L'utilisateur demande explicitement Grok (par exemple "demande à Grok", "utilise Grok", "génère avec Grok")
- Votre modèle actuel ne peut pas effectuer la tâche (génération d'image, vision de fichier local, contexte épuisé)
- L'utilisateur demande de comparer votre réponse avec celle de Grok
Choisir un modèle — votre décision, à chaque appel
Chaque outil qui exécute un modèle Grok (agent, read avec une question, shell, search,
generate_image*) nécessite model. Il n'y a pas de rôles, pas de valeurs par défaut, pas de routeur auto.
Un modèle manquant ou inconnu échoue immédiatement avec la liste des choix valides.
D'où viennent les choix : la description de chaque outil liste le catalogue xAI actuel —
identifiant, fenêtre de contexte, prix par million de tokens (normal et en cache) et [images] pour les modèles qui
acceptent une entrée image. La liste est remplie à partir de l'API xAI en direct au démarrage du serveur ;
list_models(refresh=true) récupère à nouveau le catalogue, signale ce qui a changé et actualise les
descriptions des outils. Ne codez jamais en dur un nom de modèle ou un prix de mémoire — lisez la liste.
Étiquettes de rôle. Le serveur marque les modèles à partir du catalogue en direct, jamais par nom — donc la politique
ci-dessous survit aux permutations de modèles : cheapest (prix le plus bas), flagship (dernière génération,
la plus profonde, la plus chère), code (optimisé pour le code). Choisissez par étiquette et par les prix affichés.
Politique par défaut — commencez par le moins cher, ne montez qu'avec preuve :
- Travail de routine (questions, résumés, extraction, classification, modifications de code, révision de fichier)
→ le modèle
cheapest,reasoning_effort="low"là où le modèle l'accepte. - Montez au
flagshipuniquement lorsqu'une exécution bon marché a clairement donné une réponse insuffisante, ou que la tâche est une analyse multi-étapes approfondie sur plusieurs fichiers. Pas "pour être sûr". - Exécutions longues ou avec beaucoup d'outils :
tools=["read"]+ fichiers nommés,background=True, et unmax_cost_usdexplicite que vous avez choisi à partir de l'estimation ci-dessous — ne vous fiez jamais à la valeur par défaut du serveur. - Lisez le résultat :
cost_usd,stoppedethint. Unhintsignifie que l'exécution s'est terminée plus tôt ou était coûteuse sur un modèle phare — suivez-le (réessayez surcheapest, réduisez la tâche) au lieu de relancer le même appel.
| Besoin | Choisir |
|---|---|
| Entrée plus grande qu'environ 200K tokens | un modèle dont la fenêtre de contexte correspond — vérifiez ctx |
| Entrée image | un modèle marqué [images] |
| Génération d'image | itérez sur le modèle d'image le moins cher, rendu final sur un modèle de qualité |
Barrière de coût — obligatoire pour chaque appel agent() / read / shell / search
1. Estimez d'abord, et dites-le. Avant l'appel, écrivez une ligne à l'utilisateur :
Estimation : ~<N>K tokens d'entrée, ~<R> tours, <modèle> → ~$<X>. Pour un appel
unique minuscule (une question courte), une clause suffit ("~2K tokens, <$0,01"). Calculez-le
à partir des prix dans la description de l'outil (jamais de mémoire) :
- Appel unique (pas de
tools) :input_tokens × prix_entrée + expected_output × prix_sortie(1 token ≈ 4 caractères ; les tokens de raisonnement sont facturés comme sortie). - Boucle d'outils : chaque tour renvoie toute la conversation, donc le coût augmente avec les tours. Utilisez
tours × context_moyen × prix_cachéplus les nouveaux tokens et la sortie de chaque tour. Les valeurs passées decost_usdde cette session sont la meilleure calibration — préférez-les à la théorie. - Incertain ? Prenez la limite supérieure : c'est ce que vous passerez comme
max_cost_usdde toute façon.
2. Au-dessus de 2 $, vous avez besoin de l'acceptation de l'utilisateur. Si l'estimation dépasse 2 $, n'appelez PAS encore : montrez l'estimation, le modèle et ce qui est gagné par rapport à une exécution moins chère, et attendez un oui explicite. L'acceptation couvre cette tâche uniquement, pas les suivantes. À 2 $ ou moins, procédez sans demander.
3. Transmettez toujours max_cost_usd : estimation + environ 30 % de marge, plafonné à 2 $ sauf si l'utilisateur a
accepté plus (alors au maximum ce qu'il a accepté). La valeur GROK_MAX_COST_USD du serveur (2,5 $ par
défaut) est un plafond dur, pas un budget : un max_cost_usd plus élevé y est plafonné, donc une exécution qui a
besoin de plus doit être divisée ou l'opérateur doit relever le plafond.
4. Signalez toujours ce que le travail a consommé. Après chaque appel terminé — y compris un travail en arrière-plan
récupéré avec get_job — dites à l'utilisateur : modèle, cost_usd et tokens
(prompt / cached / completion / reasoning), plus iterations et stopped. Faites-le même
lorsque le coût est minuscule, et aussi lorsqu'une exécution a échoué ou s'est arrêtée tôt. Un travail encore running n'a pas
encore de coût — dites-le, puis signalez-le lors de la récupération. Si le coût réel a dépassé l'estimation de plus de
d'environ 50 %, dites-le aussi.
reasoning_effort (low/medium/high, certains modèles aussi none) est par appel et transmis à
l'API. La prise en charge varie selon le modèle (le catalogue ne le dit pas) : certains le rejettent, d'autres
rejettent none. Lorsque vous ne le définissez pas, un modèle flagship s'exécute à low au lieu de sa propre
valeur par défaut (coûteuse), et tout autre modèle utilise sa propre valeur par défaut ; si un modèle refuse le
paramètre, le serveur abandonne la valeur par défaut pour celui-ci. Définissez-le explicitement (high) lorsque la
profondeur compte — une valeur explicite est toujours envoyée telle quelle, et un rejet est renvoyé comme erreur API.
| Tâche | Modèle |
|---|---|
| Question rapide, résumé, extraction, classification | modèle le moins cher dans la liste |
| Génération / refactoring de code | un modèle de code s'il est listé, sinon un modèle général peu coûteux |
| Analyse approfondie, raisonnement multi-étapes, révision de nombreux fichiers | le modèle phare le plus récent (version la plus élevée) |
| Entrée plus grande qu'environ 200K tokens | un modèle dont la fenêtre de contexte correspond — vérifiez ctx |
| Entrée image | un modèle marqué [images] |
| Génération d'image | itérez sur le modèle d'image le moins cher, rendu final sur un modèle de qualité |
Référence rapide Outil → Modèle
agent(prompt, model, tools?, image_paths?, system?, conversation?, file_paths?, reasoning_effort?, max_iterations?, max_seconds?, max_cost_usd?, background=False)
L'outil unique pour envoyer du texte (et des images) à Grok.
| paramètre | défaut | notes |
|---|---|---|
model | requis | voir Choisir un modèle |
tools | [] | outils de l'espace de travail que Grok peut appeler lui-même : read, write, shell, fetch, search. Nom inconnu → erreur immédiate |
image_paths | — | images locales envoyées avec le prompt (le modèle doit être [images]) ; doit être visible par le serveur — voir Chemins |
max_iterations | 100 | tours du modèle dans la boucle d'outils (plafond du serveur — vous pouvez seulement le baisser) |
max_seconds | 1800 | budget temps réel de l'exécution (plafond du serveur) |
max_cost_usd | 2.5 | budget estimé en USD de l'exécution (plafond du serveur — une valeur plus élevée est plafonnée) |
conversation | — (sans état) | nom de tâche "<projet>/<tâche>", par exemple "grok-mcp/audit-securite" — conserve le contexte entre les appels d'une même tâche ; Grok récupère l'historique à la demande (get_recent_history/search_history). Nouvelle tâche → nouveau nom ; appel ponctuel → omettre (aucun historique conservé ; un travail en arrière-plan conserve tout de même son résultat pendant quelques jours). Le préfixe de projet est important : via HTTP, le serveur ne peut pas distinguer les projets. ≤ 200 caractères, pas de caractères de contrôle |
file_paths | — | contenus de fichiers injectés côté serveur (vous choisissez les fichiers) |
reasoning_effort | low sur flagship, sinon défaut du modèle | par appel ; une valeur explicite est envoyée telle quelle |
background | False | retourne {job_id} immédiatement ; collectez avec get_job(job_id). Non requis pour les exécutions longues — voir Limites |
Les paramètres inconnus sont rejetés avec la liste des paramètres valides.
Retourne (JSON joliment formaté) :
{
"answer": "...",
"model": "grok-4.3",
"reasoning_effort": "low",
"tokens": {"prompt": 6909, "cached": 576, "completion": 49, "reasoning": 141},
"cost_usd": 0.0085,
"tool_calls": [{"tool": "read", "args": {"path": "README.md"}, "result_chars": 22463}],
"iterations": 2,
"stopped": "answer",
"hint": "présent uniquement lorsque l'exécution s'est terminée tôt ou était coûteuse sur un modèle phare"
}
stopped indique comment la boucle s'est terminée : answer (normal), max_iterations, context (fenêtre presque
pleine), loop (le même appel d'outil répété), time (max_seconds) ou cost (max_cost_usd).
Dans tous les cas, le dernier tour s'exécute sans outils, donc answer contient toujours ce que Grok a pu
conclure de ce qu'il a rassemblé — le travail n'est jamais jeté.
Limites (variables d'environnement du serveur, valeurs par défaut)
| Limite | Défaut | Variable d'env. | Ce qui se passe |
|---|---|---|---|
| Durée d'appel au premier plan | 60 s | GROK_FOREGROUND_TIMEOUT | l'appel passe en arrière-plan : vous obtenez {job_id, status: "running", note} — collectez avec get_job. Rien n'est perdu ; vous n'atteignez jamais un délai d'attente client |
| Durée d'exécution | 1800 s | GROK_JOB_MAX_SECONDS / max_seconds | réponse finale, stopped: "time" |
| Coût d'exécution | 2,5 $ | GROK_MAX_COST_USD / max_cost_usd | réponse finale, stopped: "cost" |
| Tours du modèle | 100 | GROK_MAX_ITERATIONS / max_iterations | réponse finale, stopped: "max_iterations" |
| Entrée (prompt + file_paths + images) | 60 % de la fenêtre du modèle | GROK_INPUT_MAX_RATIO | rejeté avant tout appel API, nommant les modèles dont la fenêtre convient |
| Un résultat d'outil | 15 % de la fenêtre | GROK_TOOL_RESULT_MAX_RATIO | Grok obtient "résultat trop volumineux — lisez une plage de lignes ou grep" à la place |
| Conversation entière | 80 % de la fenêtre | GROK_CONTEXT_MAX_RATIO | anciens résultats rognés une fois, puis nouveaux refusés, puis stopped: "context" |
| Commande shell | 240 s | GROK_SHELL_TIMEOUT | commande tuée, erreur renvoyée à Grok |
Chemins
Avec la configuration Docker, le serveur ne voit que ses répertoires montés (l'espace de travail et
ASSETS_DIR) : image_paths, file_paths et les chemins que Grok lit doivent s'y trouver — les chemins du
/tmp hôte ou des blocs-notes sont invisibles ; copiez d'abord le fichier dans l'espace de travail. Un serveur stdio voit
ce que son utilisateur peut voir, limité par GROK_READ_ALLOWED_PATHS lorsqu'il est défini. Un chemin que le
serveur ne peut pas voir est rejeté immédiatement avec la liste des racines visibles.
Contexte de projet automatique : lorsque le serveur s'exécute dans un projet git (stdio),
agent()ajoute la détection de langage et de framework au prompt système. Rien n'est injecté dans la configuration Docker. Sisystemcommence déjà par[Contexte du projet], l'injection est ignorée.
Laissez Grok rassembler son propre contexte. Ne lisez pas les fichiers vous-même et ne les collez pas dans le
prompt — passez tools=["read"] (ajoutez shell pour git log/grep/tests) et décrivez ce qu'il faut
examiner. Les contenus des fichiers n'entrent alors jamais dans votre contexte :
agent(prompt="Révisez src/grok_mcp/tools/agent.py et chat.py pour la logique dupliquée.",
model="<flagship de la liste>", tools=["read", "shell"])
Limitez la lecture. Nommez les fichiers (ou un répertoire restreint) dans le prompt — "lis ce dont tu as
besoin" sur un dépôt entier est la façon dont une exécution atteint 1,7 million de tokens. Pour les gros fichiers, dites à Grok de localiser le code
avec shell grep -n et de ne lire que des plages de lignes (read avec offset/limit).
Utilisez file_paths à la place lorsque vous savez déjà exactement quels fichiers sont importants (un aller-retour, pas de boucle).
Exécutions longues et coût. Chaque tour renvoie toute la conversation ; xAI met automatiquement en cache le préfixe
inchangé (tokens.cached, facturé environ 75 % moins cher), donc les tours paient surtout pour ce qui est nouveau.
Rogner les anciens résultats coûte un échec de cache. Un troisième appel d'outil identique est refusé ; un cinquième termine
la boucle. Un appel long revient simplement sous forme de {job_id} après 60 s — puis interrogez
get_job ; background=True saute seulement cette première minute d'attente.
Images. agent(prompt="Que montre cette capture d'écran ?", model=..., image_paths=["<workspace>/capture.png"]) — le fichier doit se trouver dans un répertoire que le serveur voit (voir Chemins).
Posez une question spécifique par appel ; combinez avec tools lorsque l'image doit être comparée avec du code.
generate_image(prompt, output_path, model, aspect_ratio?, resolution?, ref_image_paths?)
model est requis — la description de l'outil liste les modèles d'image avec leur prix par image.
Discipline de coût :
- Itérez avec le modèle d'image le moins cher jusqu'à ce que le prompt soit correct, puis passez à un modèle de qualité supérieure uniquement pour le rendu final.
- Retourne
{path, model, prompt, format}.
output_path doit être un chemin absolu. Les répertoires parents sont créés automatiquement.
Avec des images de référence (les modèles de niveau qualité transfèrent mieux le style) :
- Passez
ref_image_pathslorsque la cohérence de style avec une image existante est importante. Il accepte jusqu'à 3 chemins absolus, dans l'ordre — le prompt peut les adresser positionnellement, par exemple "géométrie de la première, personnage de bord de la seconde". Chaque chemin que vous passez est transmis ; rien n'est silencieusement abandonné. - La limite par modèle (3 pour les modèles d'image actuels) est appliquée par xAI, dont le message est renvoyé textuellement si vous la dépassez.
- Les fichiers de référence sont identifiés par MIME à partir de leurs bytes magiques, donc un résultat précédent peut être réinjecté directement comme référence, quelle que soit l'extension sous laquelle il a été enregistré.
aspect_ratio(défaut"1:1") etresolution(défaut"1k", aussi"2k") s'appliquent comme sans références. La sortie n'hérite pas des proportions de l'image de référence — une référence 16:10 produit toujours un carré sauf indication contraire, donc passez les deux explicitement chaque fois que vous avez besoin de plus qu'un carré 1k.
Comparaison des coûts : votre modèle actuel vs. Grok
Pour les prix exacts de votre modèle actuel, consultez la documentation actuelle de votre fournisseur.
...