For a usable AWS architecture diagram in Claude Code, describe not only the services but also the layout, icon style, labels, and connector rules you expect. In a September 2026 comparison, Ryota Sago found that sharpening those prompt instructions improved all five tested approaches substantially; after that, no single integration clearly won. The result is a useful workflow lesson, not a general benchmark: it covers one two-AZ design, three runs per setup, and Claude Code 2.1.278 with Claude Opus 5.
What the five-way comparison tested
Sago compared five ways to make Claude Code produce an AWS architecture diagram in September 2026, using Claude Code 2.1.278 with Claude Opus 5. The example was a two-Availability Zone web application with CloudFront, an Application Load Balancer, ECS Fargate, Aurora MySQL writer and reader instances in different AZs, S3 static files, CloudWatch logs and metrics, public and private subnets, and one NAT Gateway per AZ.
As an Amazon Associate I earn from qualifying purchases.
The approaches were AWS Diagram MCP Server 1.0.23, AWS’s aws-architecture-diagram skill, draw.io’s MCP Tool Server, draw.io’s Claude Code plugin, and plain Claude Code without an MCP server or skill. To make files comparable and editable, Sago requested draw.io XML from setups two through five; the AWS Diagram MCP Server produced PNG only. He assessed reproducibility, cost, fidelity to requirements, readability, visual style, and editability. His full account is in Sago’s comparison.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why prompt detail mattered
The initial prompt mostly named components and their placement. Sago reports that none of the five first outputs was usable without edits. Defects included labels crossed by lines, extra panels or notes, generic boxes where AWS icons were expected, inconsistent service labels, and distracting shapes.
#1 Best Overall
He then made the desired visual result explicit. His final instructions included:
- Spell out Availability Zone names and put users at the top.
- Place public subnets above private subnets.
- Use official, service-level AWS icons and put labels beneath them.
- Keep connectors off icons and label text; where possible, start lines at the midpoint of icon edges.
- Allow line crossings only when the lines do not overlap one another.
- Omit a separate title, legend, or explanation panel, while allowing line labels and short notes attached to relevant elements.
These are the preferences that worked for Sago’s example, not universal diagram rules. The broader lesson is to separate two kinds of instructions: what the architecture contains and how the finished diagram should communicate it. A component list alone does not specify hierarchy, grouping, or how to handle crowded connections.
A prompt structure you can adapt
Start with the architecture and relationships, then state the presentation constraints and output format separately. For example:
Architecture: [list services, network boundaries, and required connections. State which instances or components belong in which AZ or subnet.]
Layout: Put [entry point] at the top. Group resources by [VPC, AZ, subnet, or other boundary]. Place [group A] above [group B].
Visuals: Use official service-level AWS icons. Put each service label below its icon. Keep connectors clear of icons and text; route them from icon edges where practical. Do not overlap connector lines.
Content: Include [required relationships, labels, and notes]. Do not add a separate title, legend, or explanatory panel.
Output: Create an editable draw.io XML file.Replace the bracketed text with the real design. Be specific about relationships, not just inventory: for example, name the writer and reader placement and describe which components connect to which others. If you need to revise the result, add a rule in response to a visible problem rather than piling on abstract instructions.
Check architecture correctness separately from appearance
A clean layout can still misrepresent the system. In Sago’s final-prompt runs, the AWS skill omitted CloudWatch and Aurora replication lines; both that skill and draw.io MCP used a VPC icon for NAT Gateways. Those are semantic errors, not cosmetic ones. Compare the diagram against the required components and connections before judging whether the layout looks polished.
- Completeness: Are all requested services present?
- Relationships: Are data paths, replication, logging, and network connections represented as specified?
- Identity: Does each icon and label identify the intended AWS service?
- Readability: Can a reader follow connectors without lines obscuring icons or labels?
What the final runs showed
Sago ran the final prompt three times per setup. The time and output-token counts below are his reported averages across those three runs, not independently reproduced measurements. His reproducibility descriptions were rough visual judgments.
| Approach | Output in comparison | Average time per run | Average output tokens | Reported variation |
|---|---|---|---|---|
| AWS Diagram MCP Server 1.0.23 | PNG only | 5.5 minutes | 23,393 | Results changed a lot between runs |
AWS aws-architecture-diagram skill |
draw.io XML | 5.4 minutes | 33,510 | Small changes between runs |
| draw.io MCP Tool Server | draw.io XML | 4.1 minutes | 25,439 | Nearly identical, although the NAT Gateway icon differed each run |
| draw.io Claude Code plugin | draw.io XML | 5.8 minutes | 34,544 | Nearly identical, although S3 moved around |
| Plain Claude Code | draw.io XML | 5.4 minutes | 32,805 | Nearly identical |
Across these five setups, Sago’s reported averages ranged from 4.1 to 5.8 minutes per run and from 23,393 to 34,544 output tokens. These figures describe his particular setup and prompt. They are not reliable estimates for other architectures, models, versions, or workloads.
Recommended Free Tools
He considered the draw.io MCP server, draw.io plugin, and plain Claude Code outputs good enough for his use, with no clear winner. His conclusion was that “the choice of MCP server or skill mattered less than being explicit about the result I wanted.”
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose based on the file and workflow you need
For the comparison’s four draw.io XML outputs, editability was part of the requested format; the AWS Diagram MCP Server’s PNG-only output offered less direct scope for editing the diagram as a draw.io file. If you expect to fix labels, reposition services, or correct connectors by hand, ask for an editable artifact from the outset. If a rendered image is all you need, an image output may suffice, but it does not meet the same editability requirement.
Tool choice still matters for dependencies and output, but this comparison does not establish that a particular integration is best for every design. It tested one standard two-AZ architecture, one model/version combination, and three runs per setup. Sago did not test multi-account, hybrid, or very large diagrams, and users may prefer different grouping and placement.
Check AWS tool and icon status before starting
Tool availability can change. In a June 2026 update, AWS said the original awslabs.aws-diagram-mcp-server was deprecated and all versions had been removed from PyPI. AWS said its diagram agent skill in the deploy-on-aws plugin superseded it, and recommended diagrams-mcp for the Kiro CLI tutorial. That notice concerns the original server; check AWS’s update for the current status before following an older setup guide.
Use AWS’s architecture icon resources when the diagram needs AWS service icons. AWS says customers and partners may use its toolkits and assets in diagrams, and advises checking third-party icon libraries for legacy sets. Its page describes quarterly releases at the end of January, April, and July, with no Q4 release, so an icon library’s freshness is worth checking.
If you prefer text-first diagrams that can live alongside code, Mermaid Chart describes an MCP server that generates, validates, and renders diagrams from Claude, including AWS architecture mapping. That is a vendor-described alternative, not a result tested in Sago’s comparison; see Mermaid Chart’s product information. Separately, an AWS sample repository demonstrates an MCP-server pattern that produces editable draw.io files and a neutral JSON handoff. It distinguishes diagram generation from pricing or deployment, and should be treated as an implementation example rather than proof that the five tested setups behave the same way.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
