Claude Desktop MCP server for diagrams: config file, restart, and what chat can draw

Open Settings, then Developer, then Edit Config. That opens claude_desktop_config.json, the file the app reads at launch. Paste the Datadef entry under mcpServers and save. Because Claude Desktop speaks stdio rather than remote HTTP, the entry runs mcp-remote as a local bridge that forwards to the remote endpoint with the Authorization header attached.

Then quit the application properly. Closing the window leaves the process running on both macOS and Windows, and a relaunch that reuses the running process reads no config, which produces the classic report of a server that was added and never appeared. Quit from the menu or the tray, then start it again.

Once it is up, the server shows in the tools list of the conversation. Datadef exposes 36 tools there: nine that act on whole diagrams and 27 canvas tools for individual elements.

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

In an editor client the agent can open files to answer its own questions. In Claude Desktop it cannot, so the diagram is only as specific as your description. Name the actual technologies, the layers you want as zones, and the tables that matter. Zone names you give are treated as a specification rather than a suggestion, so listing them is the fastest way to control the shape of the result.

Scope is the other lever. create_diagram takes an overview scope, around 12 to 20 nodes and the default, or a detailed scope that itemises everything and reads considerably denser. A one-line request almost always wants overview, and expanding afterwards costs one instruction.

Generation that finishes inside about 35 seconds comes back complete in the same reply. Slower ones return a diagram_id immediately, and the assistant is told to check back with get_diagram after roughly a minute rather than starting a second generation, which would create a duplicate.

Image content returned by an MCP tool renders inside the collapsed tool call rather than in the assistant's visible answer. That is a protocol behaviour, not a Datadef one, and it is why a diagram can feel invisible even when the call succeeded. The server works around it by returning a ready-made markdown image line with a short-lived preview link and an instruction to paste it verbatim, so the picture lands in the reply itself.

For anything you want to keep, export_diagram renders PNG or JPEG at a viewport you choose, from 600 to 4000 pixels wide, and returns a signed download link that stays valid for 15 minutes and needs no key. When the project has been shared publicly, the same call also returns a permanent image URL you can paste into a document that should keep showing the current version.

Nothing is trapped in the conversation. Every diagram the assistant creates is a project in your workspace: open it on the canvas, move things, add the note only a human knows, then share it or embed it as a live image.

get_design_guide returns the standard Datadef's own generator follows, the same text rather than a summary of it, which is the point: a client model driving the canvas tools never sees the generator system prompt, so without the guide it produces exactly the diagrams the standard exists to prevent.

The parts that change a chat-built diagram most are the budgets and the restraint rules. Aim for 12 to 20 nodes, 25 to 40 only when someone asked for depth, and no more connections than nodes: 18 nodes with 12 edges reads better than 18 nodes with 30. Things that belong together become a zone rather than a bundle of edges. Components that relate to everything, governance, observability, a secrets manager, are drawn as standalone nodes in their own zone with no edges at all, because wiring them to every box turns a diagram into a hairball for no information gained.

Two prohibitions are worth quoting to the assistant directly. No mechanism nodes: a consumer group, a connector task or a sidecar is implementation, not architecture. And nothing invented: a monitoring stack you never mentioned is a guess presented as fact, so the guide tells the model to add a note saying it suspects one rather than a zone full of nodes. Asking for the guide at the start of a conversation costs one tool call and removes most of the review you would otherwise do by hand.

• ChatGPT MCP connector for diagrams
• MCP server documentation and client setup
• The MCP diagram server, in depth
• Live embeds: one line, always current