Vous n'avez pas à quitter Confluence. Déplacez les pages qui décrivent votre architecture, laissez le reste où il est, et faites la migration en connectant le serveur MCP d'Atlassian et celui d'Archyl au même agent IA.

Comment migrer vos docs d'architecture Confluence vers Archyl avec MCP

Voici une situation dont on me parle chaque semaine. Une équipe adopte Archyl, modélise ses systèmes en C4, lie ses ADRs et ses contrats d'API — puis quelqu'un pose la question évidente : « Et les 200 pages qu'on a dans Confluence ? »

La première chose à dire est celle que personne n'attend d'un éditeur : la plupart de ces pages devraient rester dans Confluence. Comptes-rendus de réunion, checklists d'onboarding, le runbook d'astreinte, le document de planification du trimestre dernier. Confluence est bon pour ça, et Archyl ne cherche pas à le lui prendre. Ce qui doit bouger, c'est le sous-ensemble qui décrit l'architecture — et déterminer quelles pages en font partie, c'est l'essentiel du travail.

C'est la mécanique du déplacement qui était autrefois la partie difficile. Historiquement, la réponse était « attendez un importateur » ou « copiez-collez pendant un après-midi ». Aucune des deux n'est satisfaisante. Mais quelque chose a changé cette dernière année : les deux côtés de cette migration parlent désormais MCP.

Atlassian propose un serveur MCP distant officiel qui expose Confluence et Jira à n'importe quel agent IA, avec OAuth et vos permissions existantes. Et Archyl expose toute sa plateforme — documentation, dossiers, ADRs, le modèle C4 au complet — via son propre serveur MCP, fort de 181 outils.

Placez un agent au milieu, et l'importateur que vous attendiez devient un prompt.

Quelles pages migrent, et lesquelles restent

Faites ce tri avant de connecter quoi que ce soit. Le test que j'utilise : un nouvel arrivant aurait-il besoin de cette page pour comprendre comment le système fonctionne, ou pour survivre à sa première semaine ? Le premier cas a sa place à côté du modèle. Le second a sa place dans le wiki.

Cela range un espace en quatre piles.

À migrer en documentation. Les pages qui décrivent un système : comment le service de paiement est construit, avec quoi il parle, pourquoi il y a une file d'attente devant lui, quelle est sa politique de retry. Dans Archyl, vous les attachez au container ou au système qu'elles décrivent, si bien qu'elles apparaissent avec l'élément au lieu d'être à trois clics dans une arborescence de pages.
À migrer en ADR. « Pourquoi on a choisi X », RFCs, analyses de compromis, la page de post-mortem qui s'est terminée par une décision. Ce sont des décisions, pas de la documentation, et Archyl les traite comme un objet différent, avec un statut et un lien vers l'élément qu'elles ont affecté.
À laisser dans Confluence. Comptes-rendus de réunion, planification de sprint, manuels d'équipe, tout ce qui est bâti autour d'une macro Jira et qui est en réalité un rapport vivant. Les déplacer ne vous apporte rien et vous coûte la macro.
À supprimer. Chaque espace contient des pages décrivant un système décommissionné il y a deux ans. Une migration est la seule occasion où quelqu'un les relira un jour, donc c'est la seule chance que vous aurez de les supprimer honnêtement.

Trier d'abord, c'est ce qui empêche l'opération de devenir une migration tout-ou-rien. Vous ne videz pas Confluence. Vous en extrayez une couche.

Ce qu'il vous faut

Un client MCP. J'utiliserai Claude Code ici, mais Cursor ou tout agent compatible MCP fonctionne de la même manière.
Un compte Confluence avec un accès en lecture à l'espace que vous voulez migrer.
Une clé API Archyl — créez-en une dans Profil → Clés API avec le scope écriture.

Connectez les deux serveurs

Deux commandes. D'abord, le serveur hébergé d'Atlassian (il ouvre un navigateur pour l'OAuth à la première utilisation) :

claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp/authv2

Puis Archyl :

claude mcp add --transport http archyl https://api.archyl.com/mcp \
  --header "X-API-Key: your_api_key"

C'est toute la configuration. L'agent peut désormais lire votre wiki et écrire dans votre espace de travail d'architecture.

Décrivez la migration, ne la construisez pas

Voici un vrai prompt, plus ou moins celui que j'ai utilisé sur notre propre espace :

Migre l'espace Confluence "Platform Engineering" dans mon projet
Archyl "Aurora Commerce".

1. Liste l'arborescence des pages de l'espace et montre-moi d'abord
   la hiérarchie — n'importe rien pour l'instant.
2. Recrée la hiérarchie avec des dossiers de documentation, puis
   importe chaque page en markdown. Garde les titres, nettoie le
   formatage, et réécris les liens entre pages importées pour qu'ils
   pointent vers les versions Archyl.
3. Toute page qui consigne une décision — "Pourquoi on a choisi X",
   RFCs, analyses de compromis — doit devenir un ADR plutôt qu'une
   simple doc, avec un statut accepted. Mets la date d'origine dans
   la première ligne du contexte : "Décidé le 2024-03-11, migré
   depuis Confluence."
4. Donne-moi un tableau récapitulatif de tout ce que tu as créé.

Regardez ce qui se passe ensuite. L'agent appelle getConfluenceSpaces et getPagesInConfluenceSpace pour cartographier l'espace, parcourt l'arborescence avec getConfluencePageDescendants, et récupère chaque page avec getConfluencePage. Côté Archyl, il reproduit la structure avec create_documentation_folder, convertit chaque page en markdown et la dépose avec create_documentation, puis appelle move_documentation pour la ranger dans le bon dossier (créer une doc et la placer sont deux outils distincts). Et — c'est ma partie préférée — il aiguille les pages qui ressemblent à des décisions vers create_adr à la place.

Cette dernière étape compte plus qu'il n'y paraît. Le wiki de chaque équipe abrite une couche de décisions fossilisées enfouies sous « Documentation ». Un importateur les copierait telles quelles. Un agent les lit, reconnaît « Pourquoi on a quitté RabbitMQ » comme une décision d'architecture, et la range là où les décisions doivent vivre : liée à l'élément qu'elle a affecté, et interrogeable à côté de votre modèle C4.

La règle de l'étape zéro : relisez avant d'importer en masse

Remarquez que le prompt dit « montre-moi d'abord la hiérarchie — n'importe rien pour l'instant ». Faites-le. Chaque wiki a ses sections d'archives, ses cimetières de comptes-rendus de réunion, et une page « TEST ne pas supprimer » datant de 2019. Laissez l'agent proposer l'arborescence, élaguez-la en une réponse (« ignore Archive et Meeting Notes »), puis laissez-le tourner.

À quoi ressemblent vraiment 200 pages

Ce n'est pas un prompt et un après-midi. Quatre choses déterminent le déroulement réel de l'opération, et les connaître à l'avance fait la différence entre une migration propre et une migration à moitié faite.

Travaillez section par section, pas espace par espace. L'agent garde le contexte entre les lots, et un lot dont vous pouvez lire le résumé est un lot que vous pouvez corriger. Dix pages, on vérifie, dix suivantes.

Le serveur d'Atlassian throttle, et pas au seuil auquel on s'attendrait. Une issue ouverte sur le serveur MCP officiel, déposée le 29 mai 2026 et toujours sans réponse d'Atlassian, signale des 429 au-delà d'une vingtaine d'appels en parallèle, pour un volume total de seulement 200 à 300 appels sur quelques heures. D'après son auteur, les erreurs suivent les pics de concurrence plutôt que la charge soutenue. Quelle que soit la vraie limite, la consigne reste la même : dites à l'agent de traiter les pages une par une plutôt que de les paralléliser.

Relancer un lot échoué le duplique. Archyl n'impose pas l'unicité des slugs de documentation : si un lot meurt à la page sept sur dix et que vous dites « réessaie », vous obtenez deux exemplaires des six premières. Demandez à l'agent d'appeler list_documentation et d'ignorer ce qui existe déjà avant de réessayer.

Les arborescences profondes sont aplaties. Archyl limite les dossiers de documentation à trois niveaux. Une arborescence Confluence imbriquée plus profondément renvoie Maximum folder nesting depth (3 levels) reached : décidez donc quels niveaux fusionner avant de commencer, plutôt que de le découvrir à la page 40.

Limites honnêtes

Les pièces jointes ne voyagent toujours pas toutes seules, et la raison a changé de camp. À la première publication de cet article, Archyl n'avait nulle part où les mettre. Ce n'est plus le cas : les pièces jointes de la documentation sont livrées, adossées à un stockage objet compatible S3, et un agent qui détient votre clé API peut poster un fichier directement sur une doc. Le manque est du côté Confluence. Le serveur MCP distant d'Atlassian n'a aucun outil de pièce jointe — en août 2026, la liste des outils supportés compte douze opérations Confluence et aucune ne touche aux fichiers, et la demande de fonctionnalité est ouverte depuis mars 2026. L'agent ne peut donc pas récupérer les octets via MCP. Il peut les récupérer via l'API REST de Confluence (GET /wiki/api/v2/pages/{id}/attachments renvoie un downloadLink par fichier) puis les pousser un par un :
```
curl -X POST https://api.archyl.com/api/v1/docs/$DOC_ID/attachments \
  -H "X-API-Key: $ARCHYL_API_KEY" \
  -F "file=@architecture-overview.png"
```
La réponse contient un extrait markdown prêt à coller dans la page. N'importe quel type de fichier, 10 Mo chacun par défaut. Mais soyez lucide sur ce que c'est : un script, avec un second identifiant (un token API Atlassian, puisque la session OAuth que détient le serveur MCP n'est pas à vous pour l'emprunter). Pour la plupart des espaces, re-téléverser via l'éditeur d'Archyl la poignée de diagrammes qui comptent vraiment reste la réponse la plus rapide.
Les ADRs sont datés du jour où vous les créez. Aucune API n'accepte de date de décision, ni en MCP ni en REST : une décision prise en 2023 arrive donc estampillée aujourd'hui. C'est pour ça que le prompt ci-dessus écrit la date d'origine dans le contexte. Bon à savoir avant de migrer dix ans de décisions d'un coup.
La documentation ne se lie pas toute seule à votre modèle. L'agent peut attacher un ADR à un système ou à un container en un seul appel (link_adr_to_element). Il n'existe pas encore d'outil MCP équivalent pour la documentation : les docs importées arrivent donc sans lien. Liez-les dans l'interface, ou demandez à l'agent de faire un POST sur /api/v1/docs/{id}/links avec la même clé API. Ne sautez pas cette étape : une doc posée à côté du container qu'elle décrit, c'est toute la raison pour laquelle elle a quitté le wiki.
Les macros complexes se dégradent. Les macros les plus sophistiquées de Confluence — tableaux d'issues Jira, rapports dynamiques — deviennent du texte brut ou des liens. Les blocs de code, tableaux et panneaux d'info se convertissent proprement.
Les permissions sont vos permissions. Le serveur MCP d'Atlassian n'expose que ce que votre utilisateur OAuth peut lire. C'est une fonctionnalité.

Pourquoi c'est mieux qu'un importateur classique

Un importateur one-shot déplace des octets. Un agent déplace du sens : il restructure pendant qu'il migre, transforme les décisions en ADRs, répare le formatage mort, et répond à « qu'est-ce que tu as ignoré et pourquoi » une fois terminé.

Il rend aussi le tri possible. Aucun importateur ne regardera jamais une page pour décider qu'elle appartient à la pile que vous laissez derrière vous. Un agent le fera, si vous lui donnez la règle.

À quoi ça ressemble quand les deux tournent

L'état final n'est pas un outil unique. C'est une frontière qui tient :

Confluence garde le travail de wiki. Notes, plannings, manuels, tout ce qui est lié à Jira. Personne n'a besoin qu'on lui dise d'arrêter de s'en servir, et c'est pour ça que la frontière survit au contact de l'équipe.
Archyl détient la couche architecture. Le modèle C4, plus la documentation, les ADRs et les contrats d'API qui le décrivent, chacun attaché à l'élément auquel il appartient. Quand quelqu'un ouvre le container de paiement, la doc qui l'explique et l'ADR qui le justifie sont juste là.
Les deux restent accessibles à vos agents. Votre client MCP a les deux serveurs connectés. Il peut interroger l'architecture dans Archyl et chercher quand même la page de planning dans le wiki, dans la même conversation.

Il y a une règle qui empêche tout ça de dériver à nouveau, et elle mérite d'être dite une fois à voix haute : quand une page décrit un système, elle va dans Archyl. Le jour où quelqu'un écrit une nouvelle page d'architecture dans Confluence, vous avez recommencé le problème des 200 pages.

Créez votre clé, pointez votre agent vers les deux serveurs, et donnez-lui une section à mâcher. La liste complète des outils est dans la documentation du serveur MCP.

Et une fois les docs migrées, la même astuce fonctionne sur l'architecture elle-même : fichiers Structurizr, modules Terraform, diagrammes Mermaid et code source, transformés en modèle C4.

Comment migrer vos docs d'architecture Confluence vers Archyl avec MCP - Archyl Blog