{"slug": "drawing-architecture-diagrams-with-an-ai-agent-over-mcp", "title": "Drawing architecture diagrams with an AI agent over MCP", "summary": "A developer built an MCP-connected agent that draws architecture diagrams directly onto a shared whiteboard rather than emitting Mermaid or ASCII output. The agent calls tools like describe_format, validate_board and create_board to compose an entire diagram as a declarative board document, which the server validates before creating a draggable, editable board. Authorization runs through an OAuth flow with a consent screen that labels non-first-party clients as unverified, granting scoped, revocable sessions.", "body_md": "Ask any coding assistant to \"diagram this service\" and you get the same thing back: a fenced Mermaid block, or some ASCII boxes, or a PNG you drop into a doc and never touch again. It's fine. It's also a dead end — the moment a teammate wants to move a box, add a note, or present it, they're redrawing it by hand somewhere else.\n\nI wanted the other thing: an agent that draws onto a **real whiteboard** — a shared canvas my team already opens, with nodes you can drag, connectors that stay attached, and sticky notes you can argue in. So I wired one up over [MCP](https://modelcontextprotocol.io), and it turned out to be less work than I expected. Here's how it went.\n\nA Mermaid snippet is text that *renders* a diagram. A whiteboard is an artifact your team *works on*. Those are different objects with different half-lives:\n\nIf the agent can only produce the first, the human still has to do the translation into the second — which is exactly the tedious part. The interesting version of \"AI draws my\n\narchitecture\" is the one where the output *is* the shared artifact.\n\n[DrawlyHub](https://drawlyhub.com/demo?ref=devto) (the whiteboard I work on) exposes an MCP server. MCP is just a standard way for an AI client — Claude, an IDE agent, your own script — to discover a tool's capabilities and call them with your authorization. So instead of the agent printing diagram syntax, it calls tools like \"create a board,\"\n\n\"add a frame,\" \"place these nodes,\" \"connect A to B.\"\n\nConnecting it is the ordinary OAuth dance, and the one detail worth watching is the consent screen:\n\n`/.well-known/oauth-authorization-server` and discovers the endpoints.\nThat third step is the whole security model, and it's worth saying plainly: the agent can only ever act on your data *after you approve it on a screen you control*. A client that isn't one of the first-party apps shows up labeled **unverified**, so a look-alike can't dress itself up as something you trust. You're not handing out a\n\nstanding key; you're granting a scoped, revocable session to a named app.\n\nWith the agent connected, I asked for something concrete:\n\nDraw a three-tier web architecture on a new board: CloudFront in front of an ALB,\n\nan ECS service behind it, RDS and an S3 bucket below. Label the connectors with the protocol.\n\nWhat came back wasn't a code block — it was a board. Under the hood the agent doesn't poke the canvas box by box. It asks the server to `describe_format`, composes the whole diagram as one **board document**, validates it, and submits it:\n\n```\ndescribe_format()                      # learn the .drawly schema\n\nboard = {\n  \"format\": \"drawly-spec\", \"version\": 1,\n  \"title\": \"Three-tier web on AWS\",\n  \"frames\": [{\n    \"key\": \"request-path\", \"title\": \"Request path\",\n    \"elements\": [\n      {\"kind\": \"box\",  \"id\": \"cf\",  \"x\": 120, \"y\": 80,  \"w\": 200, \"h\": 80, \"text\": \"CloudFront\",  \"palette\": \"sky\"},\n      {\"kind\": \"box\",  \"id\": \"alb\", \"x\": 120, \"y\": 220, \"w\": 200, \"h\": 80, \"text\": \"ALB\",         \"palette\": \"sky\"},\n      {\"kind\": \"box\",  \"id\": \"ecs\", \"x\": 120, \"y\": 360, \"w\": 200, \"h\": 80, \"text\": \"ECS service\", \"palette\": \"violet\"},\n      {\"kind\": \"box\",  \"id\": \"rds\", \"x\": 420, \"y\": 360, \"w\": 200, \"h\": 80, \"text\": \"RDS\",         \"palette\": \"emerald\"},\n      {\"kind\": \"box\",  \"id\": \"s3\",  \"x\": 420, \"y\": 220, \"w\": 200, \"h\": 80, \"text\": \"S3 bucket\",   \"palette\": \"emerald\"},\n      {\"kind\": \"link\", \"id\": \"k1\", \"from\": \"cf\",  \"to\": \"alb\", \"text\": \"HTTPS\"},\n      {\"kind\": \"link\", \"id\": \"k2\", \"from\": \"alb\", \"to\": \"ecs\", \"text\": \"HTTP\"},\n      {\"kind\": \"link\", \"id\": \"k3\", \"from\": \"ecs\", \"to\": \"rds\", \"text\": \"5432\"},\n      {\"kind\": \"link\", \"id\": \"k4\", \"from\": \"ecs\", \"to\": \"s3\",  \"text\": \"SDK\"}\n    ]\n  }]\n}\n\nvalidate_board(document=board)         # dry-run: catches a dangling link or bad id\ncreate_board(document=board)           # creates it, hands back the board's URL\n```\n\nThe declarative shape is the nice part: the agent authors the *whole* diagram as data, `validate_board` catches a connector pointing at nothing before anything is created, and `create_board` returns a URL. Connectors are `link` elements that reference box ids, so\n\nthey stay attached when you move a box around later.\n\nI opened the board URL and the boxes were there, wired up, laid out on a frame I could pan and zoom. Then I did the thing you can't do with a Mermaid block: I grabbed the RDS box and moved it, dropped a sticky note on the ECS box that said \"autoscaling TBD,\"\n\nand sent the link to a teammate to finish.\n\nFor the parts that genuinely are better as code than as hand-placed boxes — a sequence diagram, say — the agent can drop a **Mermaid container** onto the board instead, so the diagram renders from text but still lives on the same canvas as everything else. Text\n\nwhere text wins, boxes where boxes win, one surface either way.\n\nThis is early, and I'd rather tell you than have you find out:\n\nIf you build something fun with it — or break it — I'd genuinely like to hear about it.\n\nThe gap between \"AI output\" and \"a thing my team actually uses\" is the whole reason this exists, and MCP turned out to be the clean way to close it.", "url": "https://wpnews.pro/news/drawing-architecture-diagrams-with-an-ai-agent-over-mcp", "canonical_source": "https://dev.to/sheel_khanna_418791d4d635/drawing-architecture-diagrams-with-an-ai-agent-over-mcp-4769", "published_at": "2026-11-15 03:10:28+00:00", "updated_at": "2026-11-15 03:21:37.380983+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["DrawlyHub", "MCP", "Claude", "CloudFront", "ALB", "ECS", "RDS", "S3"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/drawing-architecture-diagrams-with-an-ai-agent-over-mcp", "markdown": "https://wpnews.pro/news/drawing-architecture-diagrams-with-an-ai-agent-over-mcp.md", "text": "https://wpnews.pro/news/drawing-architecture-diagrams-with-an-ai-agent-over-mcp.txt", "jsonld": "https://wpnews.pro/news/drawing-architecture-diagrams-with-an-ai-agent-over-mcp.jsonld"}}