AI assistants
Last updated: 9 October 2026
Diagon has no AI of its own. If you already use an AI assistant — Claude, Cursor, Copilot in VS Code, Codex — you can connect it to Diagon, and it will read the diagram you have open and draw or change it for you, in your Diagon window.
The connection uses the Model Context Protocol (MCP), which those assistants already speak. It's included in Diagon from version 1.3.0, during the trial and with a subscription alike. Until 1.2.1 Diagon shipped a small built-in model instead; Release notes says what changed and why.
This page covers setting it up, what the assistant can and can't do, and exactly what goes where.
Set it up once
- In Diagon, open Help → Connect an AI assistant… — or click Connect AI… in the toolbar.
- Switch on Let AI assistants on this computer work in Diagon. It's off until you do.
- Pick your assistant from the list. Diagon shows a short piece of configuration with the paths for your installation already filled in, and says where it goes. Click Copy and put it there.
| Assistant | Where the configuration goes |
|---|---|
| Claude Code | Run the one-line command in a terminal, then start a new session. |
| Claude Desktop | Settings → Developer → Edit Config. Add the diagon entry to mcpServers, save, then quit Claude completely and reopen it. |
| Cursor | Add the diagon entry to mcpServers in .cursor/mcp.json in your home folder, then restart Cursor. |
| VS Code (Copilot) | Run MCP: Open User Configuration from the Command Palette and add the diagon entry under servers. |
| Codex, ChatGPT desktop | Add the block to .codex/config.toml in your home folder. |
| Anything else that speaks MCP | Windsurf, Cline, Gemini CLI, Zed, JetBrains and others ask for the same few values: a command, an argument and, on most installs, one environment variable. Diagon shows them. |
Copy the configuration from the dialog rather than from a web page: it contains the path to Diagon on your machine, which a web page can't know.
Two limits: the assistant has to run on the same computer as Diagon, and it can't be a chat in a web browser (claude.ai, chatgpt.com), which can't reach a program on your desktop — use the desktop app or a coding tool.
Then just ask
In your assistant, say what you want in plain words:
Draw our checkout flow in Diagon: cart, payment, fraud check, confirmation. Declined payments go back to the cart.
In my Diagon diagram, put the three databases in one box called Storage.
Look at the diagram I have open in Diagon and tell me what's missing.
If Diagon isn't running, it opens. The diagram appears in the window, as ordinary text in the Diagon language on the left and the picture on the right — rename things, restyle them, drag nodes around. It's yours from there.
What the assistant can do
Diagon gives a connected assistant five tools, and nothing else.
| Tool | What it does |
|---|---|
| Read the language guide | Diagon's whole syntax, with examples and the mistakes to avoid. This is how the assistant learns the language instead of guessing at it. |
| Read the open diagram | The text of the diagram in the window you used last, its file name, whether it has unsaved changes, and any problems Diagon sees in it. |
| Check a draft | Runs text through Diagon's real parser and reports errors and likely mistakes — without touching your window. |
| Replace the open diagram | Swaps the text in your editor for a new version and redraws. It checks the text first; if it has errors, nothing changes. |
| Look at a diagram | Returns the picture as Diagon draws it, so the assistant can see a tangle and fix it. It can also draw a draft this way without changing what's in your window. |
That list is the boundary of the link. Through Diagon, an assistant cannot open, save or delete files, read other diagrams on your disk, write an export file, change settings, or read your licence key; if Diagon is locked, it is told only that the trial or subscription has ended. It works on the one diagram that's open. (What an assistant can reach on your computer by its own means — a coding assistant can usually read your files — is up to the assistant, not Diagon.)
When it changes your diagram
- A note appears at the bottom left of the window: Your AI assistant updated this diagram — Ctrl+Z to undo.
- Ctrl+Z undoes the whole change in one step, exactly as if you had pasted over your text. Do it before you drag a node or press Auto-arrange: those rewrite the code themselves and clear the undo history (see The editor).
- Nothing is saved. The change is in the editor; the file on disk is untouched until you press Ctrl+S.
- Positions you dragged are part of the text in a flat diagram, and the assistant is told to keep them. In a diagram with containers, in-memory positions are kept for every node that still exists.
One caution, because an assistant can also be asked for something entirely new: if you have a diagram open and ask for a different one, the assistant replaces what's there. Ctrl+Z brings it back — but if you press Ctrl+S instead, you save the new diagram under the old file's name. When you want a fresh diagram and want to keep the one you have, save it first (Ctrl+S), then press New (Ctrl+N) before you ask. New doesn't ask about unsaved changes, and Ctrl+Z doesn't bring back what it replaced.
Privacy: what goes where
Diagon sends no diagram anywhere for this. It doesn't talk to an AI provider, has no account with one, and there's no Soverain server in the path. The one request Diagon may make because of an assistant is for an icon: if the assistant's diagram or draft names one by URL, Diagon fetches it from that address, as it does for an icon you type. An assistant can add icons from one place only: the Simple Icons service (https://cdn.simpleicons.org/…), the same one the examples in these docs use. An icon from any other address is refused and the diagram is not changed. Icons you put in yourself stay, wherever they come from.
What does happen: your assistant asks Diagon for the diagram text, Diagon hands it over on your own machine, and the assistant sends it to its provider — Anthropic, OpenAI, Microsoft or whoever runs it — the same way it sends anything else you show it. That's between you and that provider, under your agreement with them. If your diagrams mustn't go to an AI provider, leave the switch off.
The link itself:
- Off by default. Until you switch it on there is nothing listening and nothing to connect to. Once on, it stays on each time Diagon starts until you switch it off in the same dialog; then it's gone. The switch covers every Diagon window on the computer.
- Local only. Diagon opens no network port. The assistant's side talks to the app over a private channel inside your computer — a named pipe on Windows, a socket file on Linux — that only programs running as you can use.
- Proven, not assumed. Each time the link opens, Diagon makes a new secret and keeps it in your home folder. Both ends must prove they hold it before anything is exchanged, so a program that can't read your home folder can't pose as either side.
- Behind the licence. When the trial is over and there's no subscription, the link refuses everything, like the rest of the app.
A diagram someone else gave you is text your assistant will read. Treat it like any other document you show an assistant: a label can contain instructions meant for it.
Whether your assistant asks before it reads or changes a diagram is its own setting, not Diagon's. Check how yours is set.
For the rest of what Diagon does and doesn't send — licence renewal, update checks, icons — see Licensing & updates.
Limits
- One diagram: the open one. With several Diagon windows, it's the one you used most recently.
- It replaces, it doesn't patch. The assistant sends the whole new text each time. For a large diagram, expect it to take a moment and check that nothing you cared about was dropped.
- It's only as good as your assistant. Diagon checks that the text is valid and warns about common slips — an arrow pointing at a node that doesn't exist, boxes on top of each other, an icon that didn't load — but whether the diagram says the right thing is between you and the model.
- Diagon's language is small. There are no sequence diagrams, class notation or per-edge line styles, and an assistant can't add them. Diagon's language guide tells the assistant to say so and offer the nearest thing.
- Size. Up to 400,000 characters of text. Pictures are sent at up to 1,600 pixels on the longer side, so on a very large diagram the assistant sees small print.
If it doesn't work
The assistant says the connection is switched off. Open Help → Connect an AI assistant… in Diagon and switch it on.
The assistant doesn't list Diagon at all. It reads its configuration when it starts. Restart it — for Claude Desktop that means Quit from the tray icon, not just closing the window — and check the entry is where the table above says.
It worked yesterday and not today. Diagon probably updated itself while the assistant was running. Restart the assistant, or reconnect the server in it (/mcp in Claude Code).
You moved or reinstalled Diagon. The configuration contains the old path. Open the dialog and copy it again. In Claude Code, remove the old entry first: claude mcp remove diagon --scope user.
Linux AppImage. The assistant is pointed at a small launcher in .diagon/mcp in your home folder, which Diagon refreshes every time it starts. After moving the AppImage file or updating it, open Diagon once so the launcher catches up.
A company-managed Cursor or Copilot. Your organisation may have to allow local MCP servers before any will start. That's a setting on their side.
Anything else: support@soverain.cz. We can help with Diagon's side of the link; what the assistant itself does belongs to whoever makes it.