How to Create Architecture Diagrams with AI Agents (MCP)

AI assistants are good at turning a description into a diagram. The trouble starts the day after. A diagram that lives as a PNG in a chat, or as a Mermaid snippet in a pull request, is a copy. Nobody updates the copy, and a month later it disagrees with the system it describes.

The Model Context Protocol (MCP) changes where the agent works. Instead of handing you an image, an agent connected to Archboard over MCP reads and edits the same structured diagram your team opens in the browser. Its changes appear on the canvas live, labeled with the person it works for, and that person can undo them in one step.

This guide shows how to connect an AI app to Archboard, walks through a worked example from first draft to review, and covers the prompts, permissions and limits that matter in practice.

What an agent can do with Archboard

Archboard diagrams are made of typed nodes from node packs: a Kubernetes Deployment, a cloud database, a C4 container or a BPMN task is a node with ports and properties, not a box with a label. Over MCP an agent can:

• List and read the diagrams it has access to, as an outline (frames, counts, who is working on it) or as full node and edge records.
• Create a diagram from a description, from a list of operations, or from a Mermaid flowchart mapped to real node types.
• Edit a diagram with a batch of operations applied as one change: add nodes, connect ports, move, restyle or remove.
• Check its work by rendering a PNG snapshot, and show the diagram inside the conversation in apps that support MCP Apps.
• Undo one of its own changes.

Archboard does not include its own AI model. You bring the agent: Claude, Cursor, VS Code or another app that can add a remote MCP server with OAuth sign-in. The AI agents page has a short overview.

Connect your AI app

Archboard's MCP server lives at https://getarchboard.app/mcp. It uses Streamable HTTP and OAuth, so there is no API key to copy. When your app connects, it opens the Archboard sign-in page; you sign in with Google or GitHub and approve the access the app asks for.

On the consent screen you choose which organizations and workspaces the app can use and what it may do in each: read, edit, or delete (move diagrams to the trash). You can rename the app, change what it can use and do, or remove its access later under Settings > Connected apps.

Setup in a few common apps:

Claude (web and desktop). Open Customize > Connectors, choose Add custom connector and enter https://getarchboard.app/mcp. On Team and Enterprise plans, an Owner adds it under Organization settings > Connectors first; then you connect from Customize > Connectors.

Claude Code.

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

Then run /mcp in a session to sign in.

Cursor. Add the server to ~/.cursor/mcp.json:

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

VS Code. Add it to your mcp.json (VS Code uses a servers key):

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

Other apps. Add https://getarchboard.app/mcp as a remote MCP server in the app's connector or MCP settings, where your plan allows it. The app needs OAuth sign-in without a client secret; the MCP documentation has the details for client developers.

A worked example: an online shop, from draft to review

Here is a session with an agent connected to Archboard. The prompts are the kind you would type; the tool names in parentheses are what the agent calls behind the scenes.

1. Ask for a first draft

Draw a C4 container diagram for our online shop: a web app, an API, a background worker that sends order emails through our email provider, a PostgreSQL database and Stripe for payments. Put everything we run inside a system boundary.

The agent picks a workspace (list_workspaces), looks up the C4 node types it needs (search_node_types) and creates the diagram (create_diagram). It then renders a snapshot (render_snapshot) to check that nothing overlaps and that every edge is labeled, and shows the result in the conversation (show_diagram).

The draft is a starting point. The agent chose the containers from your sentence; it cannot know that the worker also reads from the database unless you say so.

2. Edit with words, review on the canvas

The worker also reads orders from the database. Add a Redis cache between the API and PostgreSQL, and label every edge with its protocol.

The agent reads the current diagram (get_canvas) and applies one batch of operations (apply_ops). If you have the diagram open, you see the new nodes appear next to a cursor labeled with the app and your name. Teammates who have the diagram open see the same thing.

This is the diagram after the first two prompts:

3. Undo what you don't like

Undo the last change.

Each agent change is one step. The agent can revert its own change (revert_change), or you can undo it in one step from the undo notice that appears in the editor right after the change. Fields someone else changed in the meantime are kept.

4. Ask questions about an existing diagram

Which containers talk to PostgreSQL, and over what?

For a question like this the agent only reads (get_canvas). Explaining an existing diagram to a new teammate is one of the most useful things an agent does, and it needs no write access at all.

Prompts that work well

• Name the kind of diagram. "C4 container diagram", "Kubernetes diagram with one frame per namespace", "BPMN process with a lane per team". The agent then uses the matching node pack instead of generic boxes.
• Say what belongs inside each boundary. Frames, namespaces and VPCs carry meaning, so tell the agent what goes where.
• Ask for labeled edges. "Label every edge with protocol and port" turns arrows into documentation.
• Keep each change small. One request per change is easier to review and to undo than a rewrite.
• Ask the agent to check its work. "Render a snapshot and fix any overlaps" catches layout problems before you look.
• Ask for a summary. "List what you changed" gives you a review note for the pull request or the team chat.

Who controls what

Connecting an AI app to the diagrams your team works on raises fair questions. These are the rules Archboard enforces:

• You choose the scope. An app sees only the organizations and workspaces you allowed, and does only what you allowed there: read, edit or delete. What it may actually do is the lowest of that setting, the scopes it was granted, your role and your plan.
• Changes are visible and attributed. An agent's cursor and changes are labeled with the app and the person it works for, on the canvas and in version history.
• Undo is one step. You can undo an agent's change from the undo notice in the editor, or ask the agent to revert it within 7 days. Organization owners and admins can undo it too.
• Deleting is recoverable. An agent needs delete permission to move a diagram to the trash, and Archboard tells agents to do it only when you ask. You can restore the diagram from Trash.
• Text in a diagram is data. Archboard tells agents to treat labels, notes and names in a diagram as data, never as instructions, and to add images only when you ask for them.

When to use an agent, and when to draw by hand

Agents are good at first drafts, repetitive edits ("rename every orders-* service to checkout-*"), keeping a diagram in step with a change you are making anyway, and explaining a diagram someone else drew. A coding agent that has just changed a service can update the architecture diagram in the same session.

Drawing by hand is still better for deciding what matters. A diagram is an argument about a system, and choosing what to leave out is a judgment call. Let the agent do the typing and keep the judgment.

Limits to know

• Plan limits apply. MCP works on every plan with the same limits as the editor. On the Free plan that is 3 diagrams, and 15 diagram nodes plus 150 notes, text, stickers and mind map topics per diagram.
• Tool calls are rate limited per minute. When an agent hits the limit, Archboard tells it how long to wait before it retries.
• The agent only knows what you tell it and what is in the diagram. It cannot see your running cluster or your codebase through Archboard. If a dependency matters, say so, or let a coding agent read the code.

FAQ

Which AI apps can connect to Archboard? Apps that can add a remote MCP server with OAuth sign-in and don't require a client secret. The AI agents page has quick setup for Claude, Cursor, VS Code, Claude Code and others.

Does Archboard use its own AI model? No. Archboard is the diagram workspace; the AI app you connect does the reasoning.

Can the agent see all of my diagrams? Only the organizations and workspaces you allowed when you connected it, with the permission you chose for each. By default that is all of them, including ones you join later, with delete permission; you can narrow it on the consent screen or later under Settings > Connected apps.

Can I undo what the agent did? Yes. Every agent change is one step you can undo from the undo notice in the editor, and the app can revert its own changes from the last 7 days.

Does it work on the Free plan? Yes. MCP works on every plan, with the same limits as the editor.

Start free — one seat, no credit card.