Cómo Usar un Servidor MCP para Documentación de Arquitectura

Los asistentes de programación con IA se han vuelto indispensables. Claude Code te ayuda a refactorizar sistemas complejos. Cursor acelera el desarrollo de funcionalidades. GitHub Copilot sugiere implementaciones. Pero todas estas herramientas comparten un punto ciego común: no conocen tu arquitectura.

Cuando le pides a un asistente de IA que "agregue un nuevo endpoint al User Service," no sabe que tu User Service se comunica con un Auth Service vía gRPC, almacena datos en PostgreSQL, publica eventos a Kafka y tiene un conjunto específico de requisitos de seguridad documentados en tus ADRs. La IA adivina, tu corriges y la mitad de la ganancia de productividad se evapora.

Los servidores MCP solucionan esto. Le dan a los asistentes de IA acceso estructurado a tu documentación de arquitectura, convirtiendo tu diseño de sistema en una fuente de datos consultable y accionable. Esta guía cubre todo lo que necesitas saber sobre el uso de un servidor MCP para documentación de arquitectura -- que es MCP, por qué importa y cómo configurarlo con Archyl.

Qué Es MCP (Model Context Protocol)

MCP -- el Model Context Protocol -- es un estándar abierto creado por Anthropic para conectar asistentes de IA con herramientas externas y fuentes de datos. Define una forma estructurada para que los modelos de IA descubran, invoquen y reciban resultados de capacidades externas.

Piensa en MCP como un adaptador universal. Antes de MCP, cada asistente de IA tenía su propia forma propietaria de integrarse con herramientas externas. MCP estandariza esto, creando un protocolo único que funciona con diferentes asistentes de IA.

Un servidor MCP es un servicio que expone un conjunto de herramientas a través del protocolo MCP. Cada herramienta tiene un nombre, una descripción, parámetros de entrada y formato de salida. Cuando un asistente de IA se conecta a un servidor MCP, descubre las herramientas disponibles y puede invocarlas según sea necesario durante una conversación.

Para la documentación de arquitectura, esto significa que tu modelo de arquitectura se convierte en un conjunto de herramientas consultables y modificables que cualquier asistente de IA compatible con MCP puede usar. La IA no necesita parsear archivos ni adivinar sobre la estructura de tu sistema -- puede consultar directamente la fuente autoritativa de verdad.

Por Qué la Arquitectura Necesita MCP

La documentación de arquitectura se encuentra en la intersección de varias necesidades que MCP aborda perfectamente.

El Contexto Es Todo para el Desarrollo Asistido por IA

La calidad del código generado por IA es directamente proporcional a la calidad del contexto que tiene la IA. Cuando un asistente de IA entiende tu arquitectura -- qué servicios existen, cómo se comunican, qué tecnologías usan, qué restricciones aplican -- genera código que encaja naturalmente en tu sistema.

Sin contexto arquitectónico, los asistentes de IA hacen suposiciones. Pueden sugerir una API REST cuando tu servicio usa gRPC. Pueden crear una conexión directa a la base de datos cuando tu arquitectura requiere pasar por una capa de servicio. Pueden proponer una llamada síncrona cuando tu sistema usa comunicación event-driven.

MCP le da a los asistentes de IA acceso a la arquitectura real, eliminando estos desajustes.

La Documentación de Arquitectura Son Datos Estructurados

A diferencia de la documentación libre (wikis, páginas de Confluence, archivos README), la documentación de arquitectura modelada en el framework C4 es inherentemente estructurada. Los sistemas contienen containers. Los containers contienen componentes. Los elementos tienen tecnologías, descripciones y relaciones. Los ADRs tienen estados y elementos afectados.

Esta estructura se mapea naturalmente a herramientas MCP. Cada tipo de elemento arquitectónico se convierte en una entidad consultable. Cada operación (listar, obtener, crear, actualizar) se convierte en una herramienta. El asistente de IA puede navegar el modelo de arquitectura de la misma forma que un desarrollador navega un sistema de archivos.

La Documentación Debería Ser Bidireccional

La mayoría de las herramientas de documentación son de solo lectura desde la perspectiva de la API. Puedes ver documentos, pero modificarlos requiere abrir una aplicación específica. MCP habilita la interacción bidireccional: el asistente de IA puede tanto leer como escribir en el modelo de arquitectura.

Esto significa que un asistente de IA puede no solo consultar tu arquitectura sino también proponer modificaciones -- agregar un nuevo componente, crear una relación, redactar un ADR. El desarrollador revisa y aprueba estos cambios, pero la IA hace el trabajo mecánico de actualizar la documentación.

La documentación que nadie abre también se lee

La documentación de arquitectura siempre ha tenido un problema de visibilidad. La escribes, vive en una wiki o en una herramienta de diagramas, y los ingenieros hacen su pregunta en Slack en lugar de abrirla.

MCP cambia dónde se lee la documentación. Tú no vas a buscarla; lo hace tu asistente, cada vez que preguntas «¿cómo funciona el procesamiento de pagos?». La respuesta sale de tu arquitectura documentada y no de los datos de entrenamiento del modelo, y una ingeniera nueva la obtiene el primer día sin saber dónde están los docs.

Hay un efecto secundario que conviene tener. La documentación que se consulta todo el día se corrige cuando está mal, porque alguien nota la respuesta equivocada. La documentación que nadie lee se pudre en silencio.

El Servidor MCP de Archyl: 181 Herramientas para Arquitectura

Archyl proporciona una de las implementaciones de servidor MCP más completas para documentación de arquitectura. Con 181 herramientas organizadas a lo largo de todo el alcance del modelado arquitectónico, cubre todo desde consultar el modelo C4 hasta gestionar releases y rastrear drift.

Aquí tienes una descripción general de las categorías de herramientas.

Consultar el Modelo C4

Las herramientas principales de consulta permiten al asistente de IA explorar tu arquitectura en cada nivel:

  • list_systems / get_project_c4_model -- Descubre todos los software systems en un proyecto
  • list_containers / list_components -- Navega la jerarquía C4
  • list_relationships -- Entiende cómo se conectan los elementos
  • get_element_technologies -- Ve el stack tecnológico de cualquier elemento
  • get_element_owners -- Conoce quién es dueño de qué

Estas herramientas habilitan consultas en lenguaje natural sobre tu arquitectura. Cuando preguntas "¿De que bases de datos depende el Order Service?", la IA puede listar las relaciones del Order Service, filtrar por containers de base de datos y devolver una respuesta precisa.

Gestionar Elementos de Arquitectura

Las herramientas de escritura permiten al asistente de IA modificar el modelo de arquitectura:

  • create_system / update_system / delete_system -- Gestiona software systems
  • create_container / update_container / delete_container -- Gestiona containers
  • create_component / update_component / delete_component -- Gestiona componentes
  • create_relationship / update_relationship / delete_relationship -- Gestiona conexiones

Estas herramientas son particularmente poderosas para mantener la documentación actualizada durante el desarrollo. Cuando agregas un nuevo servicio a tu codebase, puedes pedirle al asistente de IA que agregue el container correspondiente al modelo de arquitectura, configure sus tecnologías y cree las relaciones apropiadas -- todo sin salir de tu IDE.

Architecture Decision Records

Las herramientas de ADR traen la documentación de decisiones al flujo de trabajo con IA:

  • list_adrs / get_adr -- Consulta decisiones existentes
  • create_adr / update_adr -- Crea nuevos ADRs o actualiza los existentes
  • link_adr_to_element -- Conecta decisiones a elementos afectados

Cuando estás discutiendo una elección tecnológica con tu asistente de IA, puede verificar ADRs existentes para decisiones relacionadas, redactar un nuevo ADR para la decisión actual y vincularlo a los elementos arquitectónicos relevantes.

Contratos de API y Event Channels

Las herramientas de documentación de integración cubren los límites de servicio:

  • list_api_contracts / create_api_contract -- Gestiona especificaciones de API
  • list_event_channels / create_event_channel -- Modela comunicación asíncrona
  • link_api_contract / link_event_channel -- Conecta especificaciones a elementos

Estas herramientas ayudan a mantener la conexión entre arquitectura e implementación. Cuando creas un nuevo endpoint de API, la IA puede verificar si existe un contrato de API para ese servicio y sugerir actualizarlo. También funciona al revés: si tus propios servicios exponen servidores MCP, Archyl documenta sus herramientas como contratos de API, y el playground de MCP te permite llamarlas en directo.

Documentación y Colaboración

Las herramientas más amplias de documentación soportan flujos de trabajo de equipo:

  • create_documentation / update_documentation -- Gestiona documentación del proyecto
  • create_comment / list_comments -- Anota elementos de arquitectura
  • list_flows / create_flow -- Documenta flujos de usuario y de sistema
  • get_drift_score / compute_drift_score -- Verifica la precisión de la documentación

Releases y Métricas

Las herramientas operacionales conectan la arquitectura con la entrega:

  • create_release / list_releases -- Rastrea despliegues
  • get_dora_metrics / get_dora_trend -- Mide el rendimiento de ingeniería
  • list_environments -- Entiende los objetivos de despliegue

Ejemplos Reales: MCP en Acción

Aquí tienes ejemplos concretos de como los desarrolladores usan el servidor MCP de Archyl en su flujo de trabajo diario.

Ejemplo 1: Consultando Sistemas desde Claude Code

Estás trabajando en Claude Code y necesitas entender la arquitectura antes de hacer cambios:

Tú: ¿Qué sistemas y containers tiene nuestro proyecto?

Claude: Déjame verificar tu arquitectura.
[Llama a list_systems, luego list_containers para cada sistema]

Tu proyecto "E-Commerce Platform" tiene 3 sistemas:
1. E-Commerce Platform (software_system)
   - API Gateway (Go, Kong)
   - User Service (Go, PostgreSQL)
   - Order Service (Java, PostgreSQL)
   - Product Service (Node.js, MongoDB)
   - Notification Service (Python, Redis)
   - Event Bus (Kafka)

2. Stripe (external_system)
   - Gateway de procesamiento de pagos

3. SendGrid (external_system)
   - Servicio de email transaccional

La IA devuelve datos reales de tu arquitectura documentada, no una alucinación.

Ejemplo 2: Creando Componentes desde Cursor

Estás agregando un nuevo módulo a un servicio y quieres documentarlo:

Tú: Acabo de agregar un componente RateLimiter al API Gateway.
     Usa Redis y la librería golang.org/x/time/rate.
     ¿Puedes agregarlo a nuestra arquitectura?

Cursor: Lo agregaré a tu modelo C4.
[Llama a create_component con name="RateLimiter",
 container="API Gateway", technologies=["Redis", "Go"]]
[Llama a create_relationship de RateLimiter
 al container de Redis]

Listo. He agregado el componente RateLimiter al API Gateway
y creado una relación con tu container de Redis.

La documentación se actualiza en segundos, sin salir del IDE.

Ejemplo 3: Verificando el Drift Antes de un Refactor

Antes de un esfuerzo importante de refactorización, quieres saber qué tan precisa es la documentación:

Tú: ¿Cuál es nuestro drift score actual? ¿Hay servicios
     no documentados?

Claude: Déjame verificar.
[Llama a get_drift_score]
[Llama a get_drift_details]

Tu drift score es 78/100 (Bueno).

Problemas detectados:
- El Search Service está corriendo en producción pero no está
  documentado en tu modelo C4
- El Analytics Service tiene 2 relaciones no documentadas
  con el Data Warehouse
- La lista de tecnologías del API Gateway no incluye "Redis"
  (agregado recientemente para rate limiting)

¿Quieres que corrija estos problemas?

La IA identifica exactamente qué está desactualizado y puede corregirlo automáticamente.

Ejemplo 4: Redactando un ADR

Durante una discusión de diseño sobre cambiar de REST a gRPC para la comunicación interna entre servicios:

Tú: Estamos considerando cambiar la comunicación interna entre
     servicios de REST a gRPC. ¿Puedes redactar un ADR y verificar
     si tenemos decisiones existentes sobre esto?

Claude: Déjame verificar los ADRs existentes primero.
[Llama a list_adrs]

Encontré un ADR relacionado:
- ADR-007: "Use REST for all internal APIs" (Estado: Accepted)
  Esto se decidió hace 18 meses.

Redactaré un nuevo ADR para reemplazarlo.
[Llama a create_adr con title="Migrate Internal
 Communication from REST to gRPC"]

Creado ADR-015 con:
- Contexto: La comunicación actual basada en REST agrega
  overhead de serialización...
- Decisión: Adoptar gRPC con Protocol Buffers para toda
  nueva comunicación interna entre servicios...
- Estado: Proposed
- Reemplaza: ADR-007

¿Quieres que lo vincule a los servicios afectados?

La IA verifica decisiones relacionadas, redacta un nuevo ADR y ofrece vincularlo a los elementos arquitectónicos relevantes.

Ejemplo 5: Entendiendo el Impacto Antes de los Cambios

Antes de modificar un servicio, quieres entender el radio de impacto:

Tú: Necesito cambiar el esquema de base de datos del Order Service.
     ¿Qué más depende del Order Service?

Claude: Déjame rastrear las dependencias.
[Llama a list_relationships filtrado por Order Service]
[Llama a get_element_owners para elementos dependientes]

El Order Service tiene estos dependientes:
- API Gateway -> Order Service (REST, gestión de pedidos)
- Order Service -> Payment Service (gRPC, procesamiento de pagos)
- Order Service -> Event Bus (publica eventos OrderCreated,
  OrderUpdated, OrderCancelled)
- Notification Service consume eventos de Order del Event Bus
- Analytics Service consume eventos de Order del Event Bus

Propiedad:
- Order Service: Platform Team
- Payment Service: Payments Team
- Notification Service: Platform Team
- Analytics Service: Data Team

Los cambios de esquema podrían afectar al Payment Service
(dependencia directa) y a cualquier consumidor de eventos de Order.
Recomendaría coordinar con el Payments Team y el Data Team.

Configurando el Servidor MCP de Archyl

Comenzar con el servidor MCP de Archyl toma solo unos minutos. Así es como configurarlo para los asistentes de IA más comunes. El servidor es stateless desde la revisión 2026-07-28 del protocolo.

Configuración para Claude Code

Agrega el servidor MCP de Archyl a tu configuración de Claude Code:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

Una vez configurado, Claude Code descubre automáticamente las 181 herramientas y puede usarlas en cualquier conversación.

Configuración para Cursor

Cursor soporta servidores MCP a través de su configuración. Agrega Archyl en la sección MCP:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

Después de agregar la configuración, reinicia Cursor. Las herramientas de Archyl aparecen en la lista de herramientas MCP, y Cursor puede usarlas durante la generación de código y refactorización.

Configuración para Otras Herramientas Compatibles con MCP

Cualquier herramienta que soporte el protocolo MCP puede conectarse al servidor MCP de Archyl. El servidor expone un endpoint MCP estándar con descubrimiento de herramientas, por lo que los clientes compatibles detectan y listan automáticamente las herramientas disponibles.

Generación de API Key

Genera tu API key para MCP desde el dashboard de Archyl:

  1. Navega a la configuración de tu organización
  2. Ve a la sección de API
  3. Crea una nueva API key con los permisos apropiados
  4. Copia la key en tu configuración del servidor MCP

Recomendamos crear API keys separadas para diferentes casos de uso (por ejemplo, una para Claude Code, una para CI/CD) para poder rotarlas de forma independiente.

Buenas Prácticas para Documentación de Arquitectura con MCP

Comienza con Solo Lectura

Cuando configures el servidor MCP por primera vez, comienza con consultas de solo lectura. Familiarízate con la capacidad del asistente de IA para explorar tu arquitectura antes de habilitar operaciones de escritura. Esto construye confianza en la precisión y confiabilidad de la herramienta.

Revisa los Cambios Generados por IA

Cuando el asistente de IA crea o modifica elementos de arquitectura, revisa los cambios antes de considerarlos finales. Las funciones de historial y versionado de Archyl te permiten ver qué cambió y revertir si es necesario. La IA es un asistente poderoso, pero las decisiones arquitectónicas siempre deberían tener supervisión humana.

Combina MCP con Architecture as Code

MCP y architecture as code son complementarios. Usa MCP para consultas interactivas y actualizaciones rápidas durante el desarrollo. Usa architecture as code (el archivo archyl.yaml) para definiciones autoritativas y versionadas que pasan por code review. Los dos enfoques se refuerzan mutuamente.

Usa MCP en las Revisiones de Código

Durante las revisiones de código, pide al asistente de IA que verifique si los cambios de código se alinean con la arquitectura documentada. "¿Este nuevo endpoint de API coincide con el contrato de API documentado para este servicio?" o "¿Estas consultas a la base de datos pasan por la capa de servicio como está documentado?" La IA puede validar el código contra el modelo de arquitectura en tiempo real.

Enseña a tu Equipo las Herramientas Disponibles

La mayor barrera para la adopción de MCP es la falta de conocimiento. La mayoría de los desarrolladores no se dan cuenta de que preguntas puede responder la IA sobre su arquitectura. Comparte ejemplos, crea una hoja de referencia rápida de consultas útiles y demuestra flujos de trabajo con MCP en reuniones de equipo.

El Futuro de la Documentación de Arquitectura con IA

Los servidores MCP representan un cambio fundamental en como los equipos interactúan con la documentación de arquitectura. En lugar de que la documentación sea un artefacto pasivo que los desarrolladores leen (o más a menudo, no leen), se convierte en un participante activo en el flujo de trabajo de desarrollo.

Cuando tu asistente de IA puede consultar la arquitectura antes de generar código, verificar la conformidad después de los cambios y actualizar la documentación a medida que el sistema evoluciona, la barrera entre "trabajar en el sistema" y "documentar el sistema" desaparece.

La documentación de arquitectura deja de ser algo que mantienes por separado y se convierte en algo que está entretejido en cada interacción de desarrollo. Cada pregunta que le haces a la IA, cada cambio de código que haces, cada discusión de diseño que tienes -- todos pueden estar informados por y reflejados en el modelo de arquitectura.

Este es el futuro que Archyl está construyendo. El servidor MCP es el puente entre el desarrollo impulsado por IA y la documentación de arquitectura estructurada. Y con 181 herramientas que cubren todo el alcance del modelado arquitectónico, es lo suficientemente completo para soportar cualquier flujo de trabajo que tu equipo necesite.

Comienza con el servidor MCP de Archyl y dale a tu asistente de IA el contexto arquitectónico que le ha faltado.