AI Agents Guide

Draw architecture diagrams in Cursor: setup and the workflow that holds up

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Cursor is a strong client for this because the repository is already open and indexed. The agent does not have to hunt for the service names, the migrations, or the terraform directory. What it needs is somewhere to put the answer that is not a code block, which is what an MCP diagram server gives it.

Try it free
6 min readFor Cursor users who want the architecture on a canvas, in the same session as the change

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

150/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Adding the server

Cursor reads MCP servers from ~/.cursor/mcp.json for your account, or from .cursor/mcp.json inside a project. Datadef is a remote Streamable HTTP server, so the entry bridges through mcp-remote, which forwards the Authorization header to it. The settings page also offers a one-click deep link that writes the same entry for you.

Create the key first from the MCP and integrations page. It is shown once. After saving the file, reload Cursor and check the MCP section of settings: a connected server lists its tools, and the count for Datadef is 36.

{
  "mcpServers": {
    "datadef": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://datadef.io/mcp",
        "--header", "Authorization: Bearer dd_live_YOUR_KEY"
      ]
    }
  }
}

Why the editor is the right place to ask

A diagram drawn in a chat window with no repository is a diagram of a generic system. A diagram drawn from the editor names the real services, uses the real queue names, and gets the direction of the calls right, because the agent can open the files that answer each question instead of inferring from a description you typed.

The practical consequence is when you ask. The best moment is the session where the structure changed: the agent that just added the service is the one that knows which zone it belongs in and what it calls. Asking a week later means paying for the reading twice.

What leaves the machine is narrower than people expect, and you can check rather than trust. No tool on the server accepts source files, so the agent sends the structure it decided to draw and nothing else: node labels, zone names, edges and their labels, column names where lineage was asked for. tools/list answers without a key, so the input schema of every tool is readable before you connect anything, and what a server can receive is exactly what its schemas accept.

Ask for this shape, not "draw my architecture":

  Call get_design_guide first. Read terraform/ and services/ in
  this workspace. Draw a Datadef diagram: one zone per domain,
  real service names from the code, edges only for calls that
  exist, labelled with the protocol. Validate the canvas, then
  give me the link and the list of things you could not confirm
  from the repository.

The tools the agent drives

Whole-diagram tools handle the coarse moves: create_diagram from a description, get_diagram to read one back, edit_diagram to apply a plain-language change, export_diagram for a PNG or JPEG and a permanent embed URL.

The 27 canvas tools are the ones that separate this from generated Mermaid. canvas_add_nodes and canvas_connect_nodes build, canvas_group_nodes creates zones, canvas_add_lineage draws column-level relationships, canvas_layout_canvas arranges, canvas_search_icons searches 2,095 indexed provider marks, 438 AWS and 624 Azure and 226 GCP among them, so a node gets the vendor logo rather than a generic box, and canvas_validate_canvas reports orphans and overlaps so the agent can fix its own output before handing it over.

Ask for get_design_guide at the start. It returns the same standard the Datadef generator follows, and it is the difference between a canvas that reads like a product diagram and one that reads like a graph dump.

Where the diagram lives afterwards

Not in the chat. Every diagram the agent creates is a project in your Datadef workspace: open it on the canvas, move things, add the note only a human knows, then share it. Export gives PNG or JPEG, and a live embed puts the current version in a README or a Confluence page with one markdown line.

Cursor also cannot keep it current between sessions, and neither can any MCP client, because tools only run when a model calls them. For a diagram that updates without anyone asking, connect the repository so it regenerates daily, then let the agent check freshness with repo_status when it matters.

FAQ

How do I add an MCP server to Cursor?

Add an entry under mcpServers in ~/.cursor/mcp.json for all projects, or in .cursor/mcp.json inside one project, then reload Cursor. For a remote server, the entry runs npx -y mcp-remote against the server URL with an Authorization header. Cursor also accepts a one-click install deep link that writes the entry for you.

Why does Cursor need mcp-remote for a remote server?

Many desktop clients speak the stdio transport rather than HTTP directly. mcp-remote runs locally as a stdio server and forwards everything to the remote HTTP endpoint, including the Authorization header, so a remote server behaves like a local one from the client point of view.

Can the Cursor agent edit a diagram I already have?

Yes. It can list what is in your workspace, read a specific diagram back, and apply changes either as a plain-language instruction or through individual canvas operations such as adding a node, connecting two nodes, or moving one into a zone.

Is the result a picture or an editable document?

An editable document. The diagram is a project on a canvas that a human can open, rearrange, annotate, and share. Image export exists for slides, and a live embed URL exists for docs that should keep showing the current version.

Does this work in VS Code too?

Yes, and in Claude Desktop, Codex, Gemini CLI, and ChatGPT. Any client that speaks MCP connects to the same server; only the registration syntax differs, and each client has its own prefilled snippet in the settings page.