Tout a commencé par une question sur Slack d’un collègue. « Tu sais comment on augmente la taille de nos runners CI ? Je ne trouve pas la doc. »
J'ai un souvenir très net : quelqu’un l’avait documenté ! Les tailles disponibles, la procédure pour changer, les contraintes. J’avais même probablement reviewé le document en question. Mais impossible de remettre la main dessus.
J’ai commencé par les suspects habituels; le mono-repo principal. Trois docs techniques existent, mais aucune ne couvre les runners. J’ai ouvert la recherche GitHub et tapé « runner size », j’ai obtenu des dizaines de résultats répartis sur une douzaine de repos - des fichiers Terraform, des workflows, des commentaires dans du code, et quelque part au milieu, noyée dans le bruit, ma doc. Elle était bien dans le repo infra.
J’ai passé bien trop de temps à retrouver un document que j’avais moi-même reviewé. Et pendant ce temps, mon collègue attendait.
Dans notre équipe, on fait les choses correctement. Notre documentation vit avec le code, organisée selon le framework Diátaxis : tutoriels, guides pratiques, référence technique et explications, chacun dans son répertoire dédié. On y ajoute nos ADRs (Architecture Decision Records) et PRDs (Product Requirement Documents), eux aussi versionnés. Chaque document est reviewé et mergé comme du code. C'est la bonne pratique.
Mais cette rigueur a un effet pervers : la documentation est bien organisée à l’intérieur de chaque repo, et totalement invisible à l’échelle de l’organisation. Personne n’a une vue transversale. Chaque développeur connaît les docs des repos sur lesquels il travaille, et ignore celles des autres.
Il nous fallait un pont entre nos agents et notre documentation dispersée.
Le Model Context Protocol est un standard ouvert qui permet à un agent IA d’appeler des outils externes. On écrit à un serveur qui déclare : « je sais chercher dans la documentation, je sais récupérer un document complet, je sais lister les repos ». N’importe quel client MCP peut ensuite utiliser ces outils.
La nuance clef : c’est l’agent qui décide quand appeler un outil. Ce n’est pas un pipeline qui s’exécute en arrière-plan. L’agent réfléchit, cherche, lit un résultat, affine sa requête, récupère un document. Exactement comme un développeur qui grep, lit, et itère.
En pratique, voici à quoi ressemble le flux :
Le serveur expose trois outils à nos agents :
La recherche full-text — L’agent envoie des mots-clés et peut filtrer par repo ou par type de document. Sous le capot, on utilise l’API GitHub Code Search — le même moteur que la barre de recherche GitHub, mais accessible programmatiquement. Les résultats reviennent avec des fragments de texte pour que l’agent puisse juger de la pertinence avant d’aller plus loin.
La récupération de document — Une fois qu’un résultat de recherche lui convient, l’agent peut récupérer le contenu complet du fichier markdown. Il obtient le texte brut, le type de document (inféré depuis le chemin), le repo source. Il a tout le contexte pour répondre.
La découverte de repos — L’agent peut lister tous les repos de l’organisation avec leur inventaire documentaire : combien de documents, quels types (ADR, PRD, spec, guide, how-to, reference, explanation...). C’est la vue transversale qui nous manquait.
Concrètement, voici ce qui se passe quand on cherche un ADR :
Quand un résultat de recherche revient, le serveur regarde le chemin du fichier et en déduit le type de document. Un fichier dans /adrs/ est un ADR. Un fichier dans /prds/ est un PRD. Un README.md est un readme. C’est simple, c’est déterministe, et ça colle parfaitement à nos conventions de nommage.
Cette classification permet à l’agent de filtrer ses recherches : « cherche-moi uniquement dans les ADRs » ou « montre-moi les specs techniques de ce repo ». Le filtrage se fait côté requête GitHub, pas en post-traitement — c’est rapide et ça ne consomme pas de token LLM inutilement.
Indexer un repo consiste à récupérer les fichiers de documentation qui nous intéressent et à les stocker directement dans le bon dossier du cache local. Chaque repo a son propre cache, indexé par le SHA du dernier commit sur main. À chaque appel, le serveur vérifie le SHA courant du repo via l'API GitHub : s'il correspond, le cache est servi; sinon, ce repo seul est ré-indexé. Dès qu'un développeur pousse du code, le cache du repository repo est automatiquement invalidé.
Résultat : pas d'appel API quand rien n'a changé, pas de contenu obsolète. Sans TTL, sans job de purge et sans base de données.
On nous demande souvent pourquoi on n'a pas mis tout ça dans un vector store. La réponse courte : nos docs sont déjà structurées et indexées par GitHub. Ajouter un pipeline RAG par-dessus serait de l'infrastructure pour un gain nul.
Évidemment, ça suppose une doc rangée. C'est précisément le point : si elle est trop en vrac pour qu'un MCP la trouve, elle l'est aussi pour vos équipes. RAG vous donnera l'illusion du contraire en quelques mois.
La question se pose aussi, pourquoi ne pas simplement wrapper la CLI GitHub. Ça marcherait, mais l'agent aurait accès à l'ensemble des commandes Github — même avec un token en lecture seule, la surface d'exposition reste large. Le MCP inverse l'approche : l'agent ne voit que les trois outils qu'on lui expose. Le périmètre n'est pas limité par les permissions du token, mais par le code du serveur. Et là où la CLI renvoie du texte que l'agent doit interpréter, le MCP renvoie des réponses structurées que l'agent consomme.
L'agent pilote. Il ne subit pas un contexte, il cherche, lit, affine, exactement comme un développeur le ferait.
Un agent IA sans contexte improvise. Il reprend des décisions architecturales qu'un ADR a déjà tranchées, ignore des conventions que toute l'équipe respecte, ou réinvente une solution alors qu'un pattern éprouvé existe.
Et le problème ne vient pas d'un manque de documentation — elle est là, bien rangée, dans chaque repo. Le problème, c'est la portée. Un agent qui travaille sur un repo ne voit que les documents de ce repo. Il ignore les specs d'un autre projet, les patterns partagés, les décisions transverses. C'est exactement le problème de mon collègue qui cherchait la doc des runners : l'information existe, mais elle est invisible depuis un autre contexte.
Le serveur MCP documentaire comble ce trou. Il donne à l'agent une vue transversale sur toute la base documentaire. Mieux on documente, plus les agents sont fiables. Le MCP est le pont qui rend ce cercle vertueux possible.
Commencez par le problème. On n’a pas choisi MCP parce que c’est nouveau ou élégant. On l’a choisi parce qu’un collègue cherchait une doc qu’on ne retrouvait plus assez vite. L’implémentation est venue après le besoin.
La meilleure infra est celle qu’on n’a pas. Zéro base de données, zéro pipeline d’indexation.
Laissez l’agent piloter. La force de MCP, c’est que l’agent construit progressivement sa compréhension. Il ne reçoit pas un blob de contexte — il explore, comme un développeur le ferait.
Le RAG n’est pas la réponse par défaut. Quand la source de données est déjà structurée et indexée, un wrapper MCP autour de l’API existante est plus simple, plus fiable, et moins cher.
Votre documentation a un nouveau public. Vos agents IA sont devenus les premiers lecteurs de vos docs. Rendez-les accessibles, et toute la chaîne en bénéficie.