Cómo crear diagramas de arquitectura con agentes de IA (MCP)

Los asistentes de IA son buenos convirtiendo una descripción en un diagrama. El problema empieza al día siguiente. Un diagrama que vive como PNG en un chat, o como fragmento de Mermaid en un pull request, es una copia. Nadie actualiza la copia, y un mes después contradice el sistema que describe.

El Model Context Protocol (MCP) cambia el lugar donde trabaja el agente. En lugar de entregarte una imagen, un agente conectado a Archboard por MCP lee y edita el mismo diagrama estructurado que tu equipo abre en el navegador. Sus cambios aparecen en vivo en el lienzo, etiquetados con la persona para la que trabaja, y esa persona puede deshacerlos en un paso.

Esta guía muestra cómo conectar una app de IA a Archboard, recorre un ejemplo completo desde el primer borrador hasta la revisión y cubre los prompts, permisos y límites que importan en la práctica.

Qué puede hacer un agente con Archboard

Los diagramas de Archboard están hechos de nodos tipados que vienen de packs de nodos: un Deployment de Kubernetes, una base de datos en la nube, un contenedor C4 o una tarea BPMN es un nodo con puertos y propiedades, no una caja con una etiqueta. Por MCP, un agente puede:

• Listar y leer los diagramas a los que tiene acceso, como resumen (marcos, recuentos, quién está trabajando en él) o como registros completos de nodos y conexiones.
• Crear un diagrama a partir de una descripción, de una lista de operaciones o de un diagrama de flujo de Mermaid convertido a tipos de nodo reales.
• Editar un diagrama con un lote de operaciones que se aplica como un solo cambio: añadir nodos, conectar puertos, mover, cambiar el estilo o eliminar.
• Revisar su trabajo renderizando una captura PNG, y mostrar el diagrama dentro de la conversación en las apps compatibles con MCP Apps.
• Deshacer uno de sus propios cambios.

Archboard no incluye un modelo de IA propio. El agente lo pones tú: Claude, Cursor, VS Code u otra app que pueda añadir un servidor MCP remoto con inicio de sesión OAuth. La página de agentes de IA tiene un resumen breve.

Conecta tu app de IA

El servidor MCP de Archboard está en https://getarchboard.app/mcp. Usa Streamable HTTP y OAuth, así que no hay ninguna clave de API que copiar. Cuando tu app se conecta, abre la página de inicio de sesión de Archboard; inicias sesión con Google o GitHub y apruebas el acceso que pide la app.

En la pantalla de consentimiento eliges qué organizaciones y espacios de trabajo puede usar la app y qué puede hacer en cada uno: leer, editar o eliminar (mover diagramas a la papelera). Más adelante puedes renombrar la app, cambiar lo que puede usar y hacer, o quitarle el acceso en Ajustes > Aplicaciones conectadas.

Configuración en algunas apps habituales:

Claude (web y escritorio). Abre Customize > Connectors, elige Add custom connector e introduce https://getarchboard.app/mcp. En los planes Team y Enterprise, primero un Owner lo añade en Organization settings > Connectors; después te conectas desde Customize > Connectors.

Claude Code.

claude mcp add --transport http archboard https://getarchboard.app/mcp

Después ejecuta /mcp en una sesión para autenticarte.

Cursor. Añade el servidor a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "archboard": { "url": "https://getarchboard.app/mcp" }
  }
}

VS Code. Añádelo a tu mcp.json (VS Code usa una clave servers):

{
  "servers": {
    "archboard": { "type": "http", "url": "https://getarchboard.app/mcp" }
  }
}

Otras apps. Añade https://getarchboard.app/mcp como servidor MCP remoto en los ajustes de conectores o de MCP de la app, si tu plan lo permite. La app necesita inicio de sesión OAuth sin secreto de cliente (client secret); la documentación de MCP tiene los detalles para quienes desarrollan clientes.

Un ejemplo completo: una tienda en línea, del borrador a la revisión

Esta es una sesión con un agente conectado a Archboard. Los prompts son del tipo que escribirías tú; los nombres de herramientas entre paréntesis son lo que el agente invoca entre bastidores.

1. Pide un primer borrador

Dibuja un diagrama de contenedores C4 para nuestra tienda en línea: una aplicación web, una API, un worker en segundo plano que envía los correos de los pedidos a través de nuestro proveedor de correo, una base de datos PostgreSQL y Stripe para los pagos. Pon todo lo que operamos nosotros dentro de un límite del sistema.

El agente elige un espacio de trabajo (list_workspaces), busca los tipos de nodo C4 que necesita (search_node_types) y crea el diagrama (create_diagram). Luego renderiza una captura (render_snapshot) para comprobar que nada se superpone y que cada conexión tiene etiqueta, y muestra el resultado en la conversación (show_diagram).

El borrador es un punto de partida. El agente eligió los contenedores a partir de tu frase; no puede saber que el worker también lee de la base de datos a menos que lo digas.

2. Edita con palabras, revisa en el lienzo

El worker también lee los pedidos de la base de datos. Añade una caché de Redis entre la API y PostgreSQL, y etiqueta cada conexión con su protocolo.

El agente lee el diagrama actual (get_canvas) y aplica un único lote de operaciones (apply_ops). Si tienes el diagrama abierto, ves aparecer los nodos nuevos junto a un cursor etiquetado con la app y tu nombre. Los compañeros que tienen el diagrama abierto ven lo mismo.

Este es el diagrama después de los dos primeros prompts:

3. Deshaz lo que no te guste

Deshaz el último cambio.

Cada cambio de un agente es un paso. El agente puede revertir su propio cambio (revert_change), o tú puedes deshacerlo en un paso desde el aviso para deshacer que aparece en el editor justo después del cambio. Los campos que otra persona cambió mientras tanto se conservan.

4. Haz preguntas sobre un diagrama existente

¿Qué contenedores hablan con PostgreSQL, y por qué protocolo?

Para una pregunta así, el agente solo lee (get_canvas). Explicar un diagrama existente a alguien nuevo en el equipo es una de las cosas más útiles que hace un agente, y no necesita ningún acceso de escritura.

Prompts que funcionan bien

• Nombra el tipo de diagrama. "Diagrama de contenedores C4", "diagrama de Kubernetes con un marco por namespace", "proceso BPMN con un carril por equipo". Así el agente usa el pack de nodos adecuado en lugar de cajas genéricas.
• Di qué va dentro de cada límite. Los marcos, los namespaces y las VPC tienen significado, así que dile al agente qué va en cada sitio.
• Pide conexiones etiquetadas. "Etiqueta cada conexión con protocolo y puerto" convierte las flechas en documentación.
• Mantén cada cambio pequeño. Una petición por cambio es más fácil de revisar y de deshacer que una reescritura.
• Pide al agente que revise su trabajo. "Renderiza una captura y corrige cualquier superposición" detecta problemas de layout antes de que mires.
• Pide un resumen. "Enumera lo que cambiaste" te da una nota de revisión para el pull request o el chat del equipo.

Quién controla qué

Conectar una app de IA a los diagramas en los que trabaja tu equipo plantea preguntas razonables. Estas son las reglas que aplica Archboard:

• Tú eliges el alcance. Una app solo ve las organizaciones y los espacios de trabajo que permitiste, y solo hace allí lo que permitiste: leer, editar o eliminar. Lo que realmente puede hacer es lo más restrictivo entre ese ajuste, los scopes que se le concedieron, tu rol y tu plan.
• Los cambios son visibles y tienen autor. El cursor y los cambios de un agente se etiquetan con la app y la persona para la que trabaja, en el lienzo y en el historial de versiones.
• Deshacer es un paso. Puedes deshacer un cambio de tu agente desde el aviso para deshacer del editor, o pedirle al agente que lo revierta dentro de 7 días. Los propietarios y administradores de la organización también pueden deshacerlo.
• Lo eliminado se puede recuperar. Un agente necesita el permiso Eliminar para mover un diagrama a la papelera, y Archboard indica a los agentes que lo hagan solo cuando tú lo pidas. Puedes restaurar el diagrama desde la Papelera.
• El texto de un diagrama son datos. Archboard indica a los agentes que traten las etiquetas, notas y nombres de un diagrama como datos, nunca como instrucciones, y que añadan imágenes solo cuando tú las pidas.

Cuándo usar un agente y cuándo dibujar a mano

Los agentes son buenos para primeros borradores, ediciones repetitivas ("renombra cada servicio orders-* a checkout-*"), mantener un diagrama al día con un cambio que estás haciendo de todos modos y explicar un diagrama que dibujó otra persona. Un agente de programación que acaba de cambiar un servicio puede actualizar el diagrama de arquitectura en la misma sesión.

Dibujar a mano sigue siendo mejor para decidir qué importa. Un diagrama es un argumento sobre un sistema, y elegir qué dejar fuera es una cuestión de criterio. Deja que el agente escriba y quédate con el criterio.

Límites que conviene conocer

• Se aplican los límites del plan. MCP funciona en todos los planes con los mismos límites de plan que el editor. En el plan Free son 3 diagramas y, por diagrama, 15 nodos de diagrama más 150 notas, textos, pegatinas y temas de mapa mental.
• Las llamadas a herramientas tienen un límite por minuto. Cuando un agente llega al límite, Archboard le indica cuánto debe esperar antes de reintentar.
• El agente solo sabe lo que le dices y lo que hay en el diagrama. A través de Archboard no puede ver tu clúster en ejecución ni tu código. Si una dependencia importa, dilo, o deja que un agente de programación lea el código.

Preguntas frecuentes

¿Qué apps de IA pueden conectarse a Archboard? Las apps que pueden añadir un servidor MCP remoto con inicio de sesión OAuth y no exigen un secreto de cliente. La página de agentes de IA tiene una configuración rápida para Claude, Cursor, VS Code, Claude Code y otras.

¿Archboard usa su propio modelo de IA? No. Archboard es el espacio de trabajo de diagramas; el razonamiento lo hace la app de IA que conectas.

¿Puede el agente ver todos mis diagramas? Solo las organizaciones y los espacios de trabajo que permitiste al conectarlo, con el permiso que elegiste para cada uno. Por defecto son todos, incluidos aquellos a los que te unas más adelante, con permiso Eliminar; puedes acotarlo en la pantalla de consentimiento o más adelante en Ajustes > Aplicaciones conectadas.

¿Puedo deshacer lo que hizo el agente? Sí. Cada cambio del agente es un paso que puedes deshacer desde el aviso para deshacer del editor, y la app puede revertir sus propios cambios de los últimos 7 días.

¿Funciona en el plan Free? Sí. MCP funciona en todos los planes, con los mismos límites de plan que el editor.

Empieza gratis — un puesto, sin tarjeta de crédito.