Du musst Confluence nicht verlassen. Verschiebe die Seiten, die deine Architektur beschreiben, lass den Rest, wo er ist — und erledige den Umzug, indem du den MCP-Server von Atlassian und den MCP-Server von Archyl mit demselben KI-Agenten verbindest.

Confluence-Architekturdocs mit MCP nach Archyl migrieren — so geht's

Diese Situation höre ich jede Woche: Ein Team führt Archyl ein, modelliert seine Systeme in C4, verknüpft ADRs und API-Verträge — und dann stellt jemand die naheliegende Frage: "Und was ist mit den 200 Seiten, die wir in Confluence haben?"

Das Erste, was gesagt werden muss, erwartet von einem Anbieter niemand: Die meisten dieser Seiten sollten in Confluence bleiben. Meeting-Notizen, Onboarding-Checklisten, das On-Call-Runbook, das Planungsdokument vom letzten Quartal. Confluence ist gut darin, und Archyl versucht gar nicht, ihm das wegzunehmen. Umziehen sollte die Teilmenge, die die Architektur beschreibt — und herauszufinden, welche Seiten das sind, ist der größte Teil der Arbeit.

Die Mechanik des Umzugs war früher der schwierige Teil. Historisch lautete die Antwort "warte auf einen Importer" oder "copy-paste dich durch einen Nachmittag". Beides nicht gerade toll. Aber im letzten Jahr hat sich etwas geändert: Beide Seiten dieser Migration sprechen jetzt MCP.

Atlassian liefert einen offiziellen Remote-MCP-Server, der Confluence und Jira für jeden KI-Agenten öffnet — mit OAuth und deinen bestehenden Berechtigungen. Und Archyl stellt seine gesamte Plattform — Dokumentation, Ordner, ADRs, das komplette C4-Modell — über einen eigenen MCP-Server bereit, 181 Tools tief.

Setz einen Agenten in die Mitte, und der Importer, auf den du gewartet hast, wird zu einem Prompt.

Welche Seiten umziehen — und welche bleiben

Mach das, bevor du irgendetwas verbindest. Mein Test lautet: Bräuchte eine neue Kollegin oder ein neuer Kollege diese Seite, um zu verstehen, wie das System funktioniert — oder um durch die erste Woche zu kommen? Das Erste gehört neben das Modell. Das Zweite gehört ins Wiki.

Damit sortiert sich ein Space in vier Stapel.

Als Dokumentation mitnehmen. Seiten, die ein System beschreiben: wie der Payment-Service gebaut ist, womit er spricht, warum eine Queue davorhängt, wie die Retry-Policy aussieht. In Archyl hängst du diese an den Container oder das System, das sie beschreiben — so tauchen sie zusammen mit dem Element auf, statt drei Klicks tief in einem Seitenbaum zu liegen.
Als ADR mitnehmen. "Warum wir X gewählt haben", RFCs, Trade-off-Analysen, die Post-Incident-Seite, die mit einer Entscheidung endete. Das sind Entscheidungen, keine Dokumentation, und Archyl behandelt sie als eigenes Objekt — mit Status und einer Verknüpfung zu dem Element, das sie betroffen haben.
In Confluence lassen. Meeting-Notizen, Sprint-Planung, Team-Handbücher, alles, was um ein Jira-Makro herum gebaut ist und in Wahrheit ein Live-Report ist. Ein Umzug bringt dir hier nichts und kostet dich das Makro.
Löschen. Jeder Space hat Seiten, die ein System beschreiben, das vor zwei Jahren abgeschaltet wurde. Eine Migration ist der einzige Anlass, bei dem sie überhaupt noch einmal jemand liest — also auch die einzige Gelegenheit, sie ehrlich zu löschen.

Erst sortieren ist das, was daraus keine Alles-oder-nichts-Migration macht. Du leerst Confluence nicht. Du ziehst eine Schicht heraus.

Was du brauchst

Einen MCP-Client. Ich nutze hier Claude Code, aber Cursor oder jeder andere MCP-kompatible Agent funktioniert genauso.
Einen Confluence-Account mit Lesezugriff auf den Space, den du migrieren willst.
Einen Archyl-API-Schlüssel — erstell ihn unter Profil → API-Schlüssel mit Schreib-Scope.

Verbinde beide Server

Zwei Befehle. Zuerst der gehostete Server von Atlassian (beim ersten Aufruf öffnet er einen Browser für OAuth):

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

Dann Archyl:

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

Das war das gesamte Setup. Der Agent kann jetzt dein Wiki lesen und deinen Architektur-Workspace schreiben.

Beschreib die Migration, statt sie zu bauen

Hier ein echter Prompt, mehr oder weniger genau der, den ich auf unserem eigenen Space verwendet habe:

Migriere den Confluence-Space "Platform Engineering" in mein
Archyl-Projekt "Aurora Commerce".

1. Liste zuerst den Seitenbaum des Spaces auf und zeig mir die
   Hierarchie — importiere noch nichts.
2. Bilde die Hierarchie mit Dokumentationsordnern nach und importiere
   dann jede Seite als Markdown. Behalte die Titel, räum die
   Formatierung auf und schreibe Links zwischen importierten Seiten
   so um, dass sie auf die Archyl-Versionen zeigen.
3. Jede Seite, die eine Entscheidung festhält — "Warum wir X gewählt
   haben", RFCs, Trade-off-Analysen — soll ein ADR werden statt ein
   normales Doc, mit dem Status accepted. Schreib das ursprüngliche
   Datum in die erste Zeile des Kontexts: "Entschieden 2024-03-11,
   migriert aus Confluence."
4. Gib mir eine Übersichtstabelle mit allem, was du erstellt hast.

Und dann schau zu, was passiert. Der Agent ruft getConfluenceSpaces und getPagesInConfluenceSpace auf, um den Space zu kartieren, läuft den Baum mit getConfluencePageDescendants ab und holt jede Seite mit getConfluencePage. Auf der Archyl-Seite spiegelt er die Struktur mit create_documentation_folder, konvertiert jede Seite zu Markdown und legt sie mit create_documentation ab, und ruft dann move_documentation auf, um sie im richtigen Ordner einzusortieren (ein Doc anzulegen und es zu platzieren sind zwei getrennte Tools). Und — das ist mein Lieblingsteil — er leitet die entscheidungsförmigen Seiten stattdessen durch create_adr.

Dieser letzte Schritt ist wichtiger, als er aussieht. In jedem Team-Wiki liegt eine Schicht versteinerter Entscheidungen, begraben unter "Dokumentation". Ein Importer würde sie eins zu eins kopieren. Ein Agent liest sie, erkennt "Warum wir von RabbitMQ weg sind" als Architekturentscheidung und legt sie dort ab, wo Entscheidungen hingehören: verknüpft mit dem Element, das sie betroffen hat, und abfragbar direkt neben deinem C4-Modell.

Die Schritt-null-Regel: erst reviewen, dann bulken

Fällt dir auf, dass der Prompt sagt "zeig mir die Hierarchie zuerst — importiere noch nichts"? Mach das. Jedes Wiki hat Archiv-Bereiche, Meeting-Notizen-Friedhöfe und eine Seite namens "TEST bitte nicht löschen" von 2019. Lass den Agenten den Baum vorschlagen, kürze ihn in einer einzigen Antwort ("überspring Archive und Meeting Notes") und lass ihn dann laufen.

Wie 200 Seiten wirklich aussehen

Es ist nicht ein Prompt und ein Nachmittag. Vier Dinge bestimmen, wie der Lauf tatsächlich verläuft, und sie vorher zu kennen, ist der Unterschied zwischen einer sauberen Migration und einer halbfertigen.

Arbeite Abschnitt für Abschnitt, nicht Space für Space. Der Agent behält den Kontext zwischen den Batches, und ein Batch, dessen Zusammenfassung du lesen kannst, ist ein Batch, den du korrigieren kannst. Zehn Seiten, prüfen, die nächsten zehn.

Atlassians Server drosselt — und zwar nicht bei der Zahl, die du erwarten würdest. Ein offenes Issue am offiziellen MCP-Server, eingereicht am 29. Mai 2026 und bis heute ohne Antwort von Atlassian, meldet 429er ab etwa 20 parallelen Aufrufen, bei einem Gesamtvolumen von nur 200 bis 300 Aufrufen über ein paar Stunden. Der Melder liest daraus, dass die Fehler eher Concurrency-Spitzen folgen als anhaltender Last. Wie hoch das echte Limit auch sein mag — die Anweisung bleibt dieselbe: Sag dem Agenten, er soll die Seiten eine nach der anderen abarbeiten, statt breit zu parallelisieren.

Ein fehlgeschlagener Batch dupliziert sich beim Neustart. Archyl erzwingt keine eindeutigen Dokumentations-Slugs. Wenn ein Batch also bei Seite sieben von zehn stirbt und du sagst "versuch's nochmal", bekommst du die ersten sechs doppelt. Lass den Agenten vor dem Retry list_documentation aufrufen und überspringen, was schon existiert.

Tiefe Bäume werden flachgeklopft. Archyl begrenzt Dokumentationsordner auf drei Ebenen. Ein tiefer verschachtelter Confluence-Baum kommt mit Maximum folder nesting depth (3 levels) reached zurück — entscheide also vorher, welche Ebenen zusammenfallen, statt es auf Seite 40 herauszufinden.

Ehrliche Einschränkungen

Anhänge reisen noch immer nicht von allein mit — aber der Grund hat die Seite gewechselt. Als dieser Beitrag zuerst erschien, hatte Archyl keinen Ort für sie. Jetzt schon: Dokumentations-Anhänge sind ausgeliefert, gestützt auf S3-kompatiblen Objektspeicher, und ein Agent mit deinem API-Schlüssel kann eine Datei direkt an ein Doc posten. Die Lücke liegt auf der Confluence-Seite. Atlassians Remote-MCP-Server hat überhaupt kein Attachment-Tool — Stand August 2026 listen die unterstützten Tools zwölf Confluence-Operationen, und keine davon fasst Dateien an; der Feature-Request ist seit März 2026 offen. Der Agent kann die Bytes also nicht über MCP holen. Über die Confluence-REST-API kann er es (GET /wiki/api/v2/pages/{id}/attachments liefert pro Datei einen downloadLink) und dann jede einzeln hinüberschieben:
```
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"
```
Die Antwort enthält ein fertiges Markdown-Snippet, das du in die Seite fallen lassen kannst. Jeder Dateityp, standardmäßig 10 MB pro Datei. Aber sei ehrlich, was das ist: ein Skript, mit einem zweiten Credential (einem Atlassian-API-Token, denn die OAuth-Session, die der MCP-Server hält, kannst du dir nicht ausleihen). Für die meisten Spaces ist es immer noch schneller, die Handvoll Diagramme, auf die es wirklich ankommt, über Archyls Editor neu hochzuladen.
ADRs tragen das Datum des Tages, an dem du sie anlegst. Keine API akzeptiert ein Entscheidungsdatum, weder MCP noch REST — eine Entscheidung von 2023 landet also mit dem heutigen Stempel. Genau deshalb schreibt der Prompt oben das ursprüngliche Datum in den Kontext. Gut zu wissen, bevor du ein Jahrzehnt an Entscheidungen auf einmal migrierst.
Dokumentation verknüpft sich nicht selbst mit deinem Modell. Der Agent kann ein ADR in einem Aufruf an ein System oder einen Container hängen (link_adr_to_element). Für Dokumentation gibt es noch kein entsprechendes MCP-Tool, importierte Docs kommen also unverknüpft an. Verknüpfe sie in der UI, oder lass den Agenten mit demselben API-Schlüssel auf /api/v1/docs/{id}/links POSTen. Überspring das nicht: Dass ein Doc neben dem Container liegt, den es beschreibt, ist der ganze Grund, warum es das Wiki verlassen hat.
Komplexe Makros degradieren. Die ausgefalleneren Confluence-Makros — Jira-Issue-Tabellen, dynamische Reports — werden zu reinem Text oder Links. Codeblöcke, Tabellen und Info-Panels konvertieren sauber.
Die Berechtigungen sind deine Berechtigungen. Der Atlassian-MCP-Server zeigt nur, was dein OAuth-User lesen darf. Das ist ein Feature.

Warum das einen klassischen Importer schlägt

Ein One-Shot-Importer bewegt Bytes. Ein Agent bewegt Bedeutung: Er strukturiert um, während er migriert, macht aus Entscheidungen ADRs, repariert kaputte Formatierung und beantwortet am Ende die Frage "was hast du übersprungen und warum".

Er macht außerdem das Sortieren überhaupt erst möglich. Kein Importer wird je eine Seite ansehen und entscheiden, dass sie auf den Stapel gehört, den du zurücklässt. Ein Agent tut das — wenn du ihm die Regel gibst.

Wie es aussieht, wenn beide laufen

Der Endzustand ist nicht ein Tool. Es ist eine Grenze, die hält:

Confluence behält den Wiki-Job. Notizen, Pläne, Handbücher, alles, was an Jira hängt. Niemandem muss gesagt werden, damit aufzuhören — genau deshalb übersteht diese Grenze den Kontakt mit dem Team.
Archyl hält die Architekturschicht. Das C4-Modell plus die Dokumentation, ADRs und API-Verträge, die es beschreiben, jeweils an dem Element, zu dem sie gehören. Wenn jemand den Payments-Container öffnet, liegen das erklärende Doc und das ADR dahinter direkt daneben.
Beides bleibt für deine Agenten erreichbar. Dein MCP-Client hat beide Server verbunden. Er kann die Architektur aus Archyl abfragen und trotzdem im selben Gespräch das Wiki nach der Planungsseite durchsuchen.

Es gibt eine Regel, die verhindert, dass das wieder auseinanderdriftet, und die sollte man einmal laut aussprechen: Wenn eine Seite ein System beschreibt, gehört sie nach Archyl. An dem Tag, an dem jemand eine neue Architekturseite in Confluence schreibt, hast du das 200-Seiten-Problem von vorn begonnen.

Leg deinen Schlüssel an, richte deinen Agenten auf beide Server und gib ihm einen Abschnitt zum Durchkauen. Die vollständige Tool-Liste steht in den MCP-Server-Docs.

Und wenn die Docs erst drüben sind, funktioniert derselbe Trick auf der Architektur selbst: Structurizr-Dateien, Terraform-Module, Mermaid-Diagramme und die Codebasis — hinein in ein C4-Modell.

Confluence-Architekturdocs mit MCP nach Archyl migrieren — so geht's - Archyl Blog