Non devi abbandonare Confluence. Sposta le pagine che descrivono la tua architettura, lascia il resto dov'è, e fai il trasloco collegando il server MCP di Atlassian e il server MCP di Archyl allo stesso agent AI.

Come migrare la documentazione di architettura da Confluence ad Archyl con MCP

Ecco una situazione che sento raccontare ogni settimana. Un team adotta Archyl, modella i suoi sistemi in C4, collega ADR e contratti API — e poi qualcuno fa la domanda ovvia: "E le 200 pagine che abbiamo su Confluence?"

La prima cosa da dire è quella che da un vendor non se l'aspetta nessuno: la maggior parte di quelle pagine dovrebbe restare su Confluence. Verbali di riunione, checklist di onboarding, il runbook di reperibilità, il documento di pianificazione dello scorso trimestre. Confluence è bravo a fare questo e Archyl non sta cercando di portarglielo via. Quello che deve spostarsi è il sottoinsieme che descrive l'architettura, e capire quali pagine siano è gran parte del lavoro.

Un tempo la parte difficile era la meccanica dello spostamento. Storicamente la risposta era "aspetta un importer" oppure "copia-incolla per un pomeriggio intero". Nessuna delle due è granché. Ma qualcosa è cambiato nell'ultimo anno: entrambi i lati di quella migrazione ora parlano MCP.

Atlassian pubblica un server MCP remoto ufficiale che espone Confluence e Jira a qualsiasi agent AI, con OAuth e i tuoi permessi esistenti. E Archyl espone l'intera piattaforma — documentazione, cartelle, ADR, tutto il modello C4 — attraverso il proprio server MCP, con 181 strumenti.

Metti un agent nel mezzo, e l'importer che stavi aspettando diventa un prompt.

Quali pagine si spostano e quali restano

Fallo prima di collegare qualsiasi cosa. Il test che uso io: una persona appena arrivata avrebbe bisogno di questa pagina per capire come funziona il sistema, o per superare la prima settimana? Il primo caso sta accanto al modello. Il secondo sta nel wiki.

Questo divide uno space in quattro mucchi.

Spostala come documentazione. Le pagine che descrivono un sistema: com'è costruito il servizio di pagamento, con cosa parla, perché davanti c'è una coda, qual è la retry policy. In Archyl le attacchi al container o al sistema che descrivono, così emergono insieme all'elemento invece di stare a tre clic di distanza in un albero di pagine.
Spostala come ADR. "Perché abbiamo scelto X", RFC, analisi di trade-off, la pagina di post-incident finita con una decisione. Sono decisioni, non documentazione, e Archyl le tratta come un oggetto diverso, con uno status e un collegamento all'elemento che hanno toccato.
Lasciala su Confluence. Verbali di riunione, pianificazione degli sprint, manuali del team, qualunque cosa costruita intorno a una macro Jira che in realtà è un report vivo. Spostarle non ti dà nulla e ti costa la macro.
Cancellala. Ogni space contiene pagine che descrivono un sistema dismesso due anni fa. Una migrazione è l'unica occasione in cui qualcuno le rileggerà, quindi è l'unica occasione che avrai per cancellarle onestamente.

Smistare prima è ciò che impedisce a tutto questo di diventare una migrazione tutto-o-niente. Non stai svuotando Confluence. Ne stai estraendo uno strato.

Cosa ti serve

Un client MCP. Qui userò Claude Code, ma Cursor o qualsiasi agent compatibile con MCP funziona allo stesso modo.
Un account Confluence con accesso in lettura allo space che vuoi migrare.
Una chiave API Archyl — creane una in Profilo → Chiavi API con scope di scrittura.

Collega entrambi i server

Due comandi. Prima, il server hosted di Atlassian (apre un browser per l'OAuth la prima volta che lo usi):

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

Poi Archyl:

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

Il setup è tutto qui. L'agent ora può leggere il tuo wiki e scrivere nel tuo workspace di architettura.

Descrivi la migrazione, non costruirla

Ecco un prompt reale, più o meno quello che ho usato sul nostro space:

Migra lo space Confluence "Platform Engineering" nel mio progetto
Archyl "Aurora Commerce".

1. Elenca l'albero delle pagine dello space e mostrami prima la
   gerarchia — non importare ancora nulla.
2. Ricrea la gerarchia con cartelle di documentazione, poi importa
   ogni pagina come markdown. Mantieni i titoli, ripulisci la
   formattazione e riscrivi i link tra le pagine importate in modo
   che puntino alle versioni Archyl.
3. Ogni pagina che registra una decisione — "Perché abbiamo scelto X",
   RFC, analisi di trade-off — deve diventare un ADR invece di un
   semplice documento, con status accepted. Metti la data originale
   nella prima riga del contesto: "Deciso il 2024-03-11, migrato da
   Confluence."
4. Dammi una tabella riassuntiva di tutto quello che hai creato.

Guarda cosa succede dopo. L'agent chiama getConfluenceSpaces e getPagesInConfluenceSpace per mappare lo space, percorre l'albero con getConfluencePageDescendants e recupera ogni pagina con getConfluencePage. Sul lato Archyl replica la struttura con create_documentation_folder, converte ogni pagina in markdown e la deposita con create_documentation, poi chiama move_documentation per sistemarla nella cartella giusta (creare un documento e collocarlo sono due strumenti separati). E — questa è la mia parte preferita — instrada le pagine a forma di decisione verso create_adr.

Quest'ultimo passaggio conta più di quanto sembri. Il wiki di ogni team ha uno strato di decisioni fossilizzate sepolte sotto "Documentazione". Un importer le copierebbe così come sono. Un agent le legge, riconosce "Perché abbiamo abbandonato RabbitMQ" come una decisione di architettura e la archivia dove le decisioni devono stare: collegata all'elemento che ha toccato e interrogabile accanto al tuo modello C4.

La regola dello step zero: rivedi prima di importare in massa

Nota che il prompt dice "mostrami prima la gerarchia — non importare ancora nulla". Fallo. Ogni wiki ha sezioni di archivio, cimiteri di verbali di riunione e una pagina chiamata "TEST non cancellare" del 2019. Lascia che l'agent proponga l'albero, potalo in una sola risposta ("salta Archivio e Verbali di riunione"), poi lascialo andare.

Com'è davvero fare 200 pagine

Non è un prompt e un pomeriggio. Ci sono quattro cose che determinano come va davvero l'esecuzione, e conoscerle in anticipo è la differenza tra una migrazione pulita e una lasciata a metà.

Lavora sezione per sezione, non space per space. L'agent mantiene il contesto tra un batch e l'altro, e un batch di cui riesci a leggere il riepilogo è un batch che puoi correggere. Dieci pagine, controlli, altre dieci.

Il server di Atlassian applica throttling, e non al numero che ti aspetteresti. Una issue aperta sul server MCP ufficiale, segnalata il 29 maggio 2026 e ancora senza risposta da Atlassian, riporta 429 dopo circa 20 chiamate in parallelo, a fronte di un volume totale di sole 200-300 chiamate nell'arco di un paio d'ore. Secondo chi l'ha aperta, gli errori seguono i picchi di concorrenza più che il carico prolungato. Qualunque sia il limite reale, l'istruzione è la stessa: di' all'agent di lavorare le pagine una alla volta invece di aprirsi a ventaglio.

Rilanciare un batch fallito lo duplica. Archyl non impone slug univoci per la documentazione, quindi se un batch muore alla pagina sette su dieci e tu dici "riprova", ti ritrovi due copie delle prime sei. Chiedi all'agent di chiamare list_documentation e di saltare ciò che esiste già prima di riprovare.

Gli alberi profondi vengono appiattiti. Archyl limita le cartelle di documentazione a tre livelli. Un albero Confluence annidato più in profondità torna con Maximum folder nesting depth (3 levels) reached, quindi decidi quali livelli collassare prima di iniziare, invece di scoprirlo alla pagina 40.

Limiti, onestamente

Gli allegati continuano a non viaggiare da soli, e il motivo ha cambiato lato. Quando questo post è uscito la prima volta, Archyl non aveva dove metterli. Ora sì: gli allegati della documentazione sono disponibili, appoggiati su object storage compatibile S3, e un agent che ha la tua chiave API può caricare un file direttamente su un documento. La lacuna è dal lato Confluence. Il server MCP remoto di Atlassian non ha alcuno strumento per gli allegati — ad agosto 2026 l'elenco degli strumenti supportati conta dodici operazioni Confluence e nessuna tocca i file, e la feature request è aperta da marzo 2026. Quindi l'agent non può recuperare i byte via MCP. Può recuperarli via API REST di Confluence (GET /wiki/api/v2/pages/{id}/attachments restituisce un downloadLink per ogni file) e poi spingerli uno per uno:
```
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 risposta arriva con uno snippet markdown già pronto da incollare nella pagina. Qualsiasi tipo di file, 10 MB ciascuno di default. Ma sii chiaro su cosa sia: uno script, con una seconda credenziale (un API token Atlassian, dato che la sessione OAuth che tiene il server MCP non è tua da prendere in prestito). Per la maggior parte degli space, ricaricare dall'editor di Archyl la manciata di diagrammi che contano davvero resta la risposta più veloce.
Gli ADR portano la data del giorno in cui li crei. Nessuna API accetta una data di decisione, né MCP né REST, quindi una decisione presa nel 2023 atterra timbrata con la data di oggi. È per questo che il prompt qui sopra scrive la data originale nel contesto. Meglio saperlo prima di migrare un decennio di decisioni in un colpo solo.
La documentazione non si collega da sola al tuo modello. L'agent può attaccare un ADR a un sistema o a un container con una sola chiamata (link_adr_to_element). Per la documentazione non esiste ancora uno strumento MCP equivalente, quindi i documenti importati arrivano scollegati. Collegali dalla UI, oppure fai fare all'agent una POST su /api/v1/docs/{id}/links con la stessa chiave API. Non saltare questo passaggio: un documento che sta accanto al container che descrive è l'intera ragione per cui ha lasciato il wiki.
Le macro complesse degradano. Le macro più sofisticate di Confluence — tabelle di issue Jira, report dinamici — diventano testo semplice o link. Blocchi di codice, tabelle e pannelli informativi si convertono senza problemi.
I permessi sono i tuoi permessi. Il server MCP di Atlassian espone solo ciò che il tuo utente OAuth può leggere. Ed è un pregio.

Perché batte un importer classico

Un importer one-shot sposta byte. Un agent sposta significato: ristruttura mentre migra, trasforma le decisioni in ADR, sistema la formattazione morta e risponde a "cosa hai saltato e perché" quando ha finito.

Ed è anche ciò che rende possibile lo smistamento. Nessun importer guarderà mai una pagina per decidere che appartiene al mucchio che ti lasci alle spalle. Un agent lo farà, se gli dai la regola.

Com'è quando girano entrambi

Lo stato finale non è un tool solo. È un confine che tiene:

Confluence si tiene il lavoro da wiki. Note, piani, manuali, tutto ciò che è legato a Jira. Nessuno deve sentirsi dire di smettere di usarlo, ed è proprio per questo che il confine sopravvive al contatto con il team.
Archyl tiene lo strato di architettura. Il modello C4, più la documentazione, gli ADR e i contratti API che lo descrivono, ciascuno attaccato all'elemento a cui appartiene. Quando qualcuno apre il container dei pagamenti, il documento che lo spiega e l'ADR che ci sta dietro sono proprio lì.
Entrambi restano raggiungibili dai tuoi agent. Il tuo client MCP ha collegati tutti e due i server. Può interrogare l'architettura su Archyl e cercare comunque nel wiki la pagina di pianificazione, nella stessa conversazione.

C'è una regola che impedisce a tutto questo di tornare alla deriva, e vale la pena dirla ad alta voce una volta: quando una pagina descrive un sistema, va in Archyl. Il giorno in cui qualcuno scrive una nuova pagina di architettura su Confluence, hai ricominciato daccapo il problema delle 200 pagine.

Configura la tua chiave, punta il tuo agent verso entrambi i server e dagli una sezione da masticare. L'elenco completo degli strumenti è nella documentazione del server MCP.

E una volta che i documenti sono di là, lo stesso trucco funziona sull'architettura stessa: file Structurizr, moduli Terraform, diagrammi Mermaid e la codebase, dentro un modello C4.

Come migrare la documentazione di architettura da Confluence ad Archyl con MCP - Archyl Blog