DEV Community

Cover image for Build AWS Architecture Diagrams Using Amazon Q CLI and MCP: A Comprehensive Guide
Manish Kumar
Manish Kumar

Posted on

Build AWS Architecture Diagrams Using Amazon Q CLI and MCP: A Comprehensive Guide

#webdev #mcp #aws #architecture

Amazon Q CLI with Model Context Protocol (MCP) revolutionizes AWS architecture diagramming by enabling architects to generate professional diagrams through natural language prompts in minutes rather than hours. This innovative approach combines the power of generative AI with AWS best practices documentation, allowing technical teams to create consistent, accurate architectural diagrams that automatically incorporate official AWS guidelines. The integration of AWS Diagram MCP and AWS Documentation MCP servers enables seamless validation against AWS Well-Architected Framework principles while maintaining visual consistency across enterprise documentation. Organizations implementing this solution can expect significant time savings, improved diagram quality, and enhanced collaboration between technical teams and stakeholders.

Learning Objectives

  • Master Amazon Q CLI Setup: Configure Amazon Q Developer CLI with AWS Diagram MCP and AWS Documentation MCP servers for automated architecture diagramming
  • Generate Professional Diagrams: Create enterprise-grade AWS architecture diagrams using natural language prompts that automatically validate against AWS best practices
  • Implement Real-World Patterns: Design complex architectures including microservices, serverless, data processing pipelines, and intelligent document processing solutions
  • Optimize Diagram Workflows: Establish efficient processes for iterative diagram refinement, version control, and team collaboration using AI-assisted diagramming
  • Apply Enterprise Standards: Ensure diagrams meet organizational compliance requirements while following AWS Well-Architected Framework principles

Understanding Model Context Protocol (MCP)

The Model Context Protocol represents a paradigm shift in how AI applications access external data sources and tools. MCP uses a client-server architecture where AI applications act as clients connecting to lightweight MCP servers that expose specific capabilities through standardized protocols. This architecture enables Amazon Q Developer to extend beyond its base model capabilities by connecting to specialized servers that provide domain-specific knowledge and functionality.

The AWS implementation includes several key MCP servers that enhance diagramming capabilities :

  • AWS Diagram MCP Server: Generates architecture diagrams using Python diagrams package with complete AWS icon sets
  • AWS Documentation MCP Server: Provides real-time access to official AWS documentation for best practices validation
  • MCP Client Integration: Amazon Q CLI acts as the MCP client, maintaining connections with multiple servers simultaneously

Amazon Q CLI Architecture

Amazon Q Developer CLI brings generative AI capabilities directly to terminal environments, enabling developers to interact with AWS services through natural language interfaces. The CLI integrates with MCP servers through a standardized JSON configuration file that defines server connections, authentication parameters, and execution environments.

Key architectural components include :

  • Host Application: Amazon Q CLI serves as the primary interface for user interactions
  • MCP Client: Maintains persistent connections with configured MCP servers
  • Transport Layer: Handles communication protocols between client and servers
  • Data Layer: Manages JSON-RPC based message exchange and lifecycle management

AWS Diagram Generation Workflow

The diagram generation process follows a sophisticated multi-step workflow that ensures accuracy and best practice compliance :

Step 1: Requirements Interpretation
Amazon Q CLI analyzes natural language prompts to identify architectural components, relationships, and constraints. The system parses technical requirements while maintaining context about AWS service integrations and deployment patterns.

Step 2: Best Practices Validation
The AWS Documentation MCP server searches official AWS documentation using the search_documentation tool to identify relevant architectural guidelines. This validation step ensures generated diagrams align with AWS Well-Architected Framework principles.

Step 3: Code Generation and Execution
The AWS Diagram MCP server generates Python code using the diagrams package, incorporating appropriate AWS service icons and architectural patterns. The system automatically handles icon selection, layout optimization, and styling consistency.

Step 4: Output Processing
Generated diagrams are saved in specified formats (PNG, SVG) with comprehensive metadata including creation timestamps, architectural components, and validation results.

Setting Up Your Environment

Prerequisites and Installation

Before implementing Amazon Q CLI with MCP servers, establish the foundational environment with proper dependencies and configurations :

# Install Amazon Q Developer CLI
curl -sSL https://d2us906f96lpxg.cloudfront.net/q/install.sh | sh

# Verify installation
q --version

# Configure AWS credentials
q login
Enter fullscreen mode Exit fullscreen mode

MCP Server Configuration

Create the MCP server configuration file to enable Amazon Q CLI integration with AWS diagram and documentation servers :

{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-diagram-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_DEFAULT_REGION": "us-east-1"
      },
      "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
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Dependency Installation

Install required system dependencies for diagram generation and rendering :

# Install Python package manager
pip install uv

# Install Python 3.10 or newer
uv python install 3.10

# Install GraphViz for diagram rendering
# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

# CentOS/RHEL
sudo yum install graphviz
Enter fullscreen mode Exit fullscreen mode

Basic Diagram Generation

Simple Architecture Creation

Generate your first AWS architecture diagram using natural language prompts :

# Start Amazon Q CLI chat interface
q chat

# Generate basic EC2-S3 architecture
Create a diagram showing an EC2 instance in a VPC connecting to an external S3 bucket. Include essential networking components (VPC, subnets, Internet Gateway, Route Table), security elements (Security Groups, NACLs), and clearly mark the connection between EC2 and S3. Label everything appropriately and indicate that all resources are in the us-east-1 region. Check AWS documentation for best practices compliance.
Enter fullscreen mode Exit fullscreen mode

The system will execute the following workflow :

  1. Trust the MCP server tools when prompted (enter 't')
  2. Search AWS documentation for VPC and S3 connectivity best practices
  3. Generate Python code using the diagrams package
  4. Create and save the diagram in PNG format
  5. Display the diagram location and architectural summary

Web Application Architecture

Create a three-tier web application diagram with load balancing and database components :

Create a diagram for a simple web application with an Application Load Balancer, two EC2 instances, and an RDS database. Include VPC configuration with public and private subnets across multiple Availability Zones. Ensure proper security group configurations and follow AWS best practices for high availability. Check AWS documentation for compliance before creating the diagram.
Enter fullscreen mode Exit fullscreen mode

Expected architectural components :

  • Application Load Balancer in public subnets as traffic entry point
  • EC2 instances in private subnets for application tier security
  • RDS database in isolated private subnets with Multi-AZ configuration
  • Internet Gateway and NAT Gateway for proper internet connectivity
  • Security groups with least privilege access principles

Advanced Architecture Patterns

Microservices Architecture

Design enterprise-grade microservices platforms with comprehensive service integration :

Create a diagram for an e-commerce platform with microservices architecture. Include components for product catalog, shopping cart, checkout, payment processing, order management, and user authentication. Ensure the architecture follows AWS best practices for scalability and security, incorporating API Gateway, ECS Fargate, RDS, ElastiCache, Cognito, SQS, SNS, CloudFront, Route 53, WAF, Lambda, Secrets Manager, and CloudWatch. Check AWS documentation for microservices best practices.
Enter fullscreen mode Exit fullscreen mode

Key architectural elements include :

  • API Gateway: Centralized entry point with throttling and authentication
  • ECS with Fargate: Containerized microservices with auto-scaling capabilities
  • RDS Multi-AZ: Distributed databases for different service domains
  • ElastiCache: Redis clusters for session management and caching
  • SQS/SNS: Event-driven communication between services
  • Lambda: Serverless functions for lightweight processing tasks

Serverless Data Processing Pipeline

Implement comprehensive serverless architectures for real-time data processing :

Create a diagram for a data processing pipeline with components organized in clusters for data ingestion, processing, storage, and analytics. Include Kinesis Data Streams, Kinesis Data Firehose, Lambda functions, S3 buckets with lifecycle policies, Glue ETL jobs, DynamoDB tables, Athena, and QuickSight. Ensure proper IAM roles and VPC configurations following AWS best practices. Validate against AWS documentation.
Enter fullscreen mode Exit fullscreen mode

Pipeline architecture components :

  • Ingestion Cluster: Kinesis Data Streams, Data Firehose, SQS for data collection
  • Processing Cluster: Lambda functions, Glue ETL jobs for data transformation
  • Storage Cluster: S3 buckets with intelligent tiering, DynamoDB for operational data
  • Analytics Cluster: Athena for ad-hoc queries, QuickSight for visualization

Intelligent Document Processing Solution

Design AI-powered document processing workflows with human-in-the-loop validation :

Create a diagram for an intelligent document processing (IDP) application on AWS. Include components for document ingestion via S3, OCR and text extraction using Textract, intelligent data extraction using Comprehend and custom SageMaker models, human review validation through A2I, and data output integration via API Gateway and Lambda. Ensure the architecture follows AWS best practices for AI/ML workloads including proper VPC configuration, IAM roles, and monitoring with CloudWatch. Check AWS documentation for IDP best practices.
Enter fullscreen mode Exit fullscreen mode

IDP architecture includes :

  • Document Ingestion: S3 buckets with event notifications triggering processing workflows
  • AI Processing: Textract for OCR, Comprehend for NLP, SageMaker for custom models
  • Human Review: A2I workflows for quality assurance and edge case handling
  • Integration Layer: API Gateway and Lambda for output data distribution
  • Monitoring: CloudWatch dashboards with custom metrics for processing accuracy

Configuration and Customization

Output Configuration Options

Customize diagram generation settings for organizational requirements :

# Specify custom output directory
Create a VPC diagram with EC2 and RDS components. Save the diagram to ./architecture-docs/vpc-design/ directory in SVG format for scalable documentation.

# Configure styling and formatting  
Generate a serverless architecture diagram using consistent blue color scheme with AWS orange accents. Include service names and connection labels for presentation purposes.

# Multi-format output generation
Create the same three-tier architecture in both PNG and SVG formats for different documentation needs - PNG for presentations and SVG for technical specifications.
Enter fullscreen mode Exit fullscreen mode

Organizational Standards Integration

Establish consistent diagramming standards across enterprise teams :

# Define standard architectural components
Create a template diagram showing standard VPC configuration with naming conventions: Production-VPC-${Region}, Private-Subnet-${AZ}, Public-Subnet-${AZ}. Include standard security groups and NACL configurations following organizational policies.

# Compliance validation integration
Generate a healthcare application architecture ensuring HIPAA compliance. Include encryption at rest and in transit, VPC Flow Logs, CloudTrail, and proper data classification. Validate against AWS HIPAA guidance documentation.
Enter fullscreen mode Exit fullscreen mode

Team Collaboration Workflows

Version Control Integration

Integrate diagram generation with existing development workflows :

# Generate diagrams for CI/CD pipeline documentation
Create architecture diagrams for each environment (dev, staging, production) showing differences in scaling configurations, security settings, and monitoring implementations.

# Documentation automation
Generate updated architecture diagrams automatically when CloudFormation templates change, ensuring documentation remains synchronized with actual infrastructure.
Enter fullscreen mode Exit fullscreen mode

Review and Approval Processes

Establish architectural review workflows using generated diagrams :

# Create review-ready documentation  
Generate comprehensive architecture diagrams with detailed annotations explaining design decisions, security considerations, and cost optimization strategies for architecture review board submission.

# Stakeholder presentation materials
Create simplified architecture overviews for executive presentations while maintaining technical accuracy and highlighting key business value propositions.
Enter fullscreen mode Exit fullscreen mode

Hands-on Labs: Implementing Real-World Architectures

Lab 1: Multi-Tier Web Application

Objective: Create a production-ready three-tier web application architecture with high availability and security best practices.

Step 1: Environment Preparation

# Initialize Amazon Q CLI session
q chat

# Verify MCP server availability  
# The system should show both AWS Diagram and Documentation servers loaded
Enter fullscreen mode Exit fullscreen mode

Step 2: Generate Base Architecture

Create a comprehensive three-tier web application architecture diagram. Include:
- CloudFront distribution with custom domain via Route 53
- Application Load Balancer in public subnets across 3 AZs  
- Auto Scaling Group with EC2 instances in private subnets
- Aurora PostgreSQL cluster with read replicas in separate AZs
- ElastiCache Redis cluster for session management
- WAF for security with rate limiting and geo-blocking
- VPC Flow Logs and CloudTrail for audit compliance
- Proper security groups and NACLs following least privilege
Validate against AWS Well-Architected Framework and save as 'web-app-architecture.png'
Enter fullscreen mode Exit fullscreen mode

Result of above

Step 3: Security Enhancement

Enhance the previous diagram by adding:
- AWS Secrets Manager for database credentials rotation
- Systems Manager Parameter Store for application configuration  
- KMS encryption keys for EBS volumes and database encryption
- IAM roles with minimal required permissions for each component
- GuardDuty integration for threat detection
- Config rules for compliance monitoring
Update the diagram to show security data flows and save as 'web-app-security.png'
Enter fullscreen mode Exit fullscreen mode

Step 4: Monitoring and Observability

Add comprehensive monitoring to the web application architecture:
- CloudWatch dashboards for application and infrastructure metrics
- X-Ray distributed tracing for performance analysis
- SNS notifications for critical alerts to operations team
- CloudWatch Logs aggregation from all application components  
- Application Insights for automatic problem detection
- Custom CloudWatch metrics for business KPIs
Create a monitoring-focused view and save as 'web-app-monitoring.png'
Enter fullscreen mode Exit fullscreen mode

Lab 2: Serverless Event-Driven Architecture

Objective: Design a scalable serverless architecture for processing real-time events with automatic scaling and cost optimization.

Step 1: Core Serverless Components

Create a serverless event-driven architecture diagram including:
- API Gateway with custom authorizers and request validation
- Lambda functions with different runtime environments (Node.js, Python, Java)
- EventBridge custom event bus with multiple rules and targets  
- SQS queues with dead letter queues for error handling
- SNS topics for fan-out messaging patterns
- DynamoDB tables with Global Secondary Indexes
- S3 buckets with event notifications triggering workflows
- Step Functions for orchestrating complex business processes
Ensure proper IAM roles and validate against serverless best practices
Enter fullscreen mode Exit fullscreen mode

Result of above

Step 2: Data Processing Pipeline

Extend the serverless architecture with real-time data processing:
- Kinesis Data Streams for high-throughput event ingestion
- Kinesis Analytics applications for real-time stream processing
- Kinesis Data Firehose for automated data lake delivery to S3
- Lambda functions for data transformation and enrichment
- DynamoDB Streams for change data capture and replication  
- ElastiSearch Service for real-time search and analytics
- Athena for ad-hoc querying of processed data in S3
- QuickSight for business intelligence dashboards
Show data flows and processing stages clearly
Enter fullscreen mode Exit fullscreen mode

Step 3: Global Distribution and Edge Computing

Add global distribution capabilities to the serverless architecture:
- CloudFront distributions with Lambda@Edge functions
- Global DynamoDB tables with cross-region replication
- Route 53 health checks and failover routing policies  
- S3 Cross-Region Replication for disaster recovery
- Regional Lambda functions with shared code deployment via Layers
- EventBridge cross-region event replication for global workflows
- CloudWatch cross-region dashboard aggregation
Create a global architecture view showing regional deployments
Enter fullscreen mode Exit fullscreen mode

Lab 3: Machine Learning Pipeline Architecture

Objective: Implement an end-to-end machine learning pipeline with automated training, deployment, and monitoring capabilities.

Step 1: Data Preparation Infrastructure

Create an ML data preparation pipeline diagram:
- S3 data lakes with partitioned raw and processed data storage
- Glue Data Catalog for metadata management and schema evolution
- Glue ETL jobs for data cleaning and feature engineering  
- Lake Formation for fine-grained access control and governance
- DataBrew for visual data preparation and profiling
- EMR clusters for large-scale data processing with Spark
- Redshift for structured data warehousing and analytics
- QuickSight for data exploration and business intelligence
Include data lineage and governance controls throughout the pipeline
Enter fullscreen mode Exit fullscreen mode

Step 2: Model Training and Experimentation

Add ML training infrastructure to the data pipeline:
- SageMaker Studio for collaborative development environment
- SageMaker Training Jobs with distributed training across multiple instances
- SageMaker Experiments for tracking model performance and parameters  
- SageMaker Model Registry for version control and approval workflows
- ECR for storing custom training container images
- CodeCommit repositories for model code version control
- CodePipeline for automated model training and validation
- Lambda functions for triggering training based on data availability  
- CloudWatch for monitoring training job performance and costs
Show the complete MLOps workflow from data to trained models
Enter fullscreen mode Exit fullscreen mode

Step 3: Model Deployment and Monitoring

Complete the ML architecture with production deployment capabilities:
- SageMaker Endpoints with auto-scaling for real-time inference
- SageMaker Batch Transform for large-scale batch predictions
- Lambda functions for lightweight model inference and preprocessing  
- API Gateway for REST API access to ML models with authentication
- SageMaker Model Monitor for detecting data drift and model degradation
- CloudWatch custom metrics for model performance tracking
- A/B testing infrastructure using SageMaker Multi-Model Endpoints
- SageMaker Clarify for model explainability and bias detection
- EventBridge for triggering model retraining based on performance thresholds
Create deployment architecture showing inference paths and monitoring
Enter fullscreen mode Exit fullscreen mode

Real-World Case Study: AWS Service Updates Analysis (Last 60 Days)

Executive Summary: Recent AWS Innovations and Impact

The last 60 days have witnessed significant AWS service enhancements focused on AI/ML capabilities, container orchestration improvements, and enhanced observability features. Key themes include the introduction of Amazon Bedrock AgentCore for enterprise AI deployment, enhanced ECS Managed Instances for simplified container management, and advanced monitoring capabilities through AWS X-Ray adaptive sampling. These updates collectively represent AWS's strategic focus on reducing operational overhead while enhancing security, scalability, and cost optimization across cloud-native architectures.

Domain-wise Breakdown of Critical Updates

Compute: Revolutionary Container Management

Amazon ECS Managed Instances (September 30, 2025)

  • What changed: Introduction of fully managed compute option combining ECS simplicity with EC2 flexibility
  • Why it matters: Eliminates infrastructure management overhead while maintaining access to reserved capacity and advanced configurations
  • Immediate impact: Reduces operational complexity for containerized applications requiring specific instance types or security configurations
  • Architecture implications: Enables hybrid container strategies combining Fargate simplicity with EC2 control where needed
  • FinOps considerations: Supports reserved instance pricing while reducing management costs through automation

EC2 Compute Optimizer Enhancements

  • What changed: Support for 99 additional instance types including C8, M8, R8, and I8 families
  • Impact today: Improved rightsizing recommendations for latest generation instances
  • FinOps view: Enhanced cost optimization through better instance type matching and performance profiling

AI/ML: Enterprise-Grade Agent Deployment

Claude Sonnet 4.5 in Amazon Bedrock (September 29, 2025)

  • What changed: Integration of Anthropic's most advanced model with enhanced coding and complex agent capabilities
  • Why it matters: Provides superior performance for finance, research, and cybersecurity applications requiring long-horizon reasoning
  • Architecture tomorrow: Enables more sophisticated AI agent implementations with improved memory management and context processing
  • FinOps considerations: Premium pricing model for advanced capabilities requiring careful usage monitoring and optimization

Amazon Bedrock AgentCore Enterprise Integration

  • What changed: Added VPC connectivity, PrivateLink support, CloudFormation integration, and resource tagging
  • Security enhancement: Enables private network access for AI agents with enterprise-grade security controls
  • Migration guidance: Supports gradual adoption through VPC integration and Infrastructure as Code deployment patterns

Storage: Advanced Data Management

Amazon S3 Tables Console Preview

  • What changed: Native console interface for S3 Tables with integrated data structure visualization
  • Immediate benefit: Eliminates need for SQL queries to preview table contents and schema
  • Cost impact: Minimal additional costs limited to S3 request charges for console operations

S3 Batch Operations and Security Enhancements

  • What changed: Bulk target selection, conditional deletes, increased malware scanning limits
  • Operational efficiency: Streamlined large-scale data management operations with enhanced security
  • FinOps impact: Reduced operational costs through bulk processing and automated security scanning

Observability: Intelligent Monitoring

AWS X-Ray Adaptive Sampling (September 29, 2025)

  • What changed: Automatic trace capture rate adjustment with Sampling Boost and Anomaly Span Capture
  • Why it matters: Optimizes observability costs while ensuring critical issues are captured during anomalies
  • Architecture implications: Enables cost-effective distributed tracing at scale with intelligent sampling strategies
  • FinOps benefits: Reduces tracing costs while maintaining comprehensive error detection capabilities

Networking and Security

Amazon VPC Reachability Analyzer Regional Expansion

  • What changed: Network Access Analyzer capabilities expanded to seven new regions
  • Global impact: Improved network troubleshooting coverage for multi-region deployments
  • Migration enablement: Better support for global architecture validation and connectivity analysis

Developer Tools and Integration

Amazon Q Developer Remote MCP Server Support

  • What changed: Integration with remote Model Context Protocol servers for extended AI assistant capabilities
  • Developer productivity: Enhanced development workflows through custom tools and data source integration
  • Architecture patterns: Enables distributed MCP server architectures for team collaboration

Comparison Tables

Before vs After: Container Management Evolution

Capability Before ECS Managed Instances After ECS Managed Instances Impact
Instance Management Manual EC2 provisioning and configuration Fully managed with ECS integration 70% reduction in operational overhead
Reserved Capacity Access Separate EC2 and Fargate planning Unified capacity management Improved cost predictability
Security Configuration Complex multi-service setup Integrated security controls Enhanced security posture
Scaling Flexibility Limited by manual processes Automated with EC2 capabilities Better performance optimization

AI/ML Model Capabilities Comparison

Feature Previous Bedrock Models Claude Sonnet 4.5 Business Value
Coding Capabilities Limited programming support Advanced coding and debugging Accelerated development cycles
Context Processing Standard context windows Enhanced long-horizon tasks Complex workflow automation
Memory Management Basic session handling Improved context retention Better user experience
Industry Applications General-purpose usage Finance, research, cybersecurity specialization Targeted business solutions

Action Checklist (Prioritized)

P0: Security and Breaking Changes (Immediate - This Week)

  • Review ECS workloads for Managed Instances migration opportunities - Owner: Platform Team - ETA: 5 days
  • Audit X-Ray sampling configurations to enable adaptive sampling - Owner: SRE Team - ETA: 3 days
  • Assess Bedrock usage for Claude Sonnet 4.5 integration requirements - Owner: AI/ML Team - ETA: 7 days
  • Success Metrics: 90% of production workloads reviewed, sampling costs reduced by 30%

P1: Performance and Cost Optimizations (This Month)

  • Implement S3 Tables preview for data engineering workflows - Owner: Data Team - ETA: 14 days
  • Deploy VPC Reachability Analyzer in new regions - Owner: Network Team - ETA: 10 days
  • Evaluate Compute Optimizer recommendations for new instance families - Owner: FinOps Team - ETA: 21 days
  • Success Metrics: 20% improvement in compute cost-efficiency, enhanced network visibility

P2: Strategic Adoptions (Next Quarter)

  • Pilot Bedrock AgentCore with VPC integration for enterprise AI - Owner: AI Team - ETA: 60 days
  • Implement Amazon Q MCP integration for development workflows - Owner: DevTools Team - ETA: 45 days
  • Design global architecture leveraging regional VPC analyzer expansion - Owner: Architecture Team - ETA: 90 days
  • Success Metrics: Two production AI agents deployed, 50% faster development cycles

FinOps Deep Dive: Cost Optimization Strategies

ECS Managed Instances Economic Model

  • Unit Economics: Combines Fargate simplicity with EC2 reserved instance pricing (up to 72% savings vs on-demand)
  • Commitment Strategy: Leverage existing Reserved Instance commitments while gaining managed service benefits
  • Break-even Analysis: ROI positive for workloads requiring >50 hours monthly runtime with specific instance requirements

X-Ray Adaptive Sampling Cost Controls

  • Cost Model: Pay-per-trace with intelligent sampling reducing unnecessary captures by 60-80%
  • Optimization Strategy: Configure sampling boost thresholds based on error rate and latency percentiles
  • Monitoring Setup: CloudWatch alarms for sampling rate and associated costs with automatic adjustment triggers

Bedrock Claude Sonnet 4.5 Pricing Strategy

  • Usage Patterns: Premium pricing justified for high-value use cases requiring advanced reasoning capabilities
  • Cost Controls: Implement usage quotas and approval workflows for production deployments
  • ROI Measurement: Track task completion rates and quality metrics vs. cost per inference

Migration and Governance Notes

ECS Managed Instances Adoption Framework

  • Prerequisites: Existing ECS cluster with task definitions compatible with EC2 launch type
  • Rollout Strategy: Gradual migration starting with development environments, then staging, finally production
  • Guardrails: Service Control Policies restricting direct EC2 access while allowing ECS Managed Instance usage
  • Fallback Plan: Maintain existing ECS/EC2 configurations during transition period

Bedrock AgentCore Security Implementation

  • Access Controls: IAM roles with resource-based policies limiting agent deployment to approved VPCs
  • Network Security: PrivateLink endpoints for secure agent communication without internet exposure
  • Compliance Alignment: Resource tagging strategy for audit trails and cost allocation
  • Change Management: Feature flags for gradual agent capability rollout with monitoring checkpoints

Expert Tips & Pitfalls

Pro Recommendations for Amazon Q CLI Implementation

1. MCP Server Configuration Management
Configure MCP servers with appropriate logging levels and timeout settings to prevent performance degradation during complex diagram generation. Set FASTMCP_LOG_LEVEL to "ERROR" in production environments to reduce verbose output while maintaining error visibility.

2. Natural Language Prompt Engineering
Structure prompts with explicit architectural requirements, compliance standards, and output specifications. Include phrases like "Check AWS documentation for best practices" to trigger automatic validation against official guidelines.

3. Diagram Version Control Integration
Implement Git hooks to automatically generate updated architecture diagrams when Infrastructure as Code templates change. Store diagram generation prompts alongside code to ensure reproducible documentation.

4. Enterprise Template Standardization
Create standardized prompt templates for common architectural patterns within organizations. Include mandatory security, compliance, and naming convention requirements in template prompts.

5. Multi-Format Output Strategy
Generate diagrams in both PNG and SVG formats simultaneously for different use cases - PNG for presentations and SVG for scalable technical documentation. SVG formats enable post-processing customization and integration with documentation systems.

6. Iterative Refinement Workflows
Use Amazon Q CLI's conversation context to refine diagrams through iterative prompts rather than starting fresh. Build upon previous diagrams by referencing specific components for modifications.

7. Cost Optimization for Large Teams
Implement shared diagram generation workflows to prevent redundant MCP server usage across team members. Establish central repositories for commonly used architectural patterns.

8. Security Compliance Integration
Always include specific compliance requirements (SOC 2, HIPAA, PCI DSS) in diagram generation prompts to ensure appropriate security controls are represented. Validate generated architectures against organizational security policies.

Common Mistakes and Prevention Strategies

9. Insufficient Architectural Context
Mistake: Providing vague prompts without specifying deployment environment, scale requirements, or compliance needs.
Prevention: Include explicit context about expected traffic patterns, security requirements, and operational constraints in every prompt.

10. Neglecting AWS Best Practices Validation
Mistake: Generating diagrams without leveraging AWS Documentation MCP server for best practices validation.
Prevention: Always include "validate against AWS documentation" or similar phrases to trigger automatic compliance checking.

11. Ignoring Diagram Maintenance Workflows
Mistake: Treating generated diagrams as static artifacts without establishing update processes.
Prevention: Implement automated diagram regeneration in CI/CD pipelines when infrastructure definitions change.

12. Overlooking Team Collaboration Requirements
Mistake: Individual team members generating inconsistent diagram styles and conventions.
Prevention: Establish organization-wide prompt templates and styling guidelines for consistent visual communication.

13. Inadequate Error Handling and Fallbacks
Mistake: Not preparing for MCP server connectivity issues or generation failures.
Prevention: Implement fallback procedures and maintain backup diagramming tools for critical documentation needs.

14. Missing Integration with Documentation Systems
Mistake: Generating isolated diagrams without integrating into broader documentation ecosystems.
Prevention: Configure output directories and naming conventions that align with existing documentation workflows.

15. Underutilizing Advanced MCP Capabilities
Mistake: Using only basic diagram generation without leveraging specialized MCP server tools.
Prevention: Explore list_icons, get_diagram_examples, and search_documentation tools for enhanced diagram quality.

Latest Updates Section: 2024-2025 AWS Service Enhancements

Amazon Q Developer CLI Evolution

Amazon Q Developer CLI has undergone significant enhancements throughout 2024-2025, particularly in MCP integration capabilities and image processing features. The CLI now supports image inputs directly in terminal environments, enabling architects to analyze existing diagrams and generate updated versions based on visual inputs. This capability transforms legacy architecture documentation workflows by allowing natural language interactions with visual architectural assets.

The introduction of tangent mode represents a breakthrough in conversational AI workflow management. This experimental feature creates conversation checkpoints, allowing users to explore architectural alternatives without losing their main design thread. Enable tangent mode with q settings chat.enableTangentMode true to experience non-linear architecture exploration.

MCP Server Ecosystem Expansion

AWS has significantly expanded the MCP server ecosystem with specialized servers for cost analysis, security assessment, and compliance validation. The introduction of remote MCP server support enables distributed teams to share custom architectural knowledge and validation rules across organizations.

The AWS Solutions Library now provides comprehensive guidance for deploying MCP servers on AWS infrastructure using containerized architectures with OAuth 2.0 authentication. This enables organizations to host internal MCP servers that provide proprietary architectural patterns and compliance requirements while maintaining security through standards-compliant authentication flows.

Foundation Model Integrations

Amazon Bedrock's integration with architectural diagramming workflows has advanced significantly with the introduction of Claude Sonnet 4.5 for enhanced coding and complex agent capabilities. This model excels at generating sophisticated Infrastructure as Code templates that correspond directly to architectural diagrams, creating seamless workflows from visual design to implementation.

The Amazon Nova model family customization capabilities through SageMaker AI enable organizations to fine-tune architectural diagram generation for specific industry requirements and compliance standards. These customization options allow enterprises to embed proprietary architectural patterns and security requirements directly into the AI-assisted diagramming process.

Regional Expansion and Global Architecture Support

AWS has expanded MCP server capabilities to support global architecture patterns with enhanced regional service availability. The VPC Reachability Analyzer expansion to seven new regions provides comprehensive network connectivity analysis for multi-region architectures. This enhancement enables architects to validate cross-region connectivity patterns and optimize global application deployment strategies.

New regional capabilities include enhanced support for edge computing architectures through AWS Wavelength and Local Zones integration in diagramming workflows. GameLift's new Local Zone deployment in Dallas exemplifies the growing focus on ultra-low latency architectures that require specialized diagramming considerations.

Integration with AWS Developer Tools

The integration between Amazon Q Developer CLI and AWS developer tools has deepened significantly, particularly in CI/CD pipeline documentation and Infrastructure as Code validation. CodePipeline integrations now support automatic architecture diagram generation during deployment processes, ensuring documentation remains synchronized with actual infrastructure changes.

Enhanced support for AWS CDK and CloudFormation includes automatic diagram generation from existing Infrastructure as Code templates, enabling reverse engineering of deployed architectures into visual documentation. This capability significantly reduces the effort required to document existing systems and maintain architectural accuracy.

Troubleshooting Guide

MCP Server Connection Issues

Problem: Amazon Q CLI fails to load AWS Diagram or Documentation MCP servers
Symptoms: Error messages indicating server unavailability or timeout during q chat initialization
Solution:

# Verify MCP configuration file exists and is properly formatted
cat ~/.aws/amazonq/mcp.json

# Check Python and uv installation
uv --version
python3 --version

# Reinstall MCP servers with latest versions
uvx --force awslabs.aws-diagram-mcp-server
uvx --force awslabs.aws-documentation-mcp-server@latest

# Verify GraphViz installation
dot -V
Enter fullscreen mode Exit fullscreen mode

Prevention: Regularly update MCP servers and maintain proper Python environment isolation.

Diagram Generation Failures

Problem: Prompts result in error messages instead of generated diagrams
Symptoms: "Failed to generate diagram" or Python execution errors
Solution:

# Enable detailed logging for troubleshooting
export FASTMCP_LOG_LEVEL=DEBUG

# Test with minimal architecture first
q chat
Create a simple diagram with one EC2 instance and one S3 bucket

# Verify write permissions in output directory  
ls -la generated-diagrams/
chmod 755 generated-diagrams/
Enter fullscreen mode Exit fullscreen mode

Root Cause Analysis: Most failures stem from insufficient system dependencies or file permission issues.

Authentication and Authorization Problems

Problem: AWS Documentation MCP server fails to access official documentation
Symptoms: "Access denied" errors when validating against AWS best practices
Solution:

# Verify AWS credentials configuration
aws sts get-caller-identity

# Update AWS CLI and verify region configuration
aws configure list
aws configure set region us-east-1

# Test documentation access directly
aws docs search "vpc best practices"
Enter fullscreen mode Exit fullscreen mode

Long-term Fix: Implement IAM roles with appropriate documentation access permissions.

Performance and Timeout Issues

Problem: Diagram generation takes excessive time or times out
Symptoms: Processes hanging for more than 5 minutes or timeout errors
Solution:

# Reduce diagram complexity by breaking into smaller components
Create a diagram showing only the network layer of the architecture

# Optimize MCP server resource allocation
export MCP_SERVER_TIMEOUT=300
export PYTHON_MAX_MEMORY=2G

# Monitor system resources during generation
top -p $(pgrep python)
Enter fullscreen mode Exit fullscreen mode

Optimization Strategy: Generate complex architectures iteratively, building upon smaller components.

Version Compatibility Problems

Problem: Inconsistent behavior across different Amazon Q CLI versions
Symptoms: Features working in documentation but failing in practice
Solution:

# Update to latest Amazon Q CLI version
curl -sSL https://d2us906f96lpxg.cloudfront.net/q/install.sh | sh

# Verify MCP server compatibility
uvx awslabs.aws-diagram-mcp-server --version
uvx awslabs.aws-documentation-mcp-server --version

# Clear configuration cache
rm -rf ~/.aws/amazonq/cache/
Enter fullscreen mode Exit fullscreen mode

Maintenance Practice: Establish regular update schedules for CLI tools and MCP servers.

Output Format and Quality Issues

Problem: Generated diagrams have poor quality, incorrect layouts, or missing components
Symptoms: Blurry images, overlapping elements, or missing AWS service icons
Solution:

# Specify explicit output requirements in prompts
Create a high-resolution diagram in SVG format with clear component spacing and AWS official icons

# Regenerate with different styling parameters
Create the same architecture using a horizontal layout with increased spacing between components

# Verify GraphViz installation and fonts
fc-list | grep -i arial
sudo apt-get install fonts-liberation
Enter fullscreen mode Exit fullscreen mode

Quality Assurance: Always review generated diagrams against AWS Architecture Icons official standards.

Integration and Workflow Disruptions

Problem: Diagram generation interferes with existing development workflows
Symptoms: Conflicts with existing Python environments or tool dependencies
Solution:

# Use isolated Python environments
python -m venv amazonq-env
source amazonq-env/bin/activate
pip install uv

# Configure separate working directory
mkdir ~/architecture-diagrams
cd ~/architecture-diagrams  
q chat

# Implement workflow isolation
alias aq='cd ~/architecture-diagrams && q chat'
Enter fullscreen mode Exit fullscreen mode

Best Practice: Maintain dedicated environments for architecture diagramming to prevent tool conflicts.

Further Reading

Official AWS Documentation

AWS Architecture Center: Comprehensive collection of reference architectures, best practices, and design patterns for cloud-native applications. Essential reading for understanding proper architectural patterns before generating diagrams.

AWS Well-Architected Framework: Foundational document outlining the five pillars of architectural excellence - operational excellence, security, reliability, performance efficiency, and cost optimization. Critical for ensuring generated diagrams reflect architectural best practices.

Model Context Protocol Official Documentation: Technical specification and implementation guidelines for MCP server development and client integration. Required reading for organizations developing custom MCP servers.

AWS Whitepapers and Technical Guides

"Microservices on AWS" Whitepaper: Detailed guidance on designing microservices architectures with proper service boundaries, communication patterns, and deployment strategies. Directly applicable to microservices diagram generation workflows.

"Serverless Application Lens": AWS Well-Architected framework extension specifically focused on serverless architecture patterns and best practices. Essential for generating compliant serverless architecture diagrams.

"Security Pillar - AWS Well-Architected Framework": Comprehensive security guidance including network security, identity management, and data protection patterns. Critical for ensuring security components are properly represented in generated diagrams.

Technical Implementation Resources

AWS Solutions Library - MCP Deployment Guidance: Step-by-step instructions for deploying production MCP servers on AWS infrastructure with enterprise security controls and scalability considerations.

Amazon Q Developer CLI User Guide: Complete reference documentation covering installation, configuration, and advanced usage patterns for command-line AI assistance.

AWS CDK and CloudFormation Integration Patterns: Technical documentation for integrating diagram generation with Infrastructure as Code workflows and automated documentation processes.

Community and Advanced Learning

AWS Community Builders Program: Access to expert practitioners sharing real-world architecture patterns and lessons learned from enterprise implementations. Valuable for understanding practical architecture design challenges.

re:Invent Architecture Sessions: Annual collection of deep-dive technical sessions covering emerging architecture patterns, new service integrations, and industry-specific solutions.

AWS Architecture Blog: Regular publications covering new architectural patterns, service integrations, and best practice updates. Essential for staying current with evolving AWS capabilities and integration opportunities.

Top comments (0)