Guide pour développer des extensions MCP personnalisées : de la structure du dépôt à la publication

Les extensions MCP personnalisées transforment un assistant générique en un spécialiste capable de travailler dans vos systèmes — de manière sûre, répétable et encadrée.

Ce que « extension MCP » signifie vraiment dans les dépôts MCP

Dans les dépôts MCP, une « extension » est généralement l’une des deux choses suivantes :

1. Un serveur MCP autonome que vous publiez (ou gardez privé) et qui expose des capacités — outils, ressources et prompts — via le Model Context Protocol.
2. Un module/paquet du dépôt qui aide à construire, configurer ou déployer des serveurs MCP (par exemple, une bibliothèque de gestionnaires d’auth, validation de schéma, ou modèles de déploiement).

La plupart des équipes parlent du premier cas : un serveur MCP personnalisé qui ajoute des capacités spécifiques au domaine, comme « interroger notre inventaire d’entrepôt », « ouvrir un ticket Jira », « générer un rapport de conformité » ou « résumer les appels clients de la semaine dernière ».

MCP est volontairement simple au niveau protocolaire, mais les extensions réelles nécessitent une conception soignée : périmètre, auth, sorties prévisibles, gestion des erreurs et documentation qui rendent l’extension utilisable par des humains et des modèles.

Commencez par la conception des capacités (avant d’écrire du code)

La manière la plus rapide de créer une extension désordonnée est de commencer par implémenter des endpoints. La manière la plus rapide de créer une extension fiable est de commencer par la conception des capacités.

Décidez ce que vous exposez : outils vs ressources vs prompts

Les serveurs MCP peuvent exposer trois types de capacités principales :

• Outils : fonctions appelables qui font quelque chose. Exemples : create_ticket, search_docs, run_sql_readonly.
• Ressources : données structurées pouvant être récupérées et référencées. Exemples : un arbre de fichiers, un article de base de connaissances, un enregistrement client.
• Prompts : modèles de prompt réutilisables qui guident le modèle de manière cohérente pour des tâches courantes.

Une heuristique pratique :

• Si cela change l’état ou déclenche une action : outil.
• Si c’est principalement « lire et citer » : ressource.
• Si c’est « répéter souvent ce flux de travail » : prompt.

Réduisez la surface d’exposition

Les responsables d’extensions surestiment souvent le nombre d’outils nécessaires. Commencez par moins d’outils, mais robustes et composables.

Mauvais modèle :

• create_ticket_bug
• create_ticket_task
• create_ticket_incident

Meilleur modèle :

• create_ticket avec un champ type contraint, validé côté serveur.

Votre futur vous remerciera lorsque vous devrez ajouter journalisation, limites de quota ou contrôles d’autorisation — une seule fois, pas trois fois.

Rédigez des « contrats d’outil » sérieusement

Avant l’implémentation, rédigez une page par contrat d’outil :

• Nom : stable, lower_snake_case
• But : une phrase
• Entrées : schéma avec types et contraintes
• Sorties : schéma avec exemples
• Modes d’erreur : échecs typiques et messages
• Sécurité : scopes requis, redactions, exigences d’audit
• Idempotence : que se passe-t-il si l’outil est appelé deux fois ?

Considérez ces contrats comme faisant partie de votre dépôt. Dans de nombreux dépôts MCP, ces documents deviennent votre meilleur actif de maintenance à long terme.

Choisissez une architecture d’extension qui ne vous piégera pas plus tard

Vous implémenterez typiquement un serveur MCP comme un petit service qui parle MCP sur stdio ou HTTP (selon votre stack et client). Quel que soit le transport, vous voulez une structure qui supporte :

• Ajouter des outils sans disperser les fichiers
• Auth et politique centralisées
• Validation partagée et formatage des erreurs
• Sorties déterministes
• Tests sans vraies credentials

Un layout propre pour les dépôts d’extensions MCP

Une structure largement applicable :

• src/
  • server/ (câblage MCP, enregistrement, transport)
  • tools/ (un fichier par outil ou par domaine)
  • resources/ (gestionnaires de ressources)
  • prompts/ (templates de prompts + métadonnées)
  • lib/ (auth, clients, validation, redaction, logging)
• tests/
  • unit/
  • integration/
  • fixtures/
• docs/
  • tools.md
  • resources.md
  • prompts.md
  • security.md
  • changelog.md
• examples/ (scripts minimaux montrant l’utilisation locale)
• mcp.json ou template de config (si votre écosystème l’utilise)

Cette structure se mappe proprement à la façon dont les capacités MCP sont consommées : outils/ressources/prompts sont découvrables, et votre logique de politique et de glue reste centralisée.

Rendez le « chemin heureux » ennuyeux

Une extension doit se comporter de façon prévisible même quand le modèle devient… créatif.

Visez :

• Validation stricte des entrées (rejeter les champs inconnus)
• Sorties normalisées (clés stables, types stables)
• Forme d’erreur cohérente (lisible par machine)
• Messages clairs « quoi faire ensuite » pour les erreurs récupérables

Implémentation des outils : patterns pratiques qui fonctionnent

Les outils sont là où la plupart des extensions MCP personnalisées apportent de la valeur. C’est aussi là où elles cassent.

Définissez des schémas et validez côté serveur

Même si votre client valide, votre serveur doit valider à nouveau. Traitez tout comme input non fiable.

Contraintes courantes à appliquer :

• Limites de longueur de chaîne (noms, titres, descriptions)
• Contraintes d’enum (priority : low/medium/high)
• Contraintes regex (clés de ticket, IDs clients)
• Tailles maximales de tableaux (pour stopper les explosions de payload)
• Formats de date (ISO 8601 uniquement, pour la cohérence)

Si votre stack supporte JSON Schema ou un validateur typé, utilisez-le et échouez vite.

Retournez des sorties que les modèles peuvent réutiliser de façon fiable

Les modèles fonctionnent mieux avec :

• JSON plat quand c’est possible
• IDs stables
• Champs de statut explicites
• URLs quand pertinent
• Peu de prose dans les champs destinés à un usage programmatique

Exemple de forme de sortie pour un outil d’action :

• status : success | failed
• id : ID de l’objet créé
• url : lien profond
• summary : courte ligne lisible par un humain
• next_actions : tableau optionnel de suivis recommandés

Évitez de renvoyer des réponses brutes d’API à moins de fournir aussi une vue normalisée.

Implémentez une enveloppe d’erreur standard

Une enveloppe d’erreur cohérente rend votre extension plus facile à déboguer et plus sûre à automatiser. Une bonne enveloppe inclut :

• error_code (stable, searchable)
• message (lisible par un humain)
• details (structuré, optionnel)
• retryable (booléen)
• suggested_fix (courte suggestion)

Quand un modèle rencontre une erreur, il peut décider de réessayer, de demander des données manquantes, ou d’arrêter.

Ajoutez limites de débit et timeouts tôt

Même les extensions internes peuvent involontairement DDoS des systèmes internes si elles sont invoquées en masse. Mettez des garde-fous dès le premier jour :

• Timeouts par outil (ex. 10–30 secondes)
• Politiques de retry avec backoff (attention avec les outils non idempotents)
• Limites de débit côté serveur (par utilisateur/token)
• Circuit breakers pour les pannes en aval

Implémentation des ressources : rendez les données référencables, pas seulement récupérables

Les ressources sont sous-estimées. Une bonne conception de ressource aide le modèle à citer et naviguer l’information sans transformer votre serveur en « fournisseur géant de blobs textuels ».

Privilégiez les ressources petites et linkables

Au lieu d’une ressource unique company_handbook, envisagez :

• handbook/index
• handbook/{section_id}
• handbook/search?q=...

Cela permet au modèle de récupérer seulement ce dont il a besoin et réduit le gaspillage de tokens.

Incluez des métadonnées pour la traçabilité

Les réponses de ressource devraient inclure :

• Un identifiant de ressource stable
• Horodatages de dernière mise à jour (si possible)
• Liens sources ou IDs canoniques
• Niveau d’accès (public/internal/restricted)
• Extraits optionnels plus un chemin de récupération du contenu complet

La traçabilité compte pour la conformité et pour déboguer « d’où vient cette réponse ? »

Prompts : le travailleur silencieux des grandes extensions

Les prompts en MCP ne sont pas juste « un texte utile ». Ce sont des flux de travail répétables que vous fournissez avec votre extension pour que l’assistant se comporte de manière cohérente.

Des templates de prompt utiles incluent :

• « Rédige une réponse support dans notre ton »
• « Résume un ticket pour un ingénieur »
• « Générez des notes de release à partir de titres de PR fusionnés »
• « Convertissez des résultats bruts de requête en brief exécutif »

Un template de prompt solide a :

• Un rôle et un objectif clairs
• Des entrées requises
• Un format de sortie structuré
• Des garde-fous (« Si des données manquent, demandez-les »)
• Des consignes de style qui correspondent à votre organisation

Les prompts réduisent aussi la tentation de mettre des règles métier dans les noms d’outils. Gardez la logique métier dans les outils et les politiques ; gardez l’orientation de flux dans les prompts.

Sécurité et permissions : la partie qu’on ne peut pas patcher après coup

Si votre extension touche des systèmes réels, elle a besoin d’une vraie sécurité. « C’est interne » n’est pas une stratégie.

Choisissez un modèle d’auth : délégué utilisateur vs délégué service

Deux approches courantes :

• Délégué utilisateur : l’extension agit au nom d’un utilisateur et respecte ses permissions. Idéal pour les outils de productivité qui doivent refléter l’accès utilisateur.
• Délégué service : l’extension utilise un compte de service avec des permissions scopiées. Idéal pour l’automatisation contrôlée et les tableaux de bord en lecture seule.

Le mode délégué utilisateur nécessite typiquement un échange de tokens, gestion de session et audit soigné. Le mode délégué service exige un scoping strict et peut nécessiter des outils séparés pour les actions privilégiées.

Scopage des outils par risque

Tous les outils ne se valent pas. Vous pouvez les regrouper par risque et appliquer des verrous différents :

• Lecture seule : search, list, retrieve
• Écriture : create, update
• Destructif : delete, purge, revoke
• Financier/légal : facturation, contrats, actions de conformité

Pour les outils à risque élevé, ajoutez des exigences supplémentaires :

• Champs de confirmation obligatoires
• Flux d’approbation à deux personnes (si applicable)
• Mode « dry run »
• Limites de débit serrées
• Logs d’audit détaillés

Redigez les données sensibles dans les deux sens

La redaction ne concerne pas seulement les logs sortants. Elle concerne aussi les réponses.

Si l’API en aval renvoie des secrets, des données personnelles ou des tokens, votre extension devrait :

• Supprimer les champs sensibles par défaut
• Fournir une représentation « masquée » sûre
• Exposer les détails complets seulement avec permission explicite et but clair

Journalisez pour l’audit sans divulguer de données

Une politique de logging pratique :

• Journaliser le nom de l’outil, horodatage, identité utilisateur, request ID
• Journaliser des hashes ou des comptes au lieu du contenu brut
• Stocker les payloads bruts seulement dans des sinks d’audit sécurisés, si nécessaire
• Ajouter des IDs de corrélation pour les appels en aval

Cela vous donne de la traçabilité sans transformer votre système de logs en passoire.

Tester les extensions MCP personnalisées comme un pro

La plupart des bugs d’extension ne sont pas des problèmes de syntaxe. Ce sont des problèmes d’intégration et de cas limites : champs manquants, réponses inattendues en aval, concurrence et incompatibilités de permissions.

Tests unitaires : valider schémas et formes d’erreurs

Les tests unitaires doivent couvrir :

• Le schéma rejette les champs inconnus
• Les champs requis sont appliqués
• Les contraintes d’enum
• La normalisation des sorties
• La cohérence de l’enveloppe d’erreur

Tests d’intégration : utilisez sandboxes et fixtures

Pour les tests d’intégration :

• Utilisez des sandboxes vendeurs (Jira sandbox, org de test GitHub, mode test Stripe)
• Mockez les APIs en aval quand les sandboxes ne sont pas disponibles
• Enregistrez des fixtures pour les réponses communes
• Testez les timeouts et les retries

Une bonne suite d’intégration inclut des tests de « répétition d’échec » :

• downstream 500
• downstream 429
• auth expiré
• permission denied
• données partielles renvoyées

Tests de contrat : gardez les contrats d’outil honnêtes

Vous vous souvenez de ces contrats d’outil ? Transformez-les en tests :

• Un exemple d’entrée doit passer la validation
• Un exemple de sortie doit correspondre au schéma
• Les scénarios d’erreur connus doivent produire des error_code connus

Les tests de contrat évitent les ruptures silencieuses lors de refactorings.

Documentation qui aide à la fois les humains et les modèles

Dans les dépôts MCP, la documentation n’est pas décorative. C’est la façon dont d’autres développeurs et consommateurs d’outils comprennent ce que vous avez construit.

Docs minimales à livrer :

• Quickstart : comment exécuter localement, variables d’environnement requises, comment connecter un client
• Référence des outils : entrées/sorties, exemples, codes d’erreur
• Sécurité : permissions, scopes, journalisation d’audit
• Guide opérationnel : déploiement, monitoring, réponse aux incidents
• Changelog : changements visibles par les utilisateurs et migrations

Écrivez des exemples comme s’ils allaient être copiés en production — car ils le seront.

Versioning et compatibilité ascendante : évitez les ruptures surprises

Les extensions MCP personnalisées évoluent. Le moyen le plus simple de perdre la confiance est de changer des sorties sans prévenir.

Utilisez le versioning sémantique avec discipline

Une politique viable :

• PATCH : corrections de bugs, aucun changement de schéma
• MINOR : changements additionnels (nouveaux champs optionnels, nouveaux outils)
• MAJOR : changements cassants de schéma, renommage d’outils, suppression de champs

Dépréchez avant de supprimer

Si vous devez retirer un outil ou un champ :

• Marquez-le comme déprécié dans la doc
• Maintenez-le fonctionnel pendant une fenêtre définie (30–90 jours)
• Ajoutez des avertissements dans les réponses si approprié
• Fournissez un chemin de migration (« utilisez l’outil X avec le champ Y à la place »)

C’est encore plus important quand d’autres dépôts dépendent de votre extension.

Distribution et packaging dans les dépôts MCP

La façon dont vous distribuez dépend de votre environnement :

• Serveur MCP open source publié sur GitHub
• Dépôt privé dans votre organisation
• Paquet interne distribué via un registre d’artefacts
• Image contenant déployée dans un cluster

Quelle que soit la méthode, traitez les releases comme des produits.

Checklist de release

Avant de tagger une release :

• Tests verts (unit + integration)
• Contrats d’outil à jour
• Docs à jour
• Changelog rédigé
• Revue sécurité pour les nouveaux outils
• Dashboards de monitoring mis à jour (si nécessaire)

Si votre extension se connecte à des systèmes critiques, effectuez un déploiement progressif.

Observabilité et exploitation : gardez-la en fonctionnement quand tout se complique

Le modèle ne vous dira pas que votre extension est instable. Les utilisateurs le feront — après que cela leur aura fait perdre du temps.

Metrics à capturer

Suivez au minimum :

• Nombre d’appels par outil
• Latence p50/p95/p99
• Taux d’erreur par outil et par dépendance
• Nombre de timeouts
• Déclenchements de limites de débit
• Échecs d’auth

Ajoutez des dashboards qui vous permettent de répondre à : « L’extension est-elle en panne, ou c’est le système en aval ? »

Tracer les appels en aval

Si votre extension appelle plusieurs services, le tracing distribué vous fait gagner des heures. Même des IDs de corrélation légers aident à reconstruire une chaîne de défaillance.

Dégradation sûre

Quand une dépendance est en panne, ne renvoyez pas des erreurs cryptiques. Fournissez :

• Un message clair
• Si un retry peut fonctionner
• Une alternative suggérée (mode lecture seule, données en cache)
• Un lien vers la page d’état si vous en avez une

Cela rend l’extension plus fiable même en période de stress.

Un bilan de mi-projet : l’audit « qualité d’extension »

À mi-chemin du développement, marquez une pause et faites un audit sur ces questions :

• Chaque outil peut-il être décrit en une phrase ?
• Les noms d’outils sont-ils cohérents et prévisibles ?
• Les schémas sont-ils stricts et validés ?
• Les sorties sont-elles normalisées et stables ?
• Les codes d’erreur existent-ils et mènent-ils à une action ?
• Les permissions sont-elles appliquées côté serveur ?
• Les données sensibles sont-elles rédigées ?
• Avons-nous au moins un test d’intégration par outil ?
• Un nouveau développeur comprendrait-il comment ajouter un outil en une heure ?

Si vous répondez « non » à plusieurs questions, corrigez la structure maintenant. Ça ne devient que plus difficile après.

Construire des extensions exemples : trois plans pratiques

Un guide devient réel quand vous pouvez imaginer ce que vous construisez. Voici trois plans qui correspondent à des cas d’usage courants de dépôts MCP. Chacun peut être implémenté comme un petit serveur avec une poignée d’outils et de ressources.

1. Internal Docs Navigator

   • Outils : search_docs, get_doc_section, list_collections
   • Ressources : docs/{doc_id}, docs/{doc_id}/sections/{section_id}
   • Prompts : “Answer with citations from docs”
   • Principales préoccupations : contrôle d’accès, découpage du contenu, citations, fraicheur

2. Ticketing and Incident Assistant

   • Outils : create_ticket, update_ticket, link_ticket, summarize_ticket, assign_oncall
   • Ressources : tickets/{key}, incidents/{id}
   • Prompts : “Triage and propose next steps”
   • Principales préoccupations : idempotence pour la création, permissions basées sur les rôles, logs d’audit

3. **Data Warehouse Read-Only Query Server **

   • Outils : run_query_readonly, explain_query, list_tables, describe_table
   • Ressources : schemas/{name}, tables/{name}
   • Prompts : “Write safe SQL and summarize results”
   • Principales préoccupations : application stricte du mode lecture seule, timeouts de requête, limites de résultat, masquage de PII

Ces plans ne sont pas destinés à être copiés ligne par ligne. Ils servent à montrer à quoi ressemble « petit mais complet » dans les dépôts MCP.

Gérer l’idempotence, la concurrence et les « doubles appels »

Les systèmes d’appel d’outils peuvent déclencher des appels répétés pour la même intention — parfois à cause de retries, parfois à cause de relances utilisateur, parfois à cause de reconnexions client.

Ajoutez des clés d’idempotence pour les opérations d’écriture

Pour les outils qui créent ou modifient des données, acceptez un idempotency_key optionnel :

• Si la même clé est réutilisée, renvoyez le résultat original.
• Stockez les enregistrements d’idempotence pour un TTL raisonnable.
• Documentez la durée de validité des clés.

Cela évite tickets dupliqués, factures en double, invitations d’utilisateurs en double — des échecs classiques d’extension.

Protégez contre les échecs partiels

Si votre outil effectue plusieurs étapes :

• Préférez les transactions si le backend le supporte.
• Sinon, concevez des étapes de compensation (rollback) ou un flux de « reprise ».
• Retournez des IDs intermédiaires pour que des humains puissent enquêter.

Le but n’est pas d’être parfait ; c’est d’être récupérable.

Rendre les extensions « amicales pour les modèles » sans devenir dépendant d’un modèle

Il est tentant d’adapter tout au comportement d’un modèle particulier. Résistez. Construisez des extensions agnostiques client et agnostiques modèle.

Gardez les noms d’outils et les champs littéraux

Évitez les noms mignons et les champs surchargés. Utilisez les termes déjà en usage dans votre entreprise :

• customer_id plutôt que cid
• invoice_number plutôt que inv
• priority avec un enum connu

Des noms littéraux améliorent la précision et rendent vos docs recherchables.

Mettez les règles métier dans le serveur, pas dans le prompt

Les prompts aident les modèles à suivre les règles, mais l’application appartient au code :

• Vérifications de permissions
• Approbations requises
• Transitions autorisées
• Contraintes de politique (ex. « ne jamais interroger ces tables »)

Si une règle compte, appliquez-la. Les prompts sont une guidance, pas une sécurité.

Un workflow pratique pour ajouter un nouvel outil

Quand un stakeholder demande « Peut-on ajouter un outil qui fait X ? », suivez un workflow reproductible.

1. Clarifier la tâche
   Quel est le vrai objectif de l’utilisateur ? Quel système est la source de vérité ?

2. Rédiger le contrat d’outil
   Entrées/sorties, erreurs, scope de permission.

3. Revue de sécurité
   Peut-il supprimer des données ? Exposer des PII ? Être abusé ?

4. Implémenter avec validation
   Schéma strict, sorties normalisées, enveloppe d’erreur.

5. Ajouter des tests
   Tests unitaires pour schéma et erreurs ; tests d’intégration pour l’appel en aval.

6. Documenter et livrer
   Mettre à jour la doc des outils, exemples et changelog. Tagger une release.

Ce workflow est ennuyeux — dans le bon sens. Il réduit la « connaissance tribale » et rend le développement d’extensions scalable.

Erreurs courantes dans les extensions MCP personnalisées (et comment les éviter)

Erreur : exposer un outil « run_any_command »

Un outil qui exécute des commandes ou requêtes arbitraires est une invitation aux problèmes. Même un SQL « lecture seule » arbitraire peut divulguer des données sensibles si vous oubliez une table ou une vue.

Correction :

• Fournir des requêtes contraintes ou des outils de rapport préconstruits
• Appliquer des allowlists
• Ajouter des limites de lignes et masquage de colonnes

Erreur : retourner du texte non borné

Renvoyer des blobs massifs nuit aux performances et augmente le risque que le modèle manque des détails clés.

Correction :

• Retourner des résumés plus un moyen de récupérer davantage
• Paginer
• Chunker les ressources intentionnellement

Erreur : messages d’erreur faibles

« Something went wrong » n’est pas acceptable quand un modèle orchestre des appels.

Correction :

• Standardiser les codes d’erreur
• Inclure des corrections suggérées
• Marquer clairement les erreurs retryables

Erreur : pas de plan opérationnel

Si personne ne possède le monitoring et l’on-call, l’extension se dégradera silencieusement.

Correction :

• Ajouter des dashboards de base
• Définir une ownership
• Documenter les étapes d’incident

Publier et maintenir votre extension dans le temps

Une extension MCP n’est pas « terminée » quand elle fonctionne une fois. La phase de maintenance est celle où la confiance se construit.

Traitez les changements d’API des dépendances comme un risque majeur

Si vous intégrez des fournisseurs SaaS :

• Surveillez leurs changelogs
• Épinglez les versions d’API quand c’est possible
• Ajoutez des tests d’intégration qui tournent régulièrement
• Incluez des notes de compatibilité dans vos docs

Gardez une boucle de feedback serrée avec les utilisateurs

Observez comment les gens utilisent réellement l’extension :

• Quels outils sont les plus utilisés ?
• Quels outils génèrent le plus d’erreurs ?
• Que demandent les utilisateurs à répétition qui pourrait devenir un template de prompt ?
• Où sont-ils forcés à des étapes manuelles ?

Souvent, la meilleure « nouvelle feature » n’est pas un nouvel outil — ce sont de meilleurs défauts, des sorties plus claires, ou un flux plus sûr.

Établissez des guidelines de contribution dans votre dépôt MCP

Si plusieurs équipes vont ajouter des outils, vous avez besoin de standards :

• Conventions de nommage
• Style de schéma
• Format de l’enveloppe d’erreur
• Exigences de logging et redaction
• Exigences de test
• Checklist de revue pour la sécurité

Un court CONTRIBUTING.md et un template de PR peuvent éviter des semaines de nettoyage plus tard.

Boucler la boucle : votre extension doit inspirer confiance

Une excellente extension MCP personnalisée ressemble à un collègue fiable : claire sur ce qu’elle peut faire, honnête sur ce qu’elle ne peut pas, et consistante sous pression. Construisez petit, validez tout, journalisez de façon responsable, documentez sans relâche et versionnez comme si d’autres allaient dépendre de vous — parce qu’ils le feront.

External Links

MCP developer guide | Visual Studio Code Extension API Build an MCP App - Model Context Protocol Build your MCP server – Apps SDK | OpenAI Developers Making your own MCP server in VS Code | Microsoft Learn Visual Studio Code + Model Context Protocol (MCP) Servers Getting …

External References

• Internal Docs Navigator
• and Incident Assistant
• Read Only Query Server