No tienes que abandonar Confluence. Mueve las páginas que describen tu arquitectura, deja el resto donde está, y haz la mudanza conectando el servidor MCP de Atlassian y el servidor MCP de Archyl al mismo agente IA.

Cómo Migrar tu Documentación de Arquitectura de Confluence a Archyl con MCP

Aquí va una situación de la que oigo hablar cada semana. Un equipo adopta Archyl, modela sus sistemas en C4, vincula sus ADRs y contratos de API — y entonces alguien hace la pregunta obvia: "¿Y qué pasa con las 200 páginas que tenemos en Confluence?"

Lo primero que hay que decir es lo que nadie espera de un proveedor: la mayoría de esas páginas deberían quedarse en Confluence. Notas de reuniones, checklists de onboarding, el runbook de guardias, el documento de planificación del trimestre pasado. Confluence es bueno en eso y Archyl no pretende quitárselo. Lo que debe moverse es el subconjunto que describe la arquitectura, y averiguar qué páginas son ésas es la mayor parte del trabajo.

La mecánica de la mudanza solía ser la parte difícil. Históricamente la respuesta era "espera a que haya un importador" o "copia y pega durante una tarde". Ninguna de las dos es buena. Pero algo cambió en el último año: los dos lados de esa migración ahora hablan MCP.

Atlassian publica un servidor MCP remoto oficial que expone Confluence y Jira a cualquier agente IA, con OAuth y tus permisos existentes. Y Archyl expone toda su plataforma — documentación, carpetas, ADRs, el modelo C4 completo — a través de su propio servidor MCP, con 181 herramientas.

Pon un agente en medio, y el importador que estabas esperando se convierte en un prompt.

Qué páginas se mueven y cuáles se quedan

Haz esto antes de conectar nada. La prueba que uso: ¿necesitaría esta página una persona recién incorporada para entender cómo funciona el sistema, o para sobrevivir a su primera semana? Lo primero pertenece junto al modelo. Lo segundo pertenece al wiki.

Eso ordena un espacio en cuatro montones.

Muévela como documentación. Páginas que describen un sistema: cómo está construido el servicio de pagos, con qué habla, por qué hay una cola delante, cuál es la política de reintentos. En Archyl las adjuntas al container o al sistema que describen, de modo que aparecen junto al elemento en lugar de estar a tres clics dentro de un árbol de páginas.
Muévela como ADR. "Por qué elegimos X", RFCs, análisis de trade-offs, la página del post-incidente que terminó en una decisión. Son decisiones, no documentación, y Archyl las trata como un objeto distinto, con un estado y un enlace al elemento al que afectaron.
Déjala en Confluence. Notas de reuniones, planificación de sprints, manuales de equipo, cualquier cosa construida alrededor de una macro de Jira que en realidad es un informe vivo. Moverlas no te aporta nada y te cuesta la macro.
Bórrala. Todo espacio tiene páginas que describen un sistema que se apagó hace dos años. Una migración es la única ocasión en la que alguien volverá a leerlas, así que es la única oportunidad que tendrás de borrarlas honestamente.

Clasificar primero es lo que evita que esto se convierta en una migración de todo o nada. No estás vaciando Confluence. Estás extrayendo una capa de él.

Lo que necesitas

Un cliente MCP. Aquí usaré Claude Code, pero Cursor o cualquier agente compatible con MCP funciona igual.
Una cuenta de Confluence con acceso de lectura al espacio que quieres migrar.
Una clave API de Archyl — crea una en Profile → API Keys con scope de escritura.

Conecta los dos servidores

Dos comandos. Primero, el servidor alojado de Atlassian (abre un navegador para el OAuth la primera vez que lo usas):

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

Luego Archyl:

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

Eso es toda la configuración. El agente ahora puede leer tu wiki y escribir en tu espacio de trabajo de arquitectura.

Describe la migración, no la construyas

Aquí tienes un prompt real, más o menos el que usé en nuestro propio espacio:

Migra el espacio de Confluence "Platform Engineering" a mi proyecto
de Archyl "Aurora Commerce".

1. Lista el árbol de páginas del espacio y muéstrame primero la
   jerarquía — no importes nada todavía.
2. Recrea la jerarquía con carpetas de documentación, y luego importa
   cada página como markdown. Mantén los títulos, limpia el formato,
   y reescribe los enlaces entre páginas importadas para que apunten
   a las versiones de Archyl.
3. Toda página que registre una decisión — "Why we chose X", RFCs,
   análisis de trade-offs — debe convertirse en un ADR en lugar de
   un doc normal, con estado accepted. Pon la fecha original en la
   primera línea del contexto: "Decidido 2024-03-11, migrado desde
   Confluence."
4. Dame una tabla resumen de todo lo que has creado.

Mira lo que pasa a continuación. El agente llama a getConfluenceSpaces y getPagesInConfluenceSpace para mapear el espacio, recorre el árbol con getConfluencePageDescendants, y extrae cada página con getConfluencePage. Del lado de Archyl replica la estructura con create_documentation_folder, convierte cada página a markdown y la deposita con create_documentation, y después llama a move_documentation para archivarla en la carpeta correcta (crear un doc y colocarlo son dos herramientas distintas). Y — esta es mi parte favorita — envía las páginas con forma de decisión a create_adr en su lugar.

Ese último paso importa más de lo que parece. Todo wiki de equipo tiene una capa de decisiones fosilizadas enterradas bajo "Documentación". Un importador las copiaría tal cual. Un agente las lee, reconoce "Why we moved off RabbitMQ" como una decisión de arquitectura, y la archiva donde pertenecen las decisiones: vinculada al elemento al que afectó y consultable junto a tu modelo C4.

La regla del paso cero: revisa antes de importar en masa

Fíjate en que el prompt dice "muéstrame primero la jerarquía — no importes nada todavía". Hazlo. Todo wiki tiene secciones de archivo, cementerios de notas de reuniones y una página llamada "TEST do not delete" de 2019. Deja que el agente proponga el árbol, pódalo en una sola respuesta ("sáltate Archive y Meeting Notes"), y luego déjalo correr.

Cómo son en realidad 200 páginas

No es un prompt y una tarde. Hay cuatro cosas que determinan cómo va la ejecución de verdad, y conocerlas de antemano es la diferencia entre una migración limpia y una a medio terminar.

Trabaja sección por sección, no espacio por espacio. El agente mantiene el contexto entre lotes, y un lote cuyo resumen puedes leer es un lote que puedes corregir. Diez páginas, revisas, otras diez.

El servidor de Atlassian aplica throttling, y no en la cifra que esperarías. Un issue abierto en el servidor MCP oficial, reportado el 29 de mayo de 2026 y todavía sin respuesta de Atlassian, describe errores 429 a partir de unas 20 llamadas en paralelo, con un volumen total de apenas 200 a 300 llamadas a lo largo de un par de horas. Su autor interpreta que los errores siguen a los picos de concurrencia más que a la carga sostenida. Sea cual sea el límite real, la instrucción es la misma: dile al agente que procese las páginas de una en una en lugar de abrirse en abanico.

Reintentar un lote fallido lo duplica. Archyl no impone slugs únicos en la documentación, así que si un lote muere en la página siete de diez y le dices "inténtalo otra vez", acabas con dos copias de las seis primeras. Pide al agente que llame a list_documentation y se salte lo que ya existe antes de reintentar.

Los árboles profundos se aplanan. Archyl limita las carpetas de documentación a tres niveles. Un árbol de Confluence anidado más profundo devuelve Maximum folder nesting depth (3 levels) reached, así que decide qué niveles vas a colapsar antes de empezar, en vez de descubrirlo en la página 40.

Limitaciones honestas

Los adjuntos siguen sin viajar solos, y el motivo ha cambiado de bando. Cuando este post se publicó por primera vez, Archyl no tenía dónde ponerlos. Ahora sí: los adjuntos de documentación ya están disponibles, respaldados por almacenamiento de objetos compatible con S3, y un agente que tenga tu clave API puede subir un archivo directamente a un doc. La carencia está del lado de Confluence. El servidor MCP remoto de Atlassian no tiene ninguna herramienta de adjuntos — a agosto de 2026, la lista de herramientas soportadas incluye doce operaciones de Confluence y ninguna toca archivos, y la petición de funcionalidad lleva abierta desde marzo de 2026. Así que el agente no puede traerse los bytes por MCP. Sí puede traérselos por la API REST de Confluence (GET /wiki/api/v2/pages/{id}/attachments devuelve un downloadLink por archivo) y luego empujar cada uno al otro 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"
```
La respuesta vuelve con un fragmento de markdown listo para pegar en la página. Cualquier tipo de archivo, 10 MB cada uno por defecto. Pero ten claro qué es esto: un script, con una segunda credencial (un token de API de Atlassian, porque la sesión OAuth que mantiene el servidor MCP no es tuya para tomarla prestada). Para la mayoría de espacios, volver a subir por el editor de Archyl el puñado de diagramas que de verdad importan sigue siendo la respuesta más rápida.
Los ADRs llevan la fecha del día en que los creas. Ninguna API acepta una fecha de decisión, ni MCP ni REST, así que una decisión tomada en 2023 aterriza con el sello de hoy. Por eso el prompt de arriba escribe la fecha original en el contexto. Conviene saberlo antes de migrar una década de decisiones de golpe.
La documentación no se vincula sola a tu modelo. El agente puede adjuntar un ADR a un sistema o un container en una sola llamada (link_adr_to_element). Todavía no hay una herramienta MCP equivalente para documentación, así que los docs importados llegan sin vincular. Vincúlalos en la interfaz, o haz que el agente haga POST a /api/v1/docs/{id}/links con la misma clave API. No te lo saltes: que un doc esté junto al container que describe es la razón entera por la que salió del wiki.
Las macros complejas se degradan. Las macros más sofisticadas de Confluence — tablas de issues de Jira, informes dinámicos — se convierten en texto plano o enlaces. Los bloques de código, las tablas y los paneles de información se convierten limpiamente.
Los permisos son tus permisos. El servidor MCP de Atlassian solo expone lo que tu usuario OAuth puede leer. Eso es una ventaja.

Por qué esto supera a un importador clásico

Un importador de un solo uso mueve bytes. Un agente mueve significado: reestructura mientras migra, convierte decisiones en ADRs, arregla formato muerto, y responde "¿qué te has saltado y por qué?" cuando termina.

También es lo que hace posible la clasificación. Ningún importador va a mirar una página y decidir que pertenece al montón que dejas atrás. Un agente sí lo hará, si le das la regla.

Cómo se ve cuando los dos están funcionando

El estado final no es una única herramienta. Es una frontera que se sostiene:

Confluence conserva el trabajo de wiki. Notas, planes, manuales, todo lo atado a Jira. A nadie hay que decirle que deje de usarlo, y por eso la frontera sobrevive al contacto con el equipo.
Archyl sostiene la capa de arquitectura. El modelo C4, más la documentación, los ADRs y los contratos de API que lo describen, cada uno adjunto al elemento al que pertenece. Cuando alguien abre el container de pagos, el doc que lo explica y el ADR que hay detrás están justo ahí.
Los dos siguen al alcance de tus agentes. Tu cliente MCP tiene ambos servidores conectados. Puede consultar la arquitectura en Archyl y aun así buscar en el wiki la página de planificación, en la misma conversación.

Hay una regla que evita que esto vuelva a derivar, y merece decirse en voz alta una vez: cuando una página describe un sistema, va en Archyl. El día en que alguien escriba una nueva página de arquitectura en Confluence, habrás empezado de nuevo el problema de las 200 páginas.

Configura tu clave, apunta tu agente a los dos servidores, y dale una sección para masticar. La lista completa de herramientas está en la documentación del servidor MCP.

Y una vez que los docs estén al otro lado, el mismo truco funciona con la arquitectura misma: archivos Structurizr, módulos de Terraform, diagramas Mermaid y el código, convertidos en un modelo C4.

Cómo Migrar tu Documentación de Arquitectura de Confluence a Archyl con MCP - Archyl Blog