Você não precisa abandonar o Confluence. Mova as páginas que descrevem a sua arquitetura, deixe o resto onde está, e faça a mudança conectando o servidor MCP da Atlassian e o servidor MCP do Archyl ao mesmo agente de IA.

Como Migrar Seus Docs de Arquitetura do Confluence para o Archyl com MCP

Aqui está uma situação que eu escuto toda semana. Um time adota o Archyl, modela seus sistemas em C4, vincula seus ADRs e contratos de API — e então alguém faz a pergunta óbvia: "E as 200 páginas que a gente tem no Confluence?"

A primeira coisa a dizer é a parte que ninguém espera ouvir de um fornecedor: a maioria dessas páginas deveria continuar no Confluence. Atas de reunião, checklists de onboarding, o runbook de plantão, o doc de planejamento do trimestre passado. O Confluence é bom nisso e o Archyl não está tentando tomar esse espaço. O que deve migrar é o subconjunto que descreve a arquitetura — e descobrir quais páginas são essas é a maior parte do trabalho.

A mecânica da mudança é que costumava ser a parte difícil. Historicamente, a resposta era "espere por um importador" ou "copie e cole por uma tarde inteira". Nenhuma das duas é boa. Mas algo mudou no último ano: os dois lados dessa migração agora falam MCP.

A Atlassian oferece um servidor MCP remoto oficial que expõe o Confluence e o Jira para qualquer agente de IA, com OAuth e suas permissões existentes. E o Archyl expõe a plataforma inteira — documentação, pastas, ADRs, todo o modelo C4 — através do seu próprio servidor MCP, com 181 ferramentas.

Coloque um agente no meio, e o importador que você estava esperando vira um prompt.

Quais páginas migram e quais ficam

Faça isso antes de conectar qualquer coisa. O teste que eu uso: uma pessoa recém-chegada precisaria desta página para entender como o sistema funciona, ou para sobreviver à primeira semana? O primeiro caso pertence ao lado do modelo. O segundo pertence ao wiki.

Isso separa um space em quatro pilhas.

Migre como documentação. Páginas que descrevem um sistema: como o serviço de pagamentos é construído, com o que ele conversa, por que existe uma fila na frente dele, qual é a política de retry. No Archyl você anexa essas páginas ao container ou ao sistema que elas descrevem, então elas aparecem junto com o elemento em vez de ficarem a três cliques dentro de uma árvore de páginas.
Migre como ADR. "Por que escolhemos X", RFCs, análises de trade-off, a página de post-mortem que terminou em uma decisão. Isso são decisões, não documentação, e o Archyl as trata como um objeto diferente, com status e um vínculo com o elemento que elas afetaram.
Deixe no Confluence. Atas de reunião, planejamento de sprint, manuais do time, qualquer coisa construída em torno de uma macro do Jira que na verdade é um relatório vivo. Mover isso não te dá nada e te custa a macro.
Apague. Todo space tem páginas descrevendo um sistema que foi desligado há dois anos. Uma migração é a única ocasião em que alguém vai lê-las de novo, então é a única chance que você vai ter de apagá-las honestamente.

Separar primeiro é o que impede que isso vire uma migração de tudo ou nada. Você não está esvaziando o Confluence. Você está extraindo uma camada dele.

O que você precisa

Um cliente MCP. Vou usar o Claude Code aqui, mas Cursor ou qualquer agente compatível com MCP funciona do mesmo jeito.
Uma conta Confluence com acesso de leitura ao space que você quer migrar.
Uma chave de API do Archyl — crie uma em Perfil → Chaves de API com escopo de escrita.

Conecte os dois servidores

Dois comandos. Primeiro, o servidor hospedado da Atlassian (ele abre um navegador para o OAuth na primeira vez que você o usa):

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

Depois o Archyl:

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

E o setup é só isso. O agente agora pode ler seu wiki e escrever no seu workspace de arquitetura.

Descreva a migração, não a construa

Aqui está um prompt real, mais ou menos o que usei no nosso próprio space:

Migre o space "Platform Engineering" do Confluence para o meu
projeto "Aurora Commerce" no Archyl.

1. Liste a árvore de páginas do space e me mostre a hierarquia
   primeiro — não importe nada ainda.
2. Recrie a hierarquia com pastas de documentação, depois importe
   cada página como markdown. Mantenha os títulos, limpe a
   formatação e reescreva os links entre as páginas importadas
   para que apontem para as versões do Archyl.
3. Qualquer página que registre uma decisão — "Por que escolhemos
   X", RFCs, análises de trade-off — deve virar um ADR em vez de
   um doc comum, com status accepted. Coloque a data original na
   primeira linha do contexto: "Decidido em 2024-03-11, migrado
   do Confluence."
4. Me dê uma tabela-resumo de tudo o que você criou.

Observe o que acontece em seguida. O agente chama getConfluenceSpaces e getPagesInConfluenceSpace para mapear o space, percorre a árvore com getConfluencePageDescendants e puxa cada página com getConfluencePage. Do lado do Archyl, ele espelha a estrutura com create_documentation_folder, converte cada página para markdown e a grava com create_documentation, e então chama move_documentation para arquivá-la na pasta certa (criar um doc e posicioná-lo são duas ferramentas separadas). E — essa é a minha parte favorita — direciona as páginas com cara de decisão para create_adr.

Esse último passo importa mais do que parece. Todo wiki de time tem uma camada de decisões fossilizadas enterradas debaixo de "Documentação". Um importador as copiaria como estão. Um agente as lê, reconhece "Por que abandonamos o RabbitMQ" como uma decisão de arquitetura e a arquiva onde decisões devem ficar: vinculada ao elemento que ela afetou e consultável ao lado do seu modelo C4.

A regra do passo zero: revise antes de rodar em massa

Repare que o prompt diz "me mostre a hierarquia primeiro — não importe nada ainda". Faça isso. Todo wiki tem seções de arquivo morto, cemitérios de atas de reunião e uma página chamada "TESTE não deletar" de 2019. Deixe o agente propor a árvore, faça a poda em uma única resposta ("pule Archive e Meeting Notes") e então deixe-o rodar.

Como 200 páginas realmente se comportam

Não é um prompt e uma tarde. Quatro coisas moldam como a execução vai de fato acontecer, e conhecê-las de antemão é a diferença entre uma migração limpa e uma pela metade.

Trabalhe seção por seção, não space por space. O agente mantém o contexto entre os lotes, e um lote cujo resumo você consegue ler é um lote que você consegue corrigir. Dez páginas, confere, mais dez.

O servidor da Atlassian faz throttling, e não no número que você imaginaria. Uma issue aberta no servidor MCP oficial, registrada em 29 de maio de 2026 e ainda sem resposta da Atlassian, relata 429 a partir de cerca de 20 chamadas em paralelo, com um volume total de apenas 200 a 300 chamadas ao longo de umas duas horas. A leitura de quem abriu a issue é que os erros acompanham os picos de concorrência, não a carga sustentada. Qualquer que seja o limite real, a instrução é a mesma: diga ao agente para trabalhar as páginas uma de cada vez em vez de abrir em leque.

Repetir um lote que falhou duplica o lote. O Archyl não força slugs únicos de documentação, então se um lote morre na página sete de dez e você diz "tenta de novo", você fica com duas cópias das seis primeiras. Peça ao agente para chamar list_documentation e pular o que já existe antes de tentar de novo.

Árvores profundas são achatadas. O Archyl limita as pastas de documentação a três níveis. Uma árvore do Confluence aninhada mais fundo volta com Maximum folder nesting depth (3 levels) reached, então decida quais níveis vão se fundir antes de começar, em vez de descobrir isso na página 40.

Limitações honestas

Os anexos continuam não viajando sozinhos, e o motivo mudou de lado. Quando este post saiu pela primeira vez, o Archyl não tinha onde colocá-los. Agora tem: os anexos de documentação já estão no ar, apoiados em object storage compatível com S3, e um agente com a sua chave de API pode enviar um arquivo direto para um doc. A lacuna está do lado do Confluence. O servidor MCP remoto da Atlassian não tem nenhuma ferramenta de anexo — em agosto de 2026, a lista de ferramentas suportadas traz doze operações do Confluence e nenhuma delas toca em arquivos, e o pedido de funcionalidade está aberto desde março de 2026. Ou seja, o agente não consegue buscar os bytes por MCP. Ele consegue buscá-los pela API REST do Confluence (GET /wiki/api/v2/pages/{id}/attachments devolve um downloadLink por arquivo) e depois empurrar cada um para o outro lado:
```
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"
```
A resposta já vem com um trecho de markdown pronto para colar na página. Qualquer tipo de arquivo, 10 MB cada um por padrão. Mas seja honesto sobre o que isso é: um script, com uma segunda credencial (um token de API da Atlassian, já que a sessão OAuth que o servidor MCP mantém não é sua para pegar emprestada). Para a maioria dos spaces, reenviar pelo editor do Archyl o punhado de diagramas que realmente importam continua sendo a resposta mais rápida.
ADRs recebem a data do dia em que você os cria. Nenhuma API aceita uma data de decisão, nem MCP nem REST, então uma decisão tomada em 2023 chega carimbada com a data de hoje. É por isso que o prompt acima escreve a data original no contexto. Vale saber antes de migrar uma década de decisões de uma vez.
A documentação não se vincula sozinha ao seu modelo. O agente consegue anexar um ADR a um sistema ou container em uma única chamada (link_adr_to_element). Ainda não existe ferramenta MCP equivalente para documentação, então os docs importados chegam sem vínculo. Vincule-os na interface, ou peça ao agente para fazer POST em /api/v1/docs/{id}/links com a mesma chave de API. Não pule essa parte: um doc parado ao lado do container que ele descreve é a razão inteira de ele ter saído do wiki.
Macros complexas degradam. As macros mais sofisticadas do Confluence — tabelas de issues do Jira, relatórios dinâmicos — viram texto simples ou links. Blocos de código, tabelas e painéis de informação convertem sem problemas.
As permissões são as suas permissões. O servidor MCP da Atlassian só expõe o que o seu usuário OAuth pode ler. Isso é uma feature.

Por que isso é melhor que um importador clássico

Um importador de disparo único move bytes. Um agente move significado: ele reestrutura enquanto migra, transforma decisões em ADRs, conserta formatação quebrada e responde "o que você pulou e por quê" quando termina.

Ele também é o que torna a triagem possível. Nenhum importador vai olhar para uma página e decidir que ela pertence à pilha que você está deixando para trás. Um agente vai, se você lhe der a regra.

Como fica quando os dois estão rodando

O estado final não é uma ferramenta só. É uma fronteira que se sustenta:

O Confluence fica com o trabalho de wiki. Notas, planos, manuais, tudo o que está amarrado ao Jira. Ninguém precisa ser avisado para parar de usá-lo, e é por isso que a fronteira sobrevive ao contato com o time.
O Archyl segura a camada de arquitetura. O modelo C4, mais a documentação, os ADRs e os contratos de API que o descrevem, cada um anexado ao elemento a que pertence. Quando alguém abre o container de pagamentos, o doc que o explica e o ADR por trás dele estão ali mesmo.
Os dois continuam ao alcance dos seus agentes. Seu cliente MCP tem os dois servidores conectados. Ele pode consultar a arquitetura no Archyl e ainda assim buscar no wiki a página de planejamento, na mesma conversa.

Existe uma regra que impede tudo isso de voltar a derivar, e vale dizê-la em voz alta uma vez: quando uma página descreve um sistema, ela vai para o Archyl. No dia em que alguém escrever uma nova página de arquitetura no Confluence, você recomeçou o problema das 200 páginas.

Configure sua chave, aponte seu agente para os dois servidores e dê a ele uma seção para mastigar. A lista completa de ferramentas está na documentação do servidor MCP.

E assim que os docs estiverem do outro lado, o mesmo truque funciona na própria arquitetura: arquivos Structurizr, módulos Terraform, diagramas Mermaid e o código, virando um modelo C4.

Como Migrar Seus Docs de Arquitetura do Confluence para o Archyl com MCP - Archyl Blog