Notes pratiques : Le coût caché de « simplement ajouter un .mcp.json »
Guide pratique détaillé : le coût caché de « simplement ajouter un .mcp.json » – contrats, vérifications et emplacements pour du code intégrable destinés aux équipes utilisant ce modèle.
Les notes suivantes reconstituent une approche pratique pour aborder le sujet « Le coût caché de “il suffit d’ajouter un .mcp.json” ». L’accent est mis sur les contrats, les vérifications et les placeholders de code à insérer, plutôt que sur une présentation motivante. Lors de la phase d’aperçu, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le projet passe de la démonstration aux environnements partagés.
Comment les schémas d’outils s’intègrent dans votre contexte
Les schémas des outils How enter stage fonctionnent le mieux lorsqu’ils sont considérés comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de rollback avant d’élargir le périmètre. Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les flags fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Exposez des outils dotés de schémas restreints et de labels explicites indiquant leurs effets secondaires. Les hôtes doivent savoir quels appels modifient l’état du système avant de les valider automatiquement.
{
"name": "slack_send_message",
"description": "Send a message to a Slack channel or user",
"inputSchema": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Channel ID or name to send the message to"
},
"text": {
"type": "string",
"description": "The message content to send"
},
"thread_ts": {
"type": "string",
"description": "Optional thread timestamp to reply in a thread"
}
},
"required": ["channel", "text"]
}
}
La taxe de base inévitable
La taxe de référence que vous définites fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple réussi, un cas d’échec ainsi que la note de réversion avant d’élargir le périmètre. Documentez en même temps le parcours optimal et celui de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Fournissez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant de valider automatiquement.
Les chiffres réels : un .mcp.json typique
Une étape fonctionne le mieux lorsque l’on la considère comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et une note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’erreur doit pointer vers une seule responsabilité plutôt qu’un processus embrouillé. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement. Une étape fonctionne le mieux lorsque l’on la considère comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et une note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce du coût évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"]
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}
Pourquoi cela cause plus de dommages que ne le suggère le coût en dollars
Pour la phase « Pourquoi cela fait plus mal », définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les flags fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.
1. Les schémas des outils concurrencent votre conversation pour la même fenêtre de temps fixe.
Pour l’étape de concurrence des schémas d’outil 1, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez ensemble le parcours idéal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie du produit, et non d’une amélioration ultérieure. Authentifiez au niveau du gateway et réautorisez au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.
2. Plus d’outils augmentent la latence et les erreurs de sélection.
Pour les outils 2 More, avant de modifier le code lors d’une augmentation de phase, il convient de définir les entrées, le responsable de l’étape et les critères d’arrêt. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Préférer des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Authentifier au niveau du gateway et réautoriser au niveau du plan de données. Un simple token porteur ne constitue pas une frontière entre les tenants. Pour les outils 2 More, avant de modifier le code lors d’une augmentation de phase, il convient de définir les entrées, le responsable de l’étape et les critères d’arrêt. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Enregistrer les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts permet d’éviter des factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés.
3. Le démarrage du serveur ajoute une latence en plus du coût des tokens.
Lorsque vous travaillez sur l’étape « Le démarrage du serveur ajoute », notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système. Mémorisez les instructions du système stables ainsi que les schémas des outils. Envoyer à nouveau un préambule identique est une source fréquente de gaspillage.
Comment Claude Code atténue déjà ce problème
Lorsque vous travaillez sur la phase « How Claude Code already stage », notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, déboguer des boucles d’agent prend des heures.
The following deferred tools are now available via ToolSearch.
Their schemas are NOT loaded - calling them directly will fail
with InputValidationError. Use ToolSearch with query
"select:<name>[,<name>...]" to load tool schemas before calling them:
mcp__plugin_slack_slack__slack_send_message
mcp__plugin_slack_slack__slack_read_channel
mcp__plugin_github_github__list_recent_viewer_prs
...
Que pouvez-vous faire à ce sujet
Lors de l’étape « Ce que vous pouvez faire », notez d’abord les éléments requis par le contrat : les entrées nécessaires, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité et non un processus embrouillé. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, le débogage de boucles d’agent prend des heures inutilement.
1. Vérifiez le coût du schéma de votre outil
Lors de l’étape 1 « Auditer votre outil », notez d’abord les conditions requises : les entrées nécessaires, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez les terminations partielles silencieuses. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, les boucles d’analyse des erreurs perdent des heures précieuses.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! }
});
const client = new Client({ name: "audit", version: "1.0.0" });
await client.connect(transport);
const { tools } = await client.listTools();
console.log(`Server exposes ${tools.length} tools`);
let totalTokens = 0;
for (const tool of tools) {
const schemaStr = JSON.stringify(tool);
// ~3-4 chars per token for JSON; this is a rough lower bound
const estimatedTokens = Math.ceil(schemaStr.length / 3.5);
totalTokens += estimatedTokens;
console.log(` ${tool.name}: ~${estimatedTokens} tokens`);
}
console.log(`\nEstimated context cost: ~${totalTokens} tokens/turn`);
console.log(`(For exact counts, use Anthropic's token counting API)`);
await client.close();
2. Utiliser des configurations au niveau du projet
Lors de la réalisation de l’étape 2 « Utiliser des configurations définies au niveau du projet », notez d’abord les exigences : entrées requises, signal de succès, et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le projet passe de l’environnement de démonstration à des environnements partagés. Conservez le nom outil, l’hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, le débogage des boucles d’agent prend des heures inutilement.
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"]
}
}
}
3. Préférez les serveurs qui exposent moins d’outils, bien définis
Lorsque vous travaillez sur les 3 serveurs de préparation préférés, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, le débogage des boucles d’agent prend des heures inutilement.
4. Mettez en œuvre un chargement différé si vous développez un client
Lorsque vous travaillez sur l’étape 4 consistant à mettre en œuvre le chargement différé, notez d’abord les exigences : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et les procédures de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations apportées ultérieurement. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, les boucles d’analyse des erreurs perdent des heures précieuses.
// What goes into the system prompt (cheap, ~5-8 tokens per tool):
const toolDirectory = tools.map(t => t.name);
const systemPrompt = `Available tools (use ToolSearch to load): ${toolDirectory.join(", ")}`;
// What goes into the API request's tools parameter (expensive):
// Only include tools the model has explicitly requested via ToolSearch
const activeTools: ToolSchema[] = [];
// When the model calls ToolSearch("slack_send_message"):
function loadTool(name: string) {
const schema = cachedSchemas.get(name);
if (schema) activeTools.push(schema);
}
// API call only pays for activeTools, not all 200
const response = await anthropic.messages.create({
tools: activeTools, // 1-4 tools, not 200
system: systemPrompt,
messages: conversation,
});
Le verdict
Lors de la phase « The verdict », notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, les boucles de débogage perdent des heures. Lors de la phase « The verdict », notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Notez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés.
Liste de contrôle opérationnelle
Pour l’étape de la liste de contrôle opérationnelle, définissez les entrées, le responsable de l’étape et les critères d’achèvement avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché.
Considérez cette étape comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définissez des vérifications de succès et refusez toute exécution partielle silencieuse.
Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple jeton porteur ne constitue pas une frontière entre les environnements.
Rédigez un petit manuel d’utilisation : comment rotationner les clés, comment vider la file d’attente, comment revenir en arrière après une dernière ingestion.
Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés.
Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un jeton porteur seul ne constitue pas une frontière entre les tenants.
Au préalable de promouvoir la pile logicielle, figez les versions, conservez un enregistrement de référence pour le chemin critique, et confirmez les étapes de rollback. Les environnements partagés nécessitent des limites de débit, des vérifications de tenant, ainsi qu’un responsable clair pour la rotation des secrets. Préférez une fiabilité solide à des démonstrations brillantes mais ponctuelles.
Note de batch pour 06d5cd938e01 : gardez les clés du fournisseur hors du répertoire, fixez un plafond pour les tokens par session, et stockez les enregistrements à côté des fichiers d’évaluation afin que les remplacements ultérieurs de modèles restent comparables.