If you've asked an AI agent for an AWS architecture diagram, you've probably seen something like this: rounded icons and boxes, tangled lines, and a general feeling that nobody would ship it as is.
I wanted to know whether the fix was a better tool or a better prompt. So I gave the same architecture to five setups, including AWS's and draw.io's official MCP servers and skills, and kept adding instructions whenever something looked off. By the end, every setup had improved a lot, and a plain Claude Code session with no MCP server or skill did as well as any of them. This is the diagram it drew with the final prompt.
I ran everything in September 2026 on Claude Code 2.1.278 with Claude Opus 5. The prompts were in Japanese, and the prompts below are my English translations, minus the line that set the label language. For this post, I replaced the Japanese labels in the .drawio outputs with English ones and re-exported them; the layout and lines are unchanged. The Diagram MCP Server only outputs PNG, so the first image in this post is a new run of the same prompt in English (Claude Code 2.1.285, same model).
The five setups I compared
| # | Setup | Output |
|---|---|---|
| 1 | AWS Diagram MCP Server 1.0.23 (MCP, deprecated) | PNG only |
| 2 |
aws-architecture-diagram skill from AWS |
.drawio (PNG, SVG, PDF on request) |
| 3 | draw.io's official MCP Tool Server | A URL that opens draw.io (can edit existing .drawio files) |
| 4 | draw.io's official Claude Code plugin (skill) | .drawio (PNG, SVG, PDF, URL on request) |
| 5 | Plain Claude Code, no MCP server or skill | Whatever you ask for |
Links: AWS Diagram MCP Server, aws-architecture-diagram skill, draw.io MCP Tool Server, draw.io Claude Code plugin, Claude Code docs.
The first one is the reason I started. AWS deprecated the Diagram MCP Server in March 2026, and every release on PyPI has since been yanked. The notice says the diagram skill in the deploy-on-aws plugin "generates equivalent diagrams directly through Claude Code without requiring a running MCP server." Equivalent, not better. I wanted to see what that looks like in practice.
For setups 2 to 5, I asked for draw.io XML so I could compare .drawio files. Setup 1 can only produce PNG, so I changed the last line of its prompt to ask for a PNG.
What a usable diagram means
For a diagram I'd actually use at work, I looked at six things.
- Reproducibility. The same prompt should give roughly the same diagram every time
- Cost. Fewer tokens and less time
- Faithfulness. Only what I asked for, with no extra numbering or explanation panels
- Readability. Lines and labels don't overlap
- Look. No rounded icons or decorative boxes that make it look AI-generated
- Editability. Output I can fix by hand, which means a .drawio file
Keeping the comparison fair
Anything else loaded into Claude Code, such as my own skills, plugins, or CLAUDE.md, would affect the output. So I started each session with only the project settings and only the MCP server under test.
# AWS Diagram MCP Server, draw.io MCP Tool Server
claude --setting-sources project --strict-mcp-config --mcp-config mcp.json
# aws-architecture-diagram skill
claude --setting-sources project --strict-mcp-config --plugin-dir agent-plugins/plugins/deploy-on-aws
# draw.io Claude Code plugin
claude --setting-sources project --strict-mcp-config --plugin-dir drawio-mcp/plugins/claude-code
# Plain Claude Code
claude --setting-sources project --strict-mcp-config
Without --strict-mcp-config, MCP connectors I had set up in claude.ai (in my case, AWS documentation search) still show up in the session. I also tried --safe-mode, which turns off CLAUDE.md, skills, plugins, and MCP servers all at once, but it also turned off the plugins I wanted to compare, so it didn't work for this test.
Round 1: the same short prompt, five different problems
The first prompt only described the architecture.
Draw an architecture diagram of the following AWS setup.
- Put an ALB behind CloudFront
- The ALB targets an ECS Fargate service spread across two AZs
- The database is Aurora MySQL, with one writer and one reader in different AZs
- Static files are stored in S3 and delivered through CloudFront
- Logs and metrics are collected in CloudWatch
- The VPC spans two AZs, each with a public subnet and a private subnet
- The ALB is in the public subnets, ECS and Aurora are in the private subnets
- Each AZ has a NAT Gateway in its public subnet for outbound traffic from ECS
- Save the diagram as a draw.io XML file under out/
None of the five results was usable without edits, and each failed in its own way. The Diagram MCP Server gave me a tangled, rounded diagram like the one at the top of this post. AWS's skill added numbered badges and a data-flow panel I never asked for, and put a box around every service icon.
The draw.io MCP server and plugin were closer, but both had lines running over text. The MCP server also added notes I hadn't asked for, and the plugin rounded the corners of its lines. Plain Claude Code was fairly tidy, but colored S3 orange and printed service names both above and below the icons.
What I added to the prompt, and why
From there, I iterated round by round. Each time, I looked at all five outputs, picked what bothered me, and added one or two lines to the prompt. Some fixes caused new problems, which is why the list reads like a negotiation.
| What went wrong | What I added |
|---|---|
| Lines crossed text | Don't let lines overlap labels |
| To avoid overlaps, it dropped icons and drew plain boxes | Use the official AWS icons |
| ECS was still a box | Always use icons. No text outside the diagram |
| Line labels disappeared too | Line labels are fine. Public subnets go above private ones |
| Short notes and color coding disappeared | Short notes attached to elements are fine |
| AZs were named "A" and "C" | Use the full AZ names |
| Users were sometimes at the top, sometimes on the left | Put users at the top |
| Old and new icon designs were mixed | Use the latest icon set (this didn't work, so I dropped it) |
| Aurora used an instance icon | Use service-level icons. Labels go below icons |
| Lines left icons from a different spot every time | Start lines from the middle of an icon's edge |
The final prompt was the architecture plus these rules.
- Write AZ names in full, not as "A" or "B"
- Put users at the top of the diagram
- In each AZ, put the public subnet above the private subnet
- Always use the official AWS icons. Don't substitute boxes or circles. Use service-level icons, not icons for individual resources such as instances
- Put each icon's label below the icon
- Don't let lines cross icons or label text. Lines may start below a label. Lines must not run on top of each other, though they may cross
- Start lines from the middle of an icon's edge where possible
- No title, legend, or explanation panel outside the diagram. Line labels and short notes attached to elements are fine
Results
I ran the final prompt three times per setup. Time and tokens are averages across the three runs.
| Setup | Time | Output tokens | Reproducibility |
|---|---|---|---|
| AWS Diagram MCP Server | 5.5 min | 23,393 | Changes a lot between runs |
aws-architecture-diagram skill |
5.4 min | 33,510 | Changes in small ways |
| draw.io MCP Tool Server | 4.1 min | 25,439 | Nearly identical, but the NAT Gateway icon differs every run |
| draw.io Claude Code plugin | 5.8 min | 34,544 | Nearly identical, but S3 moves around |
| Plain Claude Code | 5.4 min | 32,805 | Nearly identical |
The Diagram MCP Server switched to curved lines and kept its rounded icons, and because it only outputs PNG, I couldn't fix anything by hand. AWS's skill produced a clean layout, but left out the lines to CloudWatch and the Aurora replication, and used the VPC icon for the NAT Gateways. The draw.io MCP server's lines were my personal favorite, but it made the same NAT Gateway mistake.
The draw.io plugin got the icons right with about the right amount of detail. Plain Claude Code had no crossing lines and varied the least across runs.
What I learned
Every setup improved a lot once the prompt said what a good diagram looks like. By the end, the draw.io MCP server, the draw.io plugin, and plain Claude Code were all at a level I'd use, and none of them clearly beat the others.
So the choice of MCP server or skill mattered less than being explicit about the result I wanted. It's the same with code. If you don't say what you want, you get comments you didn't need and abstractions you didn't ask for. Diagrams are no different.
Limits of this test
- Diagram taste is personal. Whether users go at the top or on the left, what to group, what to leave out. These rules reflect mine
- It's one architecture, a standard two-AZ web app. I didn't test multi-account, hybrid, or very large diagrams here
- Three runs per setup is enough to see tendencies, not to measure variance precisely
- The reproducibility column is a rough call from comparing the images (icon count, line count, and layout), not a precise metric
I turned the prompt into a skill
Writing that long prompt every time is tedious, so I packaged the rules into a Claude Code skill: sagochiko/aws-drawio-diagram-skill. With it, you only describe the architecture. I also tried it with English requests (four runs across two architectures), and it followed the same rules as it does with Japanese requests. This is what it drew from the Round 1 prompt above.
It also handles architectures without a VPC, such as an Amazon Bedrock AgentCore agent fronted by a Lambda function running Lambda Web Adapter.
I tested the skill later, on Claude Opus 5.5. There, one diagram took about 3 to 5 minutes and cost around US$1 or less. It's licensed under Apache 2.0 and builds on the official draw.io and AWS skills.
How do you get usable diagrams out of your AI agent? I'd like to hear what rules you've added.
This post was first published on AWS Builder Center. It is an English version of my original article in Japanese on Qiita. The diagrams use AWS Architecture Icons.
I wrote the Japanese original; this English version was rewritten with the help of AI.
Top comments (0)