Como criar diagramas de arquitetura com agentes de IA (MCP)

Assistentes de IA são bons em transformar uma descrição em diagrama. O problema começa no dia seguinte. Um diagrama que vive como PNG em um chat, ou como trecho de Mermaid em um pull request, é uma cópia. Ninguém atualiza a cópia, e um mês depois ela contradiz o sistema que descreve.

O Model Context Protocol (MCP) muda o lugar onde o agente trabalha. Em vez de entregar uma imagem, um agente conectado ao Archboard por MCP lê e edita o mesmo diagrama estruturado que seu time abre no navegador. As alterações dele aparecem ao vivo no canvas, identificadas com a pessoa para quem ele trabalha, e essa pessoa pode desfazê-las em um passo.

Este guia mostra como conectar um app de IA ao Archboard, percorre um exemplo completo do primeiro rascunho à revisão e cobre os prompts, as permissões e os limites que importam na prática.

O que um agente pode fazer com o Archboard

Os diagramas do Archboard são feitos de nós tipados que vêm de packs de nós: um Deployment do Kubernetes, um banco de dados na nuvem, um contêiner C4 ou uma tarefa BPMN é um nó com portas e propriedades, não uma caixa com um rótulo. Por MCP, um agente pode:

• Listar e ler os diagramas a que tem acesso, como visão geral (frames, contagens, quem está trabalhando nele) ou como registros completos de nós e conexões.
• Criar um diagrama a partir de uma descrição, de uma lista de operações ou de um fluxograma Mermaid convertido em tipos de nó reais.
• Editar um diagrama com um lote de operações aplicado como uma única alteração: adicionar nós, conectar portas, mover, mudar o estilo ou remover.
• Conferir o próprio trabalho renderizando um snapshot em PNG e mostrar o diagrama dentro da conversa em apps que oferecem suporte a MCP Apps.
• Desfazer uma das próprias alterações.

O Archboard não inclui um modelo de IA próprio. Quem traz o agente é você: Claude, Cursor, VS Code ou outro app que consiga adicionar um servidor MCP remoto com login OAuth. A página de agentes de IA tem uma visão geral rápida.

Conecte seu app de IA

O servidor MCP do Archboard fica em https://getarchboard.app/mcp. Ele usa Streamable HTTP e OAuth, então não há chave de API para copiar. Quando seu app se conecta, ele abre a página de login do Archboard; você entra com Google ou GitHub e aprova o acesso que o app pede.

Na tela de consentimento, você escolhe quais organizações e espaços de trabalho o app pode usar e o que ele pode fazer em cada um: ler, editar ou excluir (mover diagramas para a lixeira). Depois, em Configurações > Aplicativos conectados, você pode renomear o app, mudar o que ele pode usar e fazer ou remover o acesso dele.

Configuração em alguns apps comuns:

Claude (web e desktop). Abra Customize > Connectors, escolha Add custom connector e informe https://getarchboard.app/mcp. Nos planos Team e Enterprise, um Owner primeiro o adiciona em Organization settings > Connectors; depois você se conecta por Customize > Connectors.

Claude Code.

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

Depois rode /mcp em uma sessão para fazer login.

Cursor. Adicione o servidor ao ~/.cursor/mcp.json:

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

VS Code. Adicione-o ao seu mcp.json (o VS Code usa uma chave servers):

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

Outros apps. Adicione https://getarchboard.app/mcp como servidor MCP remoto nas configurações de conectores ou de MCP do app, onde o seu plano permitir. O app precisa de login OAuth sem segredo do cliente (client secret); a documentação do MCP traz os detalhes para quem desenvolve clientes.

Um exemplo completo: uma loja online, do rascunho à revisão

Aqui está uma sessão com um agente conectado ao Archboard. Os prompts são do tipo que você digitaria; os nomes de ferramentas entre parênteses são o que o agente chama nos bastidores.

1. Peça um primeiro rascunho

Desenhe um diagrama de contêineres C4 para a nossa loja online: um aplicativo web, uma API, um worker em segundo plano que envia os e-mails de pedidos pelo nosso provedor de e-mail, um banco de dados PostgreSQL e o Stripe para pagamentos. Coloque tudo o que nós mesmos operamos dentro de um limite do sistema.

O agente escolhe um espaço de trabalho (list_workspaces), procura os tipos de nó C4 de que precisa (search_node_types) e cria o diagrama (create_diagram). Em seguida, renderiza um snapshot (render_snapshot) para conferir que nada se sobrepõe e que toda conexão tem rótulo, e mostra o resultado na conversa (show_diagram).

O rascunho é um ponto de partida. O agente escolheu os contêineres a partir da sua frase; ele não tem como saber que o worker também lê do banco de dados, a menos que você diga.

2. Edite com palavras, revise no canvas

O worker também lê os pedidos do banco de dados. Adicione um cache Redis entre a API e o PostgreSQL e rotule cada conexão com o protocolo.

O agente lê o diagrama atual (get_canvas) e aplica um único lote de operações (apply_ops). Se você está com o diagrama aberto, vê os novos nós aparecerem ao lado de um cursor identificado com o app e o seu nome. Colegas que estão com o diagrama aberto veem a mesma coisa.

Este é o diagrama depois dos dois primeiros prompts:

3. Desfaça o que não gostar

Desfaça a última alteração.

Cada alteração de um agente é um passo. O agente pode reverter a própria alteração (revert_change), ou você pode desfazê-la em um passo pelo aviso de desfazer que aparece no editor logo depois da alteração. Campos que outra pessoa mudou nesse meio-tempo são mantidos.

4. Faça perguntas sobre um diagrama existente

Quais contêineres falam com o PostgreSQL, e por qual protocolo?

Para uma pergunta assim, o agente só lê (get_canvas). Explicar um diagrama existente para uma pessoa nova no time é uma das coisas mais úteis que um agente faz, e isso não exige nenhum acesso de escrita.

Prompts que funcionam bem

• Diga o tipo de diagrama. "Diagrama de contêineres C4", "diagrama de Kubernetes com um frame por namespace", "processo BPMN com uma raia por time". Assim o agente usa o pack de nós correspondente em vez de caixas genéricas.
• Diga o que fica dentro de cada limite. Frames, namespaces e VPCs carregam significado, então diga ao agente o que vai onde.
• Peça conexões rotuladas. "Rotule cada conexão com protocolo e porta" transforma setas em documentação.
• Mantenha cada alteração pequena. Um pedido por alteração é mais fácil de revisar e de desfazer do que uma reescrita.
• Peça ao agente que confira o próprio trabalho. "Renderize um snapshot e corrija as sobreposições" pega problemas de layout antes de você olhar.
• Peça um resumo. "Liste o que você mudou" dá a você uma nota de revisão para o pull request ou o chat do time.

Quem controla o quê

Conectar um app de IA aos diagramas em que seu time trabalha levanta perguntas justas. Estas são as regras que o Archboard aplica:

• Você escolhe o escopo. Um app só vê as organizações e os espaços de trabalho que você permitiu e só faz ali o que você permitiu: ler, editar ou excluir. O que ele pode fazer de fato é o mais restritivo entre essa configuração, os escopos que recebeu, o seu papel e o seu plano.
• As alterações são visíveis e têm autoria. O cursor e as alterações de um agente são identificados com o app e a pessoa para quem ele trabalha, no canvas e no histórico de versões.
• Desfazer é um passo. Você pode desfazer uma alteração do seu agente pelo aviso de desfazer no editor ou pedir ao agente que a reverta em até 7 dias. Proprietários e administradores da organização também podem desfazê-la.
• Excluir tem volta. Um agente precisa da permissão Excluir para mover um diagrama para a lixeira, e o Archboard orienta os agentes a fazer isso só quando você pedir. Você pode restaurar o diagrama pela Lixeira.
• Texto no diagrama é dado. O Archboard orienta os agentes a tratar rótulos, notas e nomes em um diagrama como dados, nunca como instruções, e a adicionar imagens só quando você pedir.

Quando usar um agente e quando desenhar à mão

Agentes são bons em primeiros rascunhos, edições repetitivas ("renomeie todo serviço orders-* para checkout-*"), em manter um diagrama alinhado com uma mudança que você está fazendo de qualquer forma e em explicar um diagrama que outra pessoa desenhou. Um agente de código que acabou de mudar um serviço pode atualizar o diagrama de arquitetura na mesma sessão.

Desenhar à mão ainda é melhor para decidir o que importa. Um diagrama é um argumento sobre um sistema, e escolher o que deixar de fora é uma questão de julgamento. Deixe o agente digitar e fique com o julgamento.

Limites que você precisa conhecer

• Os limites do plano valem. O MCP funciona em todos os planos, com os mesmos limites de plano do editor. No plano Free, isso significa 3 diagramas e, por diagrama, 15 nós de diagrama mais 150 notas, textos, figurinhas e tópicos de mapa mental.
• As chamadas de ferramentas têm limite de taxa por minuto. Quando um agente atinge o limite, o Archboard informa quanto tempo esperar antes de tentar de novo.
• O agente só sabe o que você conta e o que está no diagrama. Pelo Archboard, ele não vê seu cluster em execução nem sua base de código. Se uma dependência importa, diga, ou deixe um agente de código ler o código.

Perguntas frequentes

Quais apps de IA podem se conectar ao Archboard? Apps que conseguem adicionar um servidor MCP remoto com login OAuth e não exigem segredo do cliente. A página de agentes de IA tem configuração rápida para Claude, Cursor, VS Code, Claude Code e outros.

O Archboard usa um modelo de IA próprio? Não. O Archboard é o espaço de trabalho dos diagramas; quem raciocina é o app de IA que você conecta.

O agente consegue ver todos os meus diagramas? Só as organizações e os espaços de trabalho que você permitiu ao conectá-lo, com a permissão que você escolheu para cada um. Por padrão, são todos, inclusive aqueles em que você entrar depois, com permissão Excluir; você pode restringir isso na tela de consentimento ou depois em Configurações > Aplicativos conectados.

Posso desfazer o que o agente fez? Sim. Cada alteração do agente é um passo que você pode desfazer pelo aviso de desfazer no editor, e o app pode reverter as próprias alterações dos últimos 7 dias.

Funciona no plano Free? Sim. O MCP funciona em todos os planos, com os mesmos limites de plano do editor.

Comece grátis — um assento, sem cartão de crédito.