Comment utiliser un serveur MCP pour la documentation d'architecture
Les assistants de codage IA sont devenus indispensables. Claude Code vous aide à refactorer des systèmes complexes. Cursor accélère le développement de features. GitHub Copilot suggère des implémentations. Mais tous ces outils partagent un angle mort commun : ils ne connaissent pas votre architecture.
Quand vous demandez à un assistant IA d'"ajouter un nouvel endpoint au Service Utilisateur", il ne sait pas que votre Service Utilisateur communique avec un Service Auth via gRPC, stocke les données dans PostgreSQL, publie des événements sur Kafka, et a un ensemble spécifique d'exigences de sécurité documentées dans vos ADR. L'IA devine, vous corrigez, et la moitié du gain de productivité s'évapore.
Les serveurs MCP corrigent cela. Ils donnent aux assistants IA un accès structuré à votre documentation d'architecture, transformant la conception de votre système en une source de données interrogeable et actionnable. Ce guide couvre tout ce que vous devez savoir sur l'utilisation d'un serveur MCP pour la documentation d'architecture -- ce qu'est MCP, pourquoi c'est important, et comment le configurer avec Archyl.
Qu'est-ce que MCP (Model Context Protocol) ?
MCP -- le Model Context Protocol -- est un standard ouvert créé par Anthropic pour connecter les assistants IA à des outils et sources de données externes. Il définit une façon structurée pour les modèles IA de découvrir, invoquer et recevoir les résultats de capacités externes.
Pensez à MCP comme un adaptateur universel. Avant MCP, chaque assistant IA avait sa propre façon propriétaire de s'intégrer aux outils externes. MCP standardise cela, créant un protocole unique qui fonctionne à travers différents assistants IA.
Un serveur MCP est un service qui expose un ensemble d'outils via le protocole MCP. Chaque outil a un nom, une description, des paramètres d'entrée et un format de sortie. Quand un assistant IA se connecte à un serveur MCP, il découvre les outils disponibles et peut les invoquer au besoin pendant une conversation.
Pour la documentation d'architecture, cela signifie que votre modèle d'architecture devient un ensemble d'outils interrogeables et modifiables que tout assistant IA compatible MCP peut utiliser. L'IA n'a pas besoin de parser des fichiers ou de deviner la structure de votre système -- elle peut directement interroger la source de vérité faisant autorité.
Pourquoi l'architecture a besoin de MCP
La documentation d'architecture se situe à l'intersection de plusieurs besoins que MCP adresse parfaitement.
Le contexte est tout pour le développement assisté par IA
La qualité du code généré par l'IA est directement proportionnelle à la qualité du contexte dont l'IA dispose. Quand un assistant IA comprend votre architecture -- quels services existent, comment ils communiquent, quelles technologies ils utilisent, quelles contraintes s'appliquent -- il génère du code qui s'intègre naturellement dans votre système.
Sans contexte architectural, les assistants IA font des hypothèses. Ils pourraient suggérer une API REST quand votre service utilise gRPC. Ils pourraient créer une connexion directe à la base de données quand votre architecture exige de passer par une couche de service. Ils pourraient proposer un appel synchrone quand votre système utilise la communication event-driven.
MCP donne aux assistants IA accès à la vraie architecture, éliminant ces décalages.
La documentation d'architecture est des données structurées
Contrairement à la documentation libre (wikis, pages Confluence, fichiers README), la documentation d'architecture modélisée dans le framework C4 est intrinsèquement structurée. Les systèmes contiennent des containers. Les containers contiennent des components. Les éléments ont des technologies, des descriptions et des relations. Les ADR ont des statuts et des éléments affectés.
Cette structure se mappe naturellement aux outils MCP. Chaque type d'élément architectural devient une entité interrogeable. Chaque opération (list, get, create, update) devient un outil. L'assistant IA peut naviguer dans le modèle d'architecture de la même façon qu'un développeur navigue dans un système de fichiers.
La documentation devrait être bidirectionnelle
La plupart des outils de documentation sont en lecture seule du point de vue API. Vous pouvez voir les documents, mais les modifier nécessite d'ouvrir une application spécifique. MCP permet une interaction bidirectionnelle : l'assistant IA peut à la fois lire depuis et écrire dans le modèle d'architecture.
Cela signifie qu'un assistant IA peut non seulement interroger votre architecture mais aussi proposer des modifications -- ajouter un nouveau component, créer une relation, rédiger un ADR. Le développeur revoit et approuve ces changements, mais l'IA fait le travail mécanique de mise à jour de la documentation.
Le serveur MCP d'Archyl : 56 outils pour l'architecture
Archyl fournit l'une des implémentations de serveur MCP les plus complètes pour la documentation d'architecture. Avec 56 outils organisés sur tout le spectre de la modélisation d'architecture, il couvre tout, de l'interrogation du modèle C4 à la gestion des releases et au suivi du drift.
Voici un aperçu des catégories d'outils.
Interroger le modèle C4
Les outils de requête principaux permettent à l'assistant IA d'explorer votre architecture à chaque niveau :
- list_systems / get_project_c4_model -- Découvrir tous les software systems d'un projet
- list_containers / list_components -- Naviguer dans la hiérarchie C4
- list_relationships -- Comprendre comment les éléments se connectent
- get_element_technologies -- Voir la stack technologique de n'importe quel élément
- get_element_owners -- Savoir qui possède quoi
Ces outils permettent des requêtes en langage naturel sur votre architecture. Quand vous demandez "De quelles bases de données le Service de Commandes dépend-il ?", l'IA peut lister les relations du Service de Commandes, filtrer les containers de base de données, et retourner une réponse précise.
Gérer les éléments d'architecture
Les outils d'écriture permettent à l'assistant IA de modifier le modèle d'architecture :
- create_system / update_system / delete_system -- Gérer les software systems
- create_container / update_container / delete_container -- Gérer les containers
- create_component / update_component / delete_component -- Gérer les components
- create_relationship / update_relationship / delete_relationship -- Gérer les connexions
Ces outils sont particulièrement puissants pour garder la documentation à jour pendant le développement. Quand vous ajoutez un nouveau service à votre codebase, vous pouvez demander à l'assistant IA d'ajouter le container correspondant au modèle d'architecture, définir ses technologies, et créer les relations appropriées -- tout cela sans quitter votre IDE.
Architecture Decision Records
Les outils ADR intègrent la documentation des décisions dans le workflow IA :
- list_adrs / get_adr -- Interroger les décisions existantes
- create_adr / update_adr -- Créer de nouveaux ADR ou mettre à jour les existants
- link_adr_to_element -- Connecter les décisions aux éléments affectés
Quand vous discutez d'un choix technologique avec votre assistant IA, il peut vérifier les ADR existants pour les décisions liées, rédiger un nouvel ADR pour la décision en cours, et le lier aux éléments architecturaux pertinents.
Contrats d'API et Event Channels
Les outils de documentation d'intégration couvrent les frontières de services :
- list_api_contracts / create_api_contract -- Gérer les spécifications API
- list_event_channels / create_event_channel -- Modéliser la communication asynchrone
- link_api_contract / link_event_channel -- Connecter les specs aux éléments
Ces outils aident à maintenir la connexion entre architecture et implémentation. Quand vous créez un nouvel endpoint API, l'IA peut vérifier si un contrat d'API existe pour ce service et suggérer de le mettre à jour.
Documentation et collaboration
Les outils de documentation plus larges supportent les workflows d'équipe :
- create_documentation / update_documentation -- Gérer la documentation projet
- create_comment / list_comments -- Annoter les éléments d'architecture
- list_flows / create_flow -- Documenter les flux utilisateurs et systèmes
- get_drift_score / compute_drift_score -- Vérifier la précision de la documentation
Releases et métriques
Les outils opérationnels connectent l'architecture à la livraison :
- create_release / list_releases -- Suivre les déploiements
- get_dora_metrics / get_dora_trend -- Mesurer la performance d'ingénierie
- list_environments -- Comprendre les cibles de déploiement
Exemples concrets : MCP en action
Voici des exemples concrets de comment les développeurs utilisent le serveur MCP d'Archyl dans leur workflow quotidien.
Exemple 1 : Interroger les systèmes depuis Claude Code
Vous travaillez dans Claude Code et avez besoin de comprendre l'architecture avant de faire des changements :
Vous : Quels systèmes et containers notre projet a-t-il ?
Claude : Laissez-moi vérifier votre architecture.
[Appelle list_systems, puis list_containers pour chaque système]
Votre projet "E-Commerce Platform" a 3 systèmes :
1. E-Commerce Platform (software_system)
- API Gateway (Go, Kong)
- User Service (Go, PostgreSQL)
- Order Service (Java, PostgreSQL)
- Product Service (Node.js, MongoDB)
- Notification Service (Python, Redis)
- Event Bus (Kafka)
2. Stripe (external_system)
- Passerelle de traitement des paiements
3. SendGrid (external_system)
- Service d'email transactionnel
L'IA retourne des données réelles de votre architecture documentée, pas une hallucination.
Exemple 2 : Créer des components depuis Cursor
Vous ajoutez un nouveau module à un service et voulez le documenter :
Vous : Je viens d'ajouter un component RateLimiter à l'API Gateway.
Il utilise Redis et la bibliothèque golang.org/x/time/rate.
Peux-tu l'ajouter à notre architecture ?
Cursor : Je vais ajouter ça à votre modèle C4.
[Appelle create_component avec name="RateLimiter",
container="API Gateway", technologies=["Redis", "Go"]]
[Appelle create_relationship du RateLimiter
vers le container Redis]
Fait. J'ai ajouté le component RateLimiter à l'API Gateway
et créé une relation vers votre container Redis.
La documentation est mise à jour en quelques secondes, sans quitter l'IDE.
Exemple 3 : Vérifier le drift avant un refactoring
Avant un effort majeur de refactoring, vous voulez savoir à quel point la documentation est précise :
Vous : Quel est notre score de drift actuel ? Y a-t-il des
services non documentés ?
Claude : Laissez-moi vérifier.
[Appelle get_drift_score]
[Appelle get_drift_details]
Votre score de drift est de 78/100 (Bon).
Problèmes détectés :
- Le Search Service tourne en production mais n'est pas
documenté dans votre modèle C4
- L'Analytics Service a 2 relations non documentées
vers le Data Warehouse
- La liste des technologies de l'API Gateway manque "Redis"
(récemment ajouté pour le rate limiting)
Voulez-vous que je corrige ces problèmes ?
L'IA identifie exactement ce qui est obsolète et peut le corriger automatiquement.
Exemple 4 : Rédiger un ADR
Pendant une discussion de conception sur le passage de REST à gRPC pour la communication interne entre services :
Vous : Nous envisageons de passer la communication interne entre
services de REST à gRPC. Peux-tu rédiger un ADR et vérifier
si nous avons des décisions existantes à ce sujet ?
Claude : Laissez-moi d'abord vérifier les ADR existants.
[Appelle list_adrs]
J'ai trouvé un ADR lié :
- ADR-007 : "Use REST for all internal APIs" (Statut : Accepté)
Décidé il y a 18 mois.
Je vais rédiger un nouvel ADR pour le remplacer.
[Appelle create_adr avec title="Migrate Internal
Communication from REST to gRPC"]
ADR-015 créé avec :
- Contexte : La communication actuelle basée sur REST ajoute
un overhead de sérialisation...
- Décision : Adopter gRPC avec Protocol Buffers pour toute
nouvelle communication interne entre services...
- Statut : Proposé
- Remplace : ADR-007
Voulez-vous que je le lie aux services concernés ?
L'IA vérifie les décisions liées, rédige un nouvel ADR, et propose de le lier aux éléments d'architecture pertinents.
Exemple 5 : Comprendre l'impact avant des changements
Avant de modifier un service, vous voulez comprendre le rayon d'impact :
Vous : Je dois changer le schéma de base de données du Service
de Commandes. Qu'est-ce qui dépend du Service de Commandes ?
Claude : Laissez-moi tracer les dépendances.
[Appelle list_relationships filtré par Order Service]
[Appelle get_element_owners pour les éléments dépendants]
Le Service de Commandes a ces dépendants :
- API Gateway -> Order Service (REST, gestion des commandes)
- Order Service -> Payment Service (gRPC, traitement des paiements)
- Order Service -> Event Bus (publie OrderCreated,
OrderUpdated, OrderCancelled)
- Notification Service consomme les événements Order depuis l'Event Bus
- Analytics Service consomme les événements Order depuis l'Event Bus
Propriétaires :
- Order Service : Équipe Plateforme
- Payment Service : Équipe Paiements
- Notification Service : Équipe Plateforme
- Analytics Service : Équipe Data
Les changements de schéma pourraient affecter le Payment Service
(dépendance directe) et tout consommateur d'événements Order.
Je recommande de coordonner avec l'Équipe Paiements et l'Équipe Data.
Configurer le serveur MCP d'Archyl
Démarrer avec le serveur MCP d'Archyl ne prend que quelques minutes. Voici comment le configurer pour les assistants IA les plus courants.
Configuration pour Claude Code
Ajoutez le serveur MCP Archyl à votre configuration Claude Code :
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
Une fois configuré, Claude Code découvre automatiquement les 56 outils et peut les utiliser dans toute conversation.
Configuration pour Cursor
Cursor supporte les serveurs MCP via ses paramètres. Ajoutez Archyl dans la section MCP :
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
Après avoir ajouté la configuration, redémarrez Cursor. Les outils Archyl apparaissent dans la liste des outils MCP, et Cursor peut les utiliser pendant la génération de code et le refactoring.
Configuration pour d'autres outils compatibles MCP
Tout outil qui supporte le protocole MCP peut se connecter au serveur MCP d'Archyl. Le serveur expose un endpoint MCP standard avec découverte d'outils, donc les clients compatibles détectent et listent automatiquement les outils disponibles.
Génération de clé API
Générez votre clé API MCP depuis le dashboard Archyl :
- Naviguez vers les paramètres de votre organisation
- Allez dans la section API
- Créez une nouvelle clé API avec les permissions appropriées
- Copiez la clé dans votre configuration de serveur MCP
Nous recommandons de créer des clés API séparées pour différents usages (ex. : une pour Claude Code, une pour CI/CD) afin de pouvoir les faire tourner indépendamment.
Bonnes pratiques pour la documentation d'architecture pilotée par MCP
Commencer en lecture seule
Quand vous configurez le serveur MCP pour la première fois, commencez avec des requêtes en lecture seule. Familiarisez-vous avec la capacité de l'assistant IA à explorer votre architecture avant d'activer les opérations d'écriture. Cela construit la confiance dans la précision et la fiabilité de l'outil.
Revoir les changements générés par l'IA
Quand l'assistant IA crée ou modifie des éléments d'architecture, revoyez les changements avant de les considérer comme définitifs. Les fonctionnalités d'historique et de version d'Archyl vous permettent de voir ce qui a changé et de revenir en arrière si nécessaire. L'IA est un assistant puissant, mais les décisions architecturales devraient toujours avoir une supervision humaine.
Combiner MCP avec l'architecture as code
MCP et l'architecture as code sont complémentaires. Utilisez MCP pour les requêtes interactives et les mises à jour rapides pendant le développement. Utilisez l'architecture as code (le fichier archyl.yaml) pour les définitions faisant autorité, versionnées, qui passent par la revue de code. Les deux approches se renforcent mutuellement.
Utiliser MCP dans les revues de code
Pendant les revues de code, demandez à l'assistant IA de vérifier si les changements de code s'alignent avec l'architecture documentée. "Ce nouvel endpoint API correspond-il au contrat API documenté pour ce service ?" ou "Ces requêtes de base de données passent-elles par la couche de service comme documenté ?" L'IA peut valider le code par rapport au modèle d'architecture en temps réel.
Former votre équipe aux outils disponibles
Le plus grand frein à l'adoption de MCP est la méconnaissance. La plupart des développeurs ne réalisent pas quelles questions l'IA peut répondre sur leur architecture. Partagez des exemples, créez un aide-mémoire de requêtes utiles, et démontrez les workflows MCP lors des réunions d'équipe.
Le futur de la documentation d'architecture pilotée par l'IA
Les serveurs MCP représentent un changement fondamental dans la façon dont les équipes interagissent avec la documentation d'architecture. Au lieu que la documentation soit un artefact passif que les développeurs lisent (ou plus souvent, ne lisent pas), elle devient un participant actif dans le workflow de développement.
Quand votre assistant IA peut interroger l'architecture avant de générer du code, vérifier la conformité après les changements, et mettre à jour la documentation à mesure que le système évolue, la barrière entre "travailler sur le système" et "documenter le système" disparaît.
La documentation d'architecture cesse d'être quelque chose que vous maintenez séparément et devient quelque chose qui est tissé dans chaque interaction de développement. Chaque question que vous posez à l'IA, chaque changement de code que vous faites, chaque discussion de conception que vous avez -- tout cela peut être informé par et reflété dans le modèle d'architecture.
C'est le futur qu'Archyl construit. Le serveur MCP est le pont entre le développement alimenté par l'IA et la documentation d'architecture structurée. Et avec 56 outils couvrant l'intégralité de la modélisation d'architecture, il est suffisamment complet pour supporter n'importe quel workflow dont votre équipe a besoin.
Démarrez avec le serveur MCP d'Archyl et donnez à votre assistant IA le contexte architectural qui lui manquait.