Como Usar un Servidor MCP para Documentacion de Arquitectura - Archyl Blog

Los asistentes de IA estan transformando como trabajan los desarrolladores, pero no pueden ver tu documentacion de arquitectura. Los servidores MCP cierran esa brecha. Esta guia cubre que es MCP, por que importa para la arquitectura y como las 56 herramientas MCP de Archyl te permiten consultar, crear y validar arquitectura directamente desde Claude o Cursor.

Como Usar un Servidor MCP para Documentacion de Arquitectura

Los asistentes de programacion 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 comun: 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 via gRPC, almacena datos en PostgreSQL, publica eventos a Kafka y tiene un conjunto especifico 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 documentacion de arquitectura, convirtiendo tu diseno de sistema en una fuente de datos consultable y accionable. Esta guia cubre todo lo que necesitas saber sobre el uso de un servidor MCP para documentacion de arquitectura -- que es MCP, por que importa y como configurarlo con Archyl.

Que Es MCP (Model Context Protocol)

MCP -- el Model Context Protocol -- es un estandar 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 tenia su propia forma propietaria de integrarse con herramientas externas. MCP estandariza esto, creando un protocolo unico que funciona con diferentes asistentes de IA.

Un servidor MCP es un servicio que expone un conjunto de herramientas a traves del protocolo MCP. Cada herramienta tiene un nombre, una descripcion, parametros de entrada y formato de salida. Cuando un asistente de IA se conecta a un servidor MCP, descubre las herramientas disponibles y puede invocarlas segun sea necesario durante una conversacion.

Para la documentacion 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 Que la Arquitectura Necesita MCP

La documentacion de arquitectura se encuentra en la interseccion de varias necesidades que MCP aborda perfectamente.

El Contexto Es Todo para el Desarrollo Asistido por IA

La calidad del codigo generado por IA es directamente proporcional a la calidad del contexto que tiene la IA. Cuando un asistente de IA entiende tu arquitectura -- que servicios existen, como se comunican, que tecnologias usan, que restricciones aplican -- genera codigo que encaja naturalmente en tu sistema.

Sin contexto arquitectonico, los asistentes de IA hacen suposiciones. Pueden sugerir una API REST cuando tu servicio usa gRPC. Pueden crear una conexion directa a la base de datos cuando tu arquitectura requiere pasar por una capa de servicio. Pueden proponer una llamada sincrona cuando tu sistema usa comunicacion event-driven.

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

La Documentacion de Arquitectura Son Datos Estructurados

A diferencia de la documentacion libre (wikis, paginas de Confluence, archivos README), la documentacion de arquitectura modelada en el framework C4 es inherentemente estructurada. Los sistemas contienen containers. Los containers contienen componentes. Los elementos tienen tecnologias, descripciones y relaciones. Los ADRs tienen estados y elementos afectados.

Esta estructura se mapea naturalmente a herramientas MCP. Cada tipo de elemento arquitectonico se convierte en una entidad consultable. Cada operacion (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 Documentacion Deberia Ser Bidireccional

La mayoria de las herramientas de documentacion son de solo lectura desde la perspectiva de la API. Puedes ver documentos, pero modificarlos requiere abrir una aplicacion especifica. MCP habilita la interaccion 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 tambien proponer modificaciones -- agregar un nuevo componente, crear una relacion, redactar un ADR. El desarrollador revisa y aprueba estos cambios, pero la IA hace el trabajo mecanico de actualizar la documentacion.

El Servidor MCP de Archyl: 56 Herramientas para Arquitectura

Archyl proporciona una de las implementaciones de servidor MCP mas completas para documentacion de arquitectura. Con 56 herramientas organizadas a lo largo de todo el alcance del modelado arquitectonico, cubre todo desde consultar el modelo C4 hasta gestionar releases y rastrear drift.

Aqui tienes una descripcion general de las categorias 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 jerarquia C4
  • list_relationships -- Entiende como se conectan los elementos
  • get_element_technologies -- Ve el stack tecnologico de cualquier elemento
  • get_element_owners -- Conoce quien es dueno de que

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 documentacion 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 tecnologias y cree las relaciones apropiadas -- todo sin salir de tu IDE.

Architecture Decision Records

Las herramientas de ADR traen la documentacion 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 estas discutiendo una eleccion tecnologica con tu asistente de IA, puede verificar ADRs existentes para decisiones relacionadas, redactar un nuevo ADR para la decision actual y vincularlo a los elementos arquitectonicos relevantes.

Contratos de API y Event Channels

Las herramientas de documentacion de integracion cubren los limites de servicio:

  • list_api_contracts / create_api_contract -- Gestiona especificaciones de API
  • list_event_channels / create_event_channel -- Modela comunicacion asincrona
  • link_api_contract / link_event_channel -- Conecta especificaciones a elementos

Estas herramientas ayudan a mantener la conexion entre arquitectura e implementacion. Cuando creas un nuevo endpoint de API, la IA puede verificar si existe un contrato de API para ese servicio y sugerir actualizarlo.

Documentacion y Colaboracion

Las herramientas mas amplias de documentacion soportan flujos de trabajo de equipo:

  • create_documentation / update_documentation -- Gestiona documentacion 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 precision de la documentacion

Releases y Metricas

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 ingenieria
  • list_environments -- Entiende los objetivos de despliegue

Ejemplos Reales: MCP en Accion

Aqui 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

Estas trabajando en Claude Code y necesitas entender la arquitectura antes de hacer cambios:

Tu: ¿Que sistemas y containers tiene nuestro proyecto?

Claude: Dejame 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 alucinacion.

Ejemplo 2: Creando Componentes desde Cursor

Estas agregando un nuevo modulo a un servicio y quieres documentarlo:

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

Cursor: Lo agregare 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 relacion con tu container de Redis.

La documentacion se actualiza en segundos, sin salir del IDE.

Ejemplo 3: Verificando el Drift Antes de un Refactor

Antes de un esfuerzo importante de refactorizacion, quieres saber que tan precisa es la documentacion:

Tu: ¿Cual es nuestro drift score actual? ¿Hay servicios
     no documentados?

Claude: Dejame verificar.
[Llama a get_drift_score]
[Llama a get_drift_details]

Tu drift score es 78/100 (Bueno).

Problemas detectados:
- El Search Service esta corriendo en produccion pero no esta
  documentado en tu modelo C4
- El Analytics Service tiene 2 relaciones no documentadas
  con el Data Warehouse
- La lista de tecnologias del API Gateway no incluye "Redis"
  (agregado recientemente para rate limiting)

¿Quieres que corrija estos problemas?

La IA identifica exactamente que esta desactualizado y puede corregirlo automaticamente.

Ejemplo 4: Redactando un ADR

Durante una discusion de diseno sobre cambiar de REST a gRPC para la comunicacion interna entre servicios:

Tu: Estamos considerando cambiar la comunicacion interna entre
     servicios de REST a gRPC. ¿Puedes redactar un ADR y verificar
     si tenemos decisiones existentes sobre esto?

Claude: Dejame verificar los ADRs existentes primero.
[Llama a list_adrs]

Encontre un ADR relacionado:
- ADR-007: "Use REST for all internal APIs" (Estado: Accepted)
  Esto se decidio hace 18 meses.

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

Creado ADR-015 con:
- Contexto: La comunicacion actual basada en REST agrega
  overhead de serializacion...
- Decision: Adoptar gRPC con Protocol Buffers para toda
  nueva comunicacion 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 arquitectonicos relevantes.

Ejemplo 5: Entendiendo el Impacto Antes de los Cambios

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

Tu: Necesito cambiar el esquema de base de datos del Order Service.
     ¿Que mas depende del Order Service?

Claude: Dejame 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, gestion 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 podrian afectar al Payment Service
(dependencia directa) y a cualquier consumidor de eventos de Order.
Recomendaria 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. Asi es como configurarlo para los asistentes de IA mas comunes.

Configuracion para Claude Code

Agrega el servidor MCP de Archyl a tu configuracion de Claude Code:

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

Una vez configurado, Claude Code descubre automaticamente las 56 herramientas y puede usarlas en cualquier conversacion.

Configuracion para Cursor

Cursor soporta servidores MCP a traves de su configuracion. Agrega Archyl en la seccion MCP:

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

Despues de agregar la configuracion, reinicia Cursor. Las herramientas de Archyl aparecen en la lista de herramientas MCP, y Cursor puede usarlas durante la generacion de codigo y refactorizacion.

Configuracion 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 estandar con descubrimiento de herramientas, por lo que los clientes compatibles detectan y listan automaticamente las herramientas disponibles.

Generacion de API Key

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

  1. Navega a la configuracion de tu organizacion
  2. Ve a la seccion de API
  3. Crea una nueva API key con los permisos apropiados
  4. Copia la key en tu configuracion 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 Practicas para Documentacion de Arquitectura con MCP

Comienza con Solo Lectura

Cuando configures el servidor MCP por primera vez, comienza con consultas de solo lectura. Familiarizate con la capacidad del asistente de IA para explorar tu arquitectura antes de habilitar operaciones de escritura. Esto construye confianza en la precision 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 que cambio y revertir si es necesario. La IA es un asistente poderoso, pero las decisiones arquitectonicas siempre deberian tener supervision humana.

Combina MCP con Architecture as Code

MCP y architecture as code son complementarios. Usa MCP para consultas interactivas y actualizaciones rapidas 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 Codigo

Durante las revisiones de codigo, pide al asistente de IA que verifique si los cambios de codigo 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 esta documentado?" La IA puede validar el codigo contra el modelo de arquitectura en tiempo real.

Ensena a tu Equipo las Herramientas Disponibles

La mayor barrera para la adopcion de MCP es la falta de conocimiento. La mayoria de los desarrolladores no se dan cuenta de que preguntas puede responder la IA sobre su arquitectura. Comparte ejemplos, crea una hoja de referencia rapida de consultas utiles y demuestra flujos de trabajo con MCP en reuniones de equipo.

El Futuro de la Documentacion de Arquitectura con IA

Los servidores MCP representan un cambio fundamental en como los equipos interactuan con la documentacion de arquitectura. En lugar de que la documentacion sea un artefacto pasivo que los desarrolladores leen (o mas 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 codigo, verificar la conformidad despues de los cambios y actualizar la documentacion a medida que el sistema evoluciona, la barrera entre "trabajar en el sistema" y "documentar el sistema" desaparece.

La documentacion de arquitectura deja de ser algo que mantienes por separado y se convierte en algo que esta entretejido en cada interaccion de desarrollo. Cada pregunta que le haces a la IA, cada cambio de codigo que haces, cada discusion de diseno que tienes -- todos pueden estar informados por y reflejados en el modelo de arquitectura.

Este es el futuro que Archyl esta construyendo. El servidor MCP es el puente entre el desarrollo impulsado por IA y la documentacion de arquitectura estructurada. Y con 56 herramientas que cubren todo el alcance del modelado arquitectonico, 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 arquitectonico que le ha faltado.