Connect Claude Code to a diagram tool: the command, the flag, the first prompt

Create an API key from the MCP and integrations page in settings, copy it once because it is shown a single time, then register the server. Add --scope user to make it available in every project, or --scope project to write it into a .mcp.json your teammates get with the repository.

The --transport http part is not optional. Without it, claude mcp add treats the URL as a stdio command and tries to execute it as a binary. Nothing errors loudly; the server simply never appears in the session, which is the single most common reason people conclude that an MCP server is broken.

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

# then restart Claude Code, and inside a session:
/mcp

Run /mcp inside a session. A connected Datadef server reports 36 tools: nine that operate on whole diagrams, including create_diagram, edit_diagram, export_diagram, repo_status, and repo_refresh, plus 27 canvas tools prefixed canvas_ for nodes, edges, zones, lineage, layout, and validation.

If the count is zero or the server is missing, work through four things in order. The transport flag, from the previous section. A restart, since the client reads its server list at startup. The key, which is shown once and cannot be recovered, only replaced. And the plan, since tool calls need a paid plan while the signup trial covers the evaluation.

Tell the agent to read the design guide before it draws. get_design_guide returns the design standard byte for byte, because the server imports the text the Datadef generator is prompted with rather than paraphrasing it. A diagram an agent builds by hand therefore comes out in the same idiom as a generated one.

What that text carries is concrete, not advice. Aim for 12 to 20 nodes with no more connections than nodes, and 25 to 40 only when depth was explicitly asked for. Never connect an edge to a zone, because zones have no ports and the edge renders detached; connect the node inside or use a flow arrow. Run canvas_layout_canvas once after a structural change and not at all after deliberate manual placement, which it would discard. The three tools an agent reaches for first, canvas_add_nodes, canvas_group_nodes, and canvas_describe_canvas, carry a pointer to the guide in their descriptions, but saying it in the prompt is more reliable than hoping.

The second thing worth asking for is validation. canvas_validate_canvas checks for orphans and overlaps, and canvas_measure_canvas reports the size, which is the part a text-only model fundamentally cannot do about its own output. A session that ends with a validate call produces a diagram you can put in a review; one that ends at add_nodes usually does not.

The diagram is not stuck in the chat. Everything the agent creates is a project in your workspace, openable on the canvas, editable by hand, and embeddable as a live image that keeps matching the canvas.

Good first prompt:

  Call get_design_guide first. Then read this repo and draw the
  architecture as a Datadef diagram: zones per domain, real service
  names, labelled edges. Validate the canvas before you finish and
  give me the link.

It will not notice tomorrow that the architecture changed. Tools run inside a session, so an agent-drawn diagram is exactly as current as the last time you asked. For a diagram that keeps up without a session, connect the repository itself and let it regenerate daily, then let the agent check on it with repo_status and bring it forward with repo_refresh when it is behind.

• MCP server documentation and client setup
• Draw diagrams with your AI agent over MCP
• Draw architecture diagrams in Cursor
• What is an MCP server, in plain terms
• Reviewing what the agent drew