Creating precise, well-structured diagrams can be a time-consuming task for engineers and architects, especially when juggling multiple cloud providers, deployment workflows, and complex system topologies. Keeping diagrams consistent, legible, and editable across teams often requires hours of manual tweaking—tracking down correct icons, adjusting connector routing, and maintaining proper containment.

The Draw.io MCP Diagramming Agent Skill, developed by Thomas Thornton, offers a reusable, scalable approach to generating clear, editable diagrams across diverse use cases, from cloud architectures to CI/CD pipelines and event-driven systems. By applying a common method that respects real containment, official iconography, and clean edge routing, this skill reduces diagram rework and accelerates understanding.

In this post, we'll explore how the Draw.io MCP Diagramming Agent Skill works under the hood, review sample use cases with different diagram types, and outline practical tips for teams looking to automate and improve their diagramming workflow using Draw.io MCP.

Architecture Overview

Key Technical Observations

• Unified Working Method Across Providers and Use Cases
  The skill abstracts shared diagramming guidance—format choice, clean connector routing, container nesting—applying them regardless of cloud provider or diagram domain. This avoids fragility and duplication seen in separate, provider-specific skills.

• Provider-specific Iconography & Conventions Loaded on Demand
  When necessary, the agent skill fetches Azure or AWS icon libraries, enforces subnet boundaries, and applies network/resource placement conventions. This hybrid approach blends generality with precision.

• Support for Diverse Diagram Inputs and Output Targets
  The skill handles XML, Mermaid, and CSV as inputs, standardizing diverse source formats into Draw.io XML for editing. Note that the hosted MCP App Server currently accepts only native Draw.io XML rather than Mermaid or CSV, while the stdio Tool Server supports these formats.

• Pragmatic Focus on Readability and Editability
  Emphasis on non-overlapping edges, concise labels, and real containment hierarchy ensures output is not only visually clear but also editable, enabling engineers to evolve diagrams collaboratively.

• Integration with Developer Toolchains
  The MCP server integrates with VS Code and GitHub Copilot through stdio Tool Server or hosted MCP App Server, promoting diagram generation as a natural part of a developer’s workflow.

• Use Case Breadth from Infrastructure to Workflow Diagrams
  The skill handles infrastructure topologies, event-driven flows, CI/CD pipelines, API interactions, and more, illustrating flexibility beyond traditional architecture diagramming tools.

How It Works

Diagram Format & Container Selection

The agent skill first interprets the input prompt to select the appropriate diagram format—topology, workflow, sequence, or entity relationship. It identifies suitable container shapes representing real boundary semantics like VPCs, clusters, namespaces, or logical layers, depending on the domain.

This decision governs layout algorithms and routing conventions, ensuring connectors reflect actual data or control flow paths rather than arbitrary graphic placement.

Icon Discovery and Shape Resolution

For cloud providers like Azure or AWS, the skill dynamically searches official Draw.io shape libraries to fetch icons matching requested components. If a provider-specific library isn’t available (e.g., GCP), it falls back to generic shape searches.

The skill also respects network and security boundaries, positioning icons within nested containers (subnets, VNets, clusters), conforming to provider best practices.

Connector Routing and Labeling

A key complexity is routing edges to avoid overlap and tangling—especially critical in flow diagrams like CI/CD pipelines or event-driven architectures. The agent skill applies orthogonal edge routing and keeps labels concise, ensuring all connections remain legible.

Decision nodes (e.g., manual approvals, health checks) introduce branching; the skill manages primary success and failure paths distinctly to clarify workflow outcomes.

Diagram Output and Validation

The skill generates raw Draw.io XML ensuring output remains fully editable. It runs validation steps to check container correctness, edge connectivity, label presence, and icon consistency before handing off to the MCP server.

The MCP server then renders the diagram, either inline inside MCP-enabled clients or opened in the Draw.io editor for further refinement.

{
  "servers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp@latest"]
    }
  }
}

This snippet highlights how the MCP Tool Server can be configured to invoke the diagramming server, integrating it smoothly with developer environments.

Flow diagram demonstrating complex CI/CD stages with approvals and rollback – source: Thomas Thornton Blog

Quick Tips & Tricks

1. Leverage Shared Diagramming Patterns
   Use the skill’s consistent method across different cloud providers to standardize diagrams, speeding onboarding and improving cross-team communication.

2. Use the MCP Server for Interactive Edits
   After generation, open diagrams in the Draw.io editor from the MCP server to tweak layouts or add annotations, preserving editability.

3. Incorporate Official Icon Libraries Dynamically
   Avoid manual icon sourcing by relying on the skill’s on-demand shape lookups for Azure or AWS, ensuring diagrams conform to updated provider visuals.

4. Apply Orthogonal Connector Routing Rules
   Use the skill’s routing conventions, which minimize edge overlaps and crossings, making complex flows like event-driven or CI/CD pipelines easier to interpret.

5. Install via Skills CLI or Agent Package Manager (APM)
   Quickly add the skill to your environment with npx skills add or choose curated APM packages for deterministic dependency management across your team.

6. Plan Diagram Containment Carefully
   Invest time in defining realistic container boundaries (VPC, subnet, cluster, namespace) rather than relying on overlapping rectangles; this pays off with clearer hierarchical visuals.

Conclusion

The Draw.io MCP Diagramming Agent Skill exemplifies how automation coupled with sound diagramming principles can ease the creation of architecture and flow diagrams across multiple domains. By unifying working methods, enabling provider-specific precision, and integrating with developer toolchains, it empowers engineers to produce clearer, repeatable, and editable visuals with less effort.

As cloud architectures and workflows grow increasingly complex, tools like this skill will be indispensable in maintaining shared understanding and accelerating collaboration. With evolving Draw.io MCP capabilities and expanding integrations, automated diagram generation stands to become a staple in platform engineering and design workflows.

References

1. Drawio Agent Skill - Thomas Thornton Blog — Original article providing the skill overview and sample diagrams.
2. Draw.io MCP for Diagram Generation: Why It’s Worth Using — Insights into the MCP server powering diagram rendering.
3. GitHub Copilot Agent Skills Repository — Source repository containing the Draw.io MCP diagramming skill.
4. Azure Diagram Agent Skill with Draw.io MCP — Related work focusing on Azure-specific diagrams.
5. Official Draw.io MCP Servers Documentation — Detailed technical documentation on MCP servers.
6. Skills CLI Installation for Draw.io MCP Diagramming — Quick start for adding the skill using the Skills CLI.