AI assistants
Last updated: 12 November 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, the pictures it may add, and exactly what goes where.
Set it up once
- In Diagon, open Help → Connect an AI assistant… — or click Connect AI in the toolbar. The dot on that button is grey while the connection is off, amber while Diagon waits for an assistant, and green once one is connected.
- 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. Since 1.5.0 that still works after you have dragged a node, pressed Auto-arrange or chosen a Direction or Routing in the toolbar. In a flat diagram those are undo steps of their own, so Ctrl+Z takes them back first and then the assistant's change. Opening a file ends the undo history (The editor has the whole list).
- 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; since 1.5.0, Ctrl+Z brings back the text it replaced, as an untitled diagram.
Pictures an assistant adds
An icon is a picture that Diagon fetches from the web, from the address written in the diagram. If you never connect an assistant, nothing changes: an icon you type yourself loads from any link, as always. An address that an assistant wrote is held to stricter rules. This is a safety rule, and it has nothing to do with licences: a diagram an assistant wrote must not make your computer call addresses that only your computer can reach, or send things out packed into an address.
Three libraries load straight away. Simple Icons (cdn.simpleicons.org), Iconify (api.iconify.design) and picture files in public GitHub repositories (raw.githubusercontent.com) — the cloud icons for Azure, AWS, Google Cloud and Kubernetes come from there. Up to 1.4.0 an assistant could use Simple Icons only.
For any other public website, Diagon asks you once. A bar at the bottom left names the website — This diagram wants to show pictures from example.com. — with Allow and Not now. Allow is greyed out for a moment, so that you can read the name first. Until you allow it, the icon is a dashed placeholder, and the assistant is told that the picture is waiting for your answer. Not now is remembered until you close Diagon: the assistant's next diagram does not bring the question back for that website, and the assistant is told not to ask again. Click the placeholder to get the question back.
The websites you allowed. Diagon remembers them. While the connection is switched on, Help → Connect an AI assistant… lists them under Pictures. Forget these empties the list, and the switch Don't ask — let assistants load pictures from any public website stops the question for good.
Addresses that are never loaded for an assistant. A picture an assistant adds must be an https:// link to a public website name. The website must be given by name: an address with a port (:8443), with a user name, or with a bare number address is not loaded for an assistant either. Before every request for an assistant's picture, Diagon looks up where that name leads. If it leads to your own computer, or to a machine on your network, Diagon does not ask for the picture. The same check is made each time a website passes the request on to another address. Behind a company proxy the proxy looks names up, so there Diagon can only judge the name. When an assistant sends a diagram with an address that plainly breaks the rule — not an https:// link, or a local or private address — Diagon does not apply the diagram, and tells the assistant why. The same happens when one diagram brings in more than five websites you have not allowed yet.
Not loaded. A placeholder with a "no entry" mark — point at it and it says Not loaded — click to see why. — means that the address counts as your assistant's, and Diagon does not load it by itself. Click it. The notice says where the address really leads, shows the address and gives the reason. Sometimes the address is yours after all: the assistant only mentioned the website, and you typed the address in yourself. Then choose It is mine — load it, and from then on Diagon loads it like any picture you add yourself. An address with a user name in front of the website name has no such button, because it can read as one website and lead to another. If it is yours, type it without that part. Nor has an address that is not a web address at all.
What counts as the assistant's. An address counts as the assistant's when its website name was written by an assistant — into this diagram or into any other on this computer, anywhere in the text, a comment included, and also after you save the file, open it again or restart Diagon. So an address you type yourself, to a website an assistant once wrote into one of your diagrams, counts as the assistant's too: a public one loads as before, or waits for your Allow; one that is not https://, or that is on your own network, shows as not loaded until you choose It is mine — load it. Pictures you add yourself can come from anywhere, and the assistant leaves them alone.
What Diagon keeps for this. A fingerprint of the text your assistants wrote: a table of yes-and-no marks, about half a megabyte, on this computer. It is not the text. It is not a secret either: somebody who has that file can test whether a word or an address was in the text, and can piece parts of it together. It stays on this computer; Diagon sends it nowhere. It is kept in the folder assistant-record in Diagon's own data folder, together with the addresses that are your own and the websites you allowed. Every open Diagon window shares it: what an assistant wrote in one window is known in the others. If Diagon cannot write to that folder, it does not apply an assistant's diagram, and the assistant is told why. To remove what Diagon keeps for this, close every Diagon window and delete that folder. Uninstalling Diagon leaves it in place.
The limits. What Diagon knows is kept on this computer: a diagram opened on another computer, or after Diagon's data was cleared, is read like any file from somewhere else, and all its pictures load — the ones an assistant added too. The check goes by the text, so an address whose website name you typed a letter into, or cut or joined in more than two places, counts as yours. And an assistant that sends a flood of text can fill the fingerprint; then every new address counts as the assistant's. Nothing loads by mistake that way, and It is mine — load it still works.
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 — but under stricter rules. Icons from three libraries load straight away, a picture from any other public website waits until you have allowed that website, and an address that is not a public https:// link is never loaded for an assistant. Pictures an assistant adds, above, has the rules. 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 and no class notation, 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. In those pictures the dashes of a
flowline stand still.
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.