Azure Drawio MCP Diagramming Agent Skill

Draw.io MCP Diagramming Skill

Use this skill to create or update diagrams through the Draw.io MCP tool and to avoid common Azure icon rendering problems.

See references/REFERENCE.md for reference artifacts and refresh commands.

For non-Azure diagrams, you can skip icon discovery/validation scripts and proceed directly to drawio/create_diagram.

When to Use

• The user asks to create or refine architecture diagrams.
• The user wants draw.io/diagrams.net output from an MCP workflow.
• The user needs Azure service icons in diagrams.
• The user reports that Azure icons/shapes are not appearing.

Required Tooling

• MCP tool: drawio/create_diagram
• Workspace MCP config should include a drawio server:

{
  "servers": {
    "drawio": {
      "type": "http",
      "url": "https://mcp.draw.io/mcp"
    }
  }
}

Recommended Workflow

• If diagram uses Azure icons: grep references/azure2-complete-catalog.txt to verify icon paths — no scripts needed at runtime.
• If diagram is not Azure-specific: skip icon lookup and create diagram directly.
• For Azure infrastructure/network diagrams: apply Professional Network Topology Patterns (see section below):
• Use larger canvas (1900x1500)
• VNets with thick borders (strokeWidth=4)
• Subnets with dashed borders (strokeWidth=2, dashPattern=8 8)
• Position resources inside their subnets
• Label all traffic flows with protocols/ports
• Include traffic legend and network isolation explanation boxes
• Build a valid mxGraphModel payload using verified icons when applicable.
• Call drawio/create_diagram with the XML.
• If user wants a file artifact, save as .drawio wrapped in <mxfile><diagram>...</diagram></mxfile>.
• Keep labels concise and explicit (service name + role).
• For Azure diagrams, prefer one icon per major service and use edges for flow semantics (ingress/egress/peering/telemetry).

Visual Quality Guardrails

Apply these defaults unless the user explicitly asks for a dense/technical view:

• Use 3-4 major lanes/zones max (for example Source, Pipeline, Azure target).
• Keep primary flow left-to-right with a single main path.
• Use stage numbering (1, 2, 3, 4) instead of many edge labels.
• Keep one icon per major service; avoid icon-per-step layouts.
• Limit cross-lane dashed lines to one security/auth line and one optional telemetry line.
• Keep text concise (single purpose per box) and avoid multiline overload.
• Prefer a "clean" variant first; add detail only if requested.

For worked examples of common layout problems (stacked edges, repeated labels, observability inside VNet, etc.), see references/layout-antipatterns.md.

Professional Network Topology Patterns (Azure Infrastructure)

When creating Azure infrastructure network diagrams with VNets, subnets, and network isolation:

Canvas Sizing

• Use larger canvas for complex infrastructure: pageWidth="1900" pageHeight="1500"
• Standard canvas may be too small for multi-VNet topologies

VNet and Subnet Visualization

• VNets: Use thick borders (strokeWidth=4) and large containers
• DMZ VNet: Yellow (fillColor=#fff2cc, strokeColor=#d6b656)
• Internal VNet: Green (fillColor=#d5e8d4, strokeColor=#82b366)
• Management Zone: Blue (fillColor=#dae8fc, strokeColor=#6c8ebf)
• Subnets: Use dashed borders (strokeWidth=2, dashed=1, dashPattern=8 8)
• Position subnet containers inside VNet containers
• Use lighter shades of parent VNet color
• Label with subnet name and CIDR (e.g., "Application Subnet - 10.x.2.0/24")
• Delegated Subnets: Add delegation info to label (e.g., "PostgreSQL Subnet - 10.x.4.0/24 (Delegated to Microsoft.DBforPostgreSQL/flexibleServers)")

Resource Positioning

• Position all resources inside their respective subnet containers
• VMs, databases, load balancers must be visually contained within their subnets
• This clearly shows network isolation boundaries

Traffic Flow Visualization

• Label all traffic arrows with protocols and ports:
• HTTPS:443 (red thick arrows for internet ingress)
• HTTP:8080/8090/8095 (gold arrows for backend pools)
• PostgreSQL:5432 (blue dashed arrows for database connections)
• NFS/Gluster (green arrows for shared storage)
• RBAC/Identity/SMTP (orange dashed arrows for management/external)
• Use edgeStyle=orthogonalEdgeStyle for clean routing
• Include <Array> waypoints for complex routing

Essential Components

• Traffic Legend Box (bottom-left)
• Show all 5 traffic types with color-coded arrows
• Include protocol/port information
• Use thick bordered white box (strokeWidth=3)

• Network Isolation Explanation Box (top-left)
• Explain visual conventions:
• "VNets: Thick borders"
• "Subnets: Dashed borders"
• "PostgreSQL subnet delegated"
• "NSGs control traffic"
• "Private DNS for internal resolution"
• Use yellow background (fillColor=#fff9cc)

• Zone Separation
• VNet Peering Zone: Grey box (fillColor=#f5f5f5, strokeColor=#666666)
• External Services Zone: Orange box (fillColor=#ffe6cc, strokeColor=#d79b00)

Complete Example Structure

<mxGraphModel pageWidth="1900" pageHeight="1500">
  <!-- VNet Container with thick border -->
  <mxCell id="vnet" value="Internal VNet - 10.x.0.0/16" 
    style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;
    verticalAlign=top;fontSize=16;fontStyle=1;align=center;strokeWidth=4;">
    <mxGeometry x="220" y="580" width="1340" height="820"/>
  </mxCell>
  
  <!-- Subnet Container with dashed border inside VNet -->
  <mxCell id="subnet-app" value="Application Subnet - 10.x.2.0/24"
    style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e6f4ea;strokeColor=#82b366;
    verticalAlign=top;fontSize=13;fontStyle=1;align=center;strokeWidth=2;dashed=1;dashPattern=8 8;">
    <mxGeometry x="260" y="650" width="480" height="340"/>
  </mxCell>
  
  <!-- Resources inside subnet -->
  <mxCell id="vm" style="image;aspect=fixed;html=1;points=[];align=center;
    image=img/lib/azure2/compute/Virtual_Machine.svg;">
    <mxGeometry x="300" y="720" width="64" height="59"/>
  </mxCell>
  
  <!-- Labeled traffic edge -->
  <mxCell id="edge" value="PostgreSQL:5432" 
    style="edgeStyle=orthogonalEdgeStyle;strokeWidth=2;strokeColor=#6c8ebf;dashed=1;"
    edge="1" source="vm" target="postgres">
    <mxGeometry relative="1"/>
  </mxCell>
</mxGraphModel>

Professional Topology Checklist

• [ ] VNets have thick borders (strokeWidth=4)
• [ ] Subnets have dashed borders (strokeWidth=2, dashPattern=8 8)
• [ ] All resources positioned inside their subnets
• [ ] Traffic arrows labeled with protocols and ports
• [ ] Traffic legend box included
• [ ] Network isolation explanation box included
• [ ] Color-coded zones for different purposes
• [ ] Canvas sized appropriately (1900x1500 for complex infra)
• [ ] VNet peering connections shown in separate zone
• [ ] External services grouped in separate zone

Icon Reference Assets (Azure Diagrams)

This section applies only when the diagram includes Azure services/icons.

• Use the static catalog — references/azure2-complete-catalog.txt contains all 648 Azure2 icons.
• Grep it to find icon paths: grep -i "gateway" references/azure2-complete-catalog.txt
• No HTTP requests or script execution needed at runtime.
• Hard gate
• If an icon path cannot be confirmed in the catalog, do not use it in drawio/create_diagram.
• Find an alternative via grep first.
• Render review fallback
• If diagram review shows wrong/missing icon rendering, grep the catalog for alternative paths.
• Substitute and regenerate the diagram.
• Refresh catalog (periodic, human-run — not per diagram):

cd .github/skills/drawio-mcp-diagramming/scripts
python3 search_azure2_icons_github.py --max-results 9999 > ../references/azure2-complete-catalog.txt

Azure Icon Caveats (Important)

Azure icon rendering in draw.io can fail for two common reasons:

• Wrong style type
• shape=mxgraph.azure2.* may not render in some hosts.
• Prefer Azure2 image style entries:
• image;aspect=fixed;html=1;...;image=img/lib/azure2/<category>/<Icon_Name>.svg;

• Library/environment mismatch
• Some embedded viewers/extensions do not resolve img/lib/azure2/... consistently.
• If icons do not render in one host, test in app.diagrams.net.

How to Discover Icons

Grep the static catalog — no scripts needed at agent runtime:

grep -i "gateway" references/azure2-complete-catalog.txt
grep -i "virtual_machine\|load_balancer\|key_vault" references/azure2-complete-catalog.txt

Use verified paths in diagram cell styles:

image;aspect=fixed;html=1;...;image=img/lib/azure2/<category>/<Icon_Name>.svg;

For renderer resilience, absolute URLs also work:

image;aspect=fixed;html=1;...;image=https://raw.githubusercontent.com/jgraph/drawio/dev/src/main/webapp/img/lib/azure2/networking/Application_Gateways.svg;

If local rendering still fails, open in app.diagrams.net.

Known-Good Azure2 Icon Examples

image=img/lib/azure2/networking/Front_Doors.svg
image=img/lib/azure2/networking/Private_Link_Hub.svg
image=img/lib/azure2/networking/Network_Watcher.svg
image=img/lib/azure2/app_services/API_Management_Services.svg
image=img/lib/azure2/app_services/App_Services.svg
image=img/lib/azure2/databases/Azure_Cosmos_DB.svg
image=img/lib/azure2/identity/Managed_Identities.svg
image=img/lib/azure2/management_governance/Policy.svg
image=img/lib/azure2/analytics/Log_Analytics_Workspaces.svg
image=img/lib/azure2/management_governance/Monitor.svg
image=img/lib/azure2/devops/Application_Insights.svg
image=img/lib/azure2/devops/API_Connections.svg

Fallback Strategy if Icons Still Fail

If Azure icons still do not render:

• Do not generate the Azure diagram with unresolved icon set.
• Return the missing icon list and propose verified replacements.
• After replacements validate to OK, then generate the diagram.

Troubleshooting Checklist

• Confirm MCP server appears in MCP: List Servers.
• Run MCP: Reset Cached Tools if tool list is stale.
• Ensure XML is well-formed (no malformed tags or invalid comments).
• Verify style uses image=img/lib/azure2/... for Azure2 icon mode.
• Reopen diagram in web draw.io if VS Code extension rendering differs.
• If an icon path looks wrong, grep references/azure2-complete-catalog.txt for alternatives.
• If the catalog itself appears stale, re-run the refresh workflow in REFERENCE.md.

Prompt Template for Agents

See references/REFERENCE.md for full example prompt templates.

Definition of Done

• For non-Azure diagrams: diagram is generated and renders correctly.
• For Azure diagrams: all icon paths confirmed against references/azure2-complete-catalog.txt before calling drawio/create_diagram.
• If render issues found, alternative icon paths sourced from catalog and substituted.
• Diagram generated via drawio/create_diagram only with confirmed icon paths.
• XML is valid and opens in draw.io.
• Azure resources are identifiable (icons and clear service labels).
• For Azure infrastructure/network diagrams:
• VNets use thick borders (strokeWidth=4) and are color-coded
• Subnets use dashed borders (strokeWidth=2, dashPattern=8 8)
• All resources positioned inside their respective subnets
• All traffic flows labeled with protocols and ports
• Traffic legend box included (bottom-left)
• Network isolation explanation box included (top-left)
• Canvas appropriately sized (1900x1500 for complex topologies)
• VNet peering and external services in separate zones
• Layout anti-patterns checked against references/layout-antipatterns.md before finalising