Validate your events with Bufstream Validate your events with Bufstream Tired of chasing weird side effects in your event-driven systems? Bufstream is a Kafka-compatible broker that validates events right at the source — before they ever reach your topics. No more debugging downstream validation failures. Try Bufstream → ❤️ Sponsored content — supporting quality content about AWS and serverless.

Introduction

Let's face it: In most cases, drawing AWS architecture diagrams is no fun. You
spend hours dragging boxes around in Lucidchart or draw.io, trying to make
everything line up properly. It's hard to find proper icons for all the AWS
services and requires manual work. In the end, your diagram looks like a
kindergarten art project compared to the polished ones in AWS whitepapers. Or it
looks good, but it doesn't matter, because when it's finished, it's already
outdated.

Most of us hate this process, but we do it anyway because people need visuals.
Not only stakeholders, but also developers. Documentation requires diagrams.
Architecture reviews demand them. You end up with inconsistent styling across
different diagrams because everyone uses different tools and templates. Looking
at any Confluence of any company, you'll see that diagrams with different styles
are everywhere.

Amazon Q with MCP servers tries to change this. You describe your architecture
in plain English, and it generates the diagram for you. No more pixel-perfect
alignment headaches or searching for the latest service icons.

At least that's the idea. 😶‍🌫️ Let's dive into the current state of the art, the
pros and cons of this approach and how to get the best out of it.

What You'll Learn

I'll show you how to set up Amazon Q with two MCP servers that handle diagram
generation. The AWS Diagram MCP server does the actual drawing work. The AWS
Documentation MCP server provides current service information via the AWS
documentation and best practices.

We'll start with basic examples like a simple web app, then move to complex
multi-region setups. I'll share the prompting tricks I've learned for getting
better results. We'll also talk about where this approach falls short, because
it's not perfect.

Why MCP Servers Matter for Diagram Generation

MCP servers give Amazon Q superpowers it doesn't have by default. Think of them
as plugins that add specific capabilities.

• The diagram server knows how to create proper AWS architecture diagrams.
• The documentation server has access to current AWS service details.

Without these servers, Amazon Q can only work with whatever was in its training
data. That means outdated service information and no actual diagram generation
capabilities. With MCP servers, it can create diagrams using current AWS
services and best practices.

This combination is powerful.

Amazon Q can look up service documentation in real-time and use that information
to build accurate diagrams via an underlying tool.

Prerequisites and Setup

The following steps obviously all require that you have an AWS account & AWS
Builder ID. Besides that, we'll need to install some software on your machine.

Installing Amazon Q

Amazon Q is available as a desktop app. You can download it from the
Amazon Q homepage.

If you're using macOS, you can install it via Homebrew too:

brew install --cask amazon-q

Once installed, you can check that everything works properly by running
q --version in your preferred terminal. You'll also need to login via
q login.

Either use your AWS Builder ID for free or the pro license. In our case, we'll
use the free version (which has limitations on how many requests you can make).

Installing MCP Servers

Now that we have Amazon Q installed, we can install the MCP servers. The MCP
servers are available via Python packages.

This means we need to have Python and pip installed on our machine. If you
don't, please first install pip via your package manager of choice.

Afterward, we can get uv (the package manager for Python) to install Python.

pip install uv
uv python install 3.12

As the MCP tool needs to render the graph, we also need to install
Graphviz. It's also available via
Homebrew:

brew install graphviz

Now we're ready to add the MCP servers into Q's configuration!

{
    "mcpServers": {
        "awslabs.aws-diagram-mcp-server": {
            "command": "uvx",
            "args": ["awslabs.aws-diagram-mcp-server"],
            "env": {
                "FASTMCP_LOG_LEVEL": "ERROR"
            },
            "autoApprove": [],
            "disabled": false
        },
        "awslabs.aws-documentation-mcp-server": {
            "command": "uvx",
            "args": ["awslabs.aws-documentation-mcp-server@latest"],
            "env": {
                "FASTMCP_LOG_LEVEL": "ERROR"
            },
            "autoApprove": [],
            "disabled": false
        }
    }
}

Please add the following JSON to your ~/.aws/amazonq/mcp.json file.

If you're not aware what MCP is, in a nutshell, it's a standard protocol for
making AI agents talk to tools. Each MCP server is an application that tells
the AI agent how to talk to it. It can offer different commands or functions.
In our case for example, the diagram server provides a generate_diagram
function. This function takes a description of the architecture and returns a
diagram by using Python code and the Graphviz library.

Testing Your Setup

Now let's check if our setup works as expected by starting Q via q chat. You
should see that Q starts and loads our added MCP servers:

If this is true, we're already ready to start creating diagrams! ✨

Running Your First Diagram Command

Let's start with a very simple example. Creating a diagram of a simple server
backend.

Please create a diagram of a serverless API powered by AWS Lambda that is exposed via an API Gateway.

You should see that Q starts to work on our request by displaying Thinking...
in the bottom left corner.

If Q needs to run MCP commands, it will display a message like this. You'll need
to confirm the calls either via:

• y (confirm once just for this call)
• or t (to trust the call for all future calls in this session)

In the example screenshot, we can see that Q wants to run the
get_diagram_examples function to get a list of available diagram examples to
learn from.

Let's confirm the call and all future calls of this function via t. Q will ask
for many more calls to be trusted. Let's confirm all of them.

At the end, we'll be notified that the generation was successful. It will also
show where the diagram is stored. By default, it will be stored in the current
directories' generated-diagrams folder.

What do we notice in our case?

We've never talked about DynamoDB, but Q did use it anyway. That's because we
weren't explicit enough in our architecture description. Even if we were more
precise, there's still a chance that Q will come up with something we've not
specified as the output is never 100% deterministic.

Nevertheless, the result doesn't look too bad!

Configuration Options

There are a few settings that you can configure:

• Styling: Use your favorite colors and shapes.
• Format: It's possible to request other formats like SVG (PNG is the
  default).
• Output directory: As mentioned, everything will be stored in the
  generated-diagrams folder by default. It's up to you to change this.

Creating Architecture Diagrams

Let's continue with some more complex examples and see how Q handles them.

Detailed Example

Now we try to create a diagram of a three-tiered web application. In comparison
to our first try, let's be way more specific.

Create a diagram of a simple three-tier web application architecture using AWS services.
Requirements:
- Only include the AWS services and components described below.
- Do not add any extra components, services, or icons beyond what is described.
Components:
1.	Client Layer:
    A single "User" accessing the application via a web browser (represented as an external entity, not an AWS service).
2.	Application Layer:
    One "Amazon EC2 Instance" running the web application.
3.	Database Layer:
    One "Amazon RDS Instance" (for example, using MySQL or PostgreSQL).
Connections:
- The User connects to the Amazon EC2 instance.
- The Amazon EC2 instance connects to the Amazon RDS instance.
Labels:
- Clearly label each component as follows: "User", "Amazon EC2", and "Amazon RDS".
Restrictions:
- Do not include any load balancers, VPCs, subnets, security groups, auto-scaling, caching, monitoring, IAM roles, or any other AWS or third-party services not explicitly listed above.

Instead of simply writing a text, we've structured our request properly. It's
way more detailed and should get better results.

The result looks exactly as we described it. No hallucinated components, no
extra services.

It's simple, but on point! Obviously, it's not a real-world layered
architecture, as most details are missing like VPCs, public and private subnets,
load balancers, etc.

Let's change that and add some more details.

Create a diagram of a three-tier web application architecture using AWS services.
Requirements:
- Only include the AWS services and components described below.
- Do not add any extra components, services, or icons beyond what is described.
Components:
1.	VPC:
    One "Amazon VPC" containing all resources.
    One "Public Subnet" within the VPC.
    One "Private Subnet" within the VPC.
2.	Client Layer:
    A single "User" accessing the application via a web browser (external to AWS).
3.	Application Layer:
    One "Application Load Balancer" in the public subnet.
    One "Amazon EC2 instance" in the public subnet, running the web application.
4.	Database Layer:
    One "Amazon RDS instance" in the private subnet.
Connections:
- The User connects to the Application Load Balancer.
- The Application Load Balancer forwards traffic to the Amazon EC2 instance.
- The Amazon EC2 instance connects to the Amazon RDS instance.
Labels:
- Clearly label each component as follows: "User", "VPC", "Public Subnet", "Private Subnet", "Application Load Balancer", "Amazon EC2", and "Amazon RDS".
Restrictions:
- Do not include any other AWS services, such as security groups, NAT gateways, internet gateways, auto-scaling, monitoring, IAM roles, or any third-party services not explicitly listed above.

Great result! We do have a little text overflow, but that's not a big deal.

Best Practices for Prompting

So what are the best practices for prompting Q for our architecture diagrams?
We've already learned that we need to be specific and detailed.

Let's expand on that.

Adding Context and Requirements

The biggest mistake you can make is being vague about what you want. If you
don't specify the requirements, Q will likely hallucinate components that are
not part of your architecture.

We need to be precise and specific.

A good general approach is to include the sections we've used in our previous
examples.

• Requirements: Specify the requirements for the diagram. This can be kept
  general.
• Components: List the components that should be included in the diagram. By
  being specific, we can avoid that Q comes up with components that do not exist
  in our case.
• Connections: List the connections between the components. Let's make sure
  the connections between components are correct.
• Labels: List the labels for the components. This might be helpful to avoid
  confusion and auto-generated labels that are not what you want.
• Restrictions: List the restrictions for the diagram. What should be
  excluded?

For the requirements, the example from our first try is a good starting point.

- Only include the AWS services and components described below.
- Do not add any extra components, services, or icons beyond what is described.

You can obviously iterate on this as long as you want to get the best results.

Using Meta Prompting

Let's do an "Inception" on our process of the creation. Why do we need to write
the prompt on our own?

Let's go one level up and ask Q to create a basic prompt template we can use to
create the diagram. This way, we'll likely get better results.

Let's create a prompt that I can use to create technical diagrams via Amazon Q and its diagram creation MCP.
The prompt should be very specific and make sure that Q doesn't add any components that we didn't describe.
It should be very precise and the output should be as deterministic as possible, but I don't want to explicitly describe where the components should be placed.

When we put this into Q with Sonnet 4.0, we'll get a nice prompt template that
we can re-use.

Limitations and Drawbacks

Most obviously, the outputs won't be deterministic. It's also very hard to make
sure that it's visually pleasing and that texts & arrows are properly placed.

Let's have a look at the examples provided by the
introduction article by AWS:

Which was (at least shown in the blog), created with the following prompt:

Create a diagram for a three-tier web application with a presentation tier (ALB and CloudFront), application tier (ECS with Fargate), and data tier (Aurora PostgreSQL). Include VPC with public and private subnets across multiple AZs. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

Let's reuse the exact prompt they used and see what we get.

Looks very different; we've lost some details (e.g. the ECS task role is not
there anymore), but got more details regarding the availability zones. Some of
the labels are not perfectly placed, but that's not a big deal.

Let's try it one more time.

Another slightly different result. As you can see, it's hard to get consistently
good results.

Conclusion

Amazon Q with MCP servers for diagram generation is promising, but it's not
ready to replace your existing tools completely.

Here's where it shines: You can create basic architecture diagrams quickly
without hunting for icons or fighting with alignment. But the limitations are
real: Every generation gives you different results, even with identical prompts.
Text placement and visual formatting can be messy. You'll spend time tweaking
prompts to avoid unwanted components. If you need pixel-perfect diagrams for
presentations or client deliverables, stick with your current tools for now.

The future looks interesting though. As the underlying models improve and the
MCP servers (and underlying tools) get more sophisticated, this approach might
actually solve the diagram creation problem we all hate.

For now, consider it a useful addition to your toolkit, not a replacement.