An MCP server for architecture diagrams

Ask any model for an architecture diagram and it will hand back Mermaid. That works right up to the point where the diagram has more than a dozen boxes, because the model is writing text it never sees rendered. It cannot tell that two nodes overlap, that a zone swallowed a label, or that the layout reads as a hairball. It is drawing blindfolded.

MCP changes the shape of the problem. The agent is not producing a picture in one shot; it is operating a canvas — adding nodes, connecting them, laying them out, then measuring the result and fixing what is wrong. That loop is what separates a diagram somebody can present from a diagram somebody has to redraw.

Create an API key, then point your client at the server. Every MCP client uses the same endpoint; only the registration syntax differs.

Claude Code

claude mcp add datadef https://datadef.io/mcp \
  --header "Authorization: Bearer dd_live_YOUR_KEY"

Cursor and Claude Desktop

{
  "mcpServers": {
    "datadef": {
      "url": "https://datadef.io/mcp",
      "headers": { "Authorization": "Bearer dd_live_YOUR_KEY" }
    }
  }
}

VS Code

code --add-mcp '{"name":"datadef","url":"https://datadef.io/mcp","headers":{"Authorization":"Bearer dd_live_YOUR_KEY"}}'

Keys are created from MCP & integrations and are shown once. Access is part of a paid plan.

Two layers. Seven top-level tools cover the whole-diagram operations — create, list, fetch, edit, export — and seventeen atomic canvas tools cover the fine work: adding nodes, connecting them, grouping into zones, adding column-level lineage, running an ELK layout, and validating that the result has no orphans or overlaps.

The one that matters most is not a drawing tool at all. get_design_guide returns the same standard Datadef’s own generator follows — size budgets, edge discipline, when a zone is justified, how annotations should read. An agent that reads it first produces a diagram indistinguishable from a generated one; an agent that skips it produces exactly the diagram the standard exists to prevent.

› Read this repo and diagram how our data flows. Put it in the README.

  I'll look at what's here first.
⏺ Read — dbt_project.yml, models/staging/*.sql (14 files)
⏺ Read — terraform/kinesis.tf, terraform/redshift.tf

  Kinesis → S3 → Redshift, with dbt building staging and marts. Drawing it.
⏺ get_design_guide — zone and edge rules
⏺ create_diagram — "Order Analytics Platform"
⏺ canvas_add_nodes — 4 zones · 16 nodes
⏺ canvas_connect_nodes — 11 labelled edges
⏺ canvas_add_lineage — order_id, customer_id across 3 tables
⏺ canvas_layout_canvas — ELK layered
⏺ canvas_validate_canvas — no orphans, no overlaps
⏺ export_diagram — png · 2400×980
✎ README.md  +3 −0
✓ https://datadef.io/preview/order-analytics-platform

Note the validate step. That is the part a text-only model cannot do, and the reason the output is worth putting in front of a stakeholder.

The agent reads your repository locally. What reaches the server is the structure it decided to draw — node names, zones, edges, column names where you asked for lineage. The source itself is never requested and never sent, because there is no tool that accepts it.

The natural pairing is documentation: once an agent can draw the architecture, the useful next move is having it write the page around the diagram and embed it rather than paste it, so the picture keeps matching after the agent has gone.

If you would rather not wire up a client yet, the scratch canvas runs the same generator from a prompt, with no account.