# MCP server

> Page: https://docs.plotwork.dev/mcp/overview. Index of every page: https://docs.plotwork.dev/llms.txt

What the diagram MCP (Model Context Protocol) server is, which tools it exposes, and how it behaves. It is for anyone who wants an AI agent to write, check, and render diagrams.

## TL;DR

| Question | Answer |
|---|---|
| What is it? | A server that gives an agent tools for diagrams. Workflow tools draw a diagram, convert Mermaid, choose icons, and sync a Markdown document, each in one call. Single tools read the source back out of an existing Plotwork SVG, read the language, validate, render, outline, and search icons. Every one of these only reads. The hosted server adds three tools for the diagrams you host: `publish_diagram` stores one, `list_diagrams` shows what is stored, and `delete_diagram` removes one. |
| Which transports? | Standard input and output for a local process, and HTTP for the hosted server. |
| Which diagrams can it draw? | Twenty kinds, chosen by the first word of the source: `flow`, `sequence`, `schema`, `git`, `gantt`, `class`, `state`, `timeline`, `journey`, `mindmap`, `treemap`, `pie`, `quadrant`, `layers`, `c4`, `matrix`, `sankey`, `xychart`, `tree`, and `swimlane`. Every tool takes any of them, and `get_diagram_syntax` returns the shared language with a line about each kind, or any one kind in full when it is given `kind`. See [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md). |
| Does it change anything? | Not by default. Every tool of the local server is read-only and idempotent, and stores nothing. Every one but `read_diagram` is also closed-world; `read_diagram` fetches a link only when it is given one. The hosted server adds three tools that work on the diagrams you host. `publish_diagram` stores a diagram as a public link, or in an organisation's private library when you name an organisation, and only when you ask for one. `list_diagrams` only reads. `delete_diagram` removes a diagram for good, and only after you have said which one. The local server never stores or deletes anything. |
| Does it need a key or a sign-in? | Not locally. The local server needs no key, no sign-in, and no account, and by default it makes no network requests. The one exception is `read_diagram` given the link of a Plotwork picture, which fetches that link and nothing else. If you choose, it can [count your use on your device, and share pseudonymous daily totals](https://docs.plotwork.dev/mcp/usage.md), and it does neither unless you turn it on. The hosted server asks for an API key or a browser sign-in, so each caller has an identity, a rate limit, and a daily allowance. |
| What happens on a mistake in a diagram? | The tool returns every mistake with its line, column, and a hint. The agent fixes the source and calls again. |
| Where does it run? | On your own machine, started by your client with `npx`, or hosted at `https://mcp.plotwork.dev`. Both give the same results. |

## 1. The loop an agent follows

**Diagram source**

```diagram
sequence "Agent and MCP server" desc="An agent reads the language once, then draws a diagram until it is valid. A valid diagram comes back with its warnings, outline, and pictures."

actor agent agent   "AI agent"
actor mcp   service "Diagram MCP server" sub="Read-only tools"

agent -> mcp : "get_diagram_syntax"
mcp --> agent : "Language, limits, examples"

loop "until valid is true" {
  agent -> mcp : "draw_diagram"
  mcp --> agent : "Mistakes with line, column, hint, or warnings, outline, SVG"
}
```

*Picture: Agent and MCP server: 2 participants. An agent reads the language once, then draws a diagram until it is valid. A valid diagram comes back with its warnings, outline, and pictures.*

**Text description**

**Participants:**

- AI agent, agent
- Diagram MCP server (Read-only tools), service

**Steps:**

- 1. AI agent to Diagram MCP server: get_diagram_syntax
- 2. Diagram MCP server to AI agent (dashed): Language, limits, examples
- loop: until valid is true
  - 3. AI agent to Diagram MCP server: draw_diagram
  - 4. Diagram MCP server to AI agent (dashed): Mistakes with line, column, hint, or warnings, outline, SVG

## 2. The tools

| Kind | What it does | Examples |
|---|---|---|
| Workflow | Does the work of several single tools in one call, and returns problems in the source as data. Prefer it. | `draw_diagram` checks, describes, and draws a diagram. `convert_mermaid` converts one Mermaid diagram. `map_icons` chooses icons for many names and returns candidates instead of guessing. `sync_markdown` turns the diagram fences of a whole document into pictures. |
| Single tool | Does one fine-grained step. | `read_diagram` gives back the source of an existing Plotwork SVG, from its text or a hosted link, so an agent can edit it; see [Editing an existing diagram](https://docs.plotwork.dev/editing-existing-diagrams.md). `get_diagram_syntax` returns the language as data: called with no arguments it gives the overview, and called with `kind` it gives that kind in full, so it is called once per session and once more for the kind being drawn. `validate_diagram` returns every mistake with a line, a column, and a hint. `render_diagram` returns one themed SVG. `outline_diagram` returns a plain-text description. `search_icons` finds icon names by name, tag, or idea. |
| Hosted only | Stores, lists, or removes the diagrams you host, so only the hosted server offers them. An agent calls `publish_diagram` only when you ask to share a diagram, and `delete_diagram` only when you name the diagram to delete. | `publish_diagram` hosts a finished diagram at a public link and returns the link with a Markdown image to paste. With its `organization` option it files the diagram in an organisation's private library instead, and returns a sign-in page address and no public link. `list_diagrams` shows what you have hosted, in your own library or an organisation's: each diagram's id, name, folder, size, expiry, whether the owner locked it, and whether you may delete it. It changes nothing. `delete_diagram` deletes one diagram by its id, for good, and refuses a diagram the owner locked or one your role may not delete. |

The [tool reference](https://docs.plotwork.dev/mcp/tools.md) lists every tool the local server has, with its arguments and results. `publish_diagram`, `list_diagrams` and `delete_diagram` are described in [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md), and their `organization` option in [Organisations](https://docs.plotwork.dev/organisations.md).

## 3. How it behaves

| Behavior | Detail |
|---|---|
| Errors in a result | A diagram with mistakes comes back with its diagnostics, so the model can read them and fix its input. A workflow and `validate_diagram` return them as a normal result. `render_diagram` and `outline_diagram` mark the result as an error. Bad arguments are refused the same way. |
| Crashes stay private | An unexpected failure is answered with a short generic message. No stack trace reaches the model. |
| Privacy | Each call is logged as one line: tool, outcome, duration, and argument size. Argument contents are never logged. |
| Nothing is stored | Each call stands alone. The server keeps nothing between calls and writes no files, except the local server with `PLOTWORK_OPEN=1`, which writes each drawing to your temporary folder to open it in your browser. The one exception is a diagram you publish with `publish_diagram` on the hosted server: Plotwork stores its picture so the link keeps working, or so your organisation's library has it, until you delete it with `delete_diagram` or in the portal. See [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) and [Organisations](https://docs.plotwork.dev/organisations.md). |
| Daily allowance | The hosted server counts each tool call toward one allowance per account, shared with the REST API and with every key and connected agent. The plan sets it: 300 a day on Free and 50,000 a day on Pro. Listing the tools and connecting are free. When it is spent, the server answers HTTP 429 and a JSON-RPC error with code -32029 and `usage.daily_limit` in its data, until 00:00 UTC. The local server has no allowance. See [Plans and billing](https://docs.plotwork.dev/plans-and-billing.md). |
| Seeing a drawing | A valid answer of `draw_diagram`, `draw_from_pattern`, or `convert_mermaid` has `viewUrl`, a link to a page that draws the diagram in the browser from the part after `#`, which is never sent to a server. A client with MCP Apps (Claude, Claude Desktop, VS Code, ChatGPT) also shows the drawing inline. The local server reads `PLOTWORK_VIEWER_URL` to point the link elsewhere. See [Viewing diagrams](https://docs.plotwork.dev/viewing-diagrams.md). |
| Judging the look | A valid answer of `validate_diagram`, `draw_diagram`, `draw_from_pattern`, or `convert_mermaid` has `quality`: a `score` from 0 to 100, a `grade` (`clean` at 85 or more, `fair` at 60 or more, `cluttered` below), the `measures` it comes from (line crossings, lines across boxes, overlapping labels, the smallest text in an 880px column, the shape, the empty space, how far lines detour, and for charts the series and slices), and up to three `hints` that name a statement to change, such as `add direction=down to the header line` or `shorten label "..."`. It is read from the laid-out picture, so a model that cannot see the drawing can still judge it, and it comes back with `svg` set to `never`. The same diagram always gets the same report. |
| Icon aliases | An everyday word written as an icon name, such as `lucide:cart` or `lucide:bank`, draws the bundled icon it means and comes back in `notices` as I122 with the real name, never as an error. See [Icon names and lookup](https://docs.plotwork.dev/cloud-architecture/icon-names.md). |
| Large drawings | Some clients refuse a tool answer over a size: Claude Code stops at 25,000 tokens. When the answer of `draw_diagram`, `draw_from_pattern`, or `convert_mermaid` would pass 36,000 characters (about 30 nodes in both color schemes), the pictures are left out from the dark one back, `picturesOmitted` says which, and the check, warnings, and outline still come back. `publish_diagram` gives a link instead on the hosted server. Pass `svg` as `always` to get every picture whatever the size, or `never` to skip drawing while you fix mistakes, which is cheaper. The local server reads `PLOTWORK_MCP_RESULT_LIMIT` (a number of characters, at least 4,000) to move the limit. The HTTP API ignores the limit. |
| Limits | Source is limited to 50,000 characters. A flow diagram may have 500 nodes, and its connections may skip over at most 1000 tiers between them; past either the call returns error E140 with a hint, before any layout work, because a tangle of long connections costs far more than a tidy diagram of the same size. Quality warnings start at 15 flow nodes, 6 tables, or 6 actors. |

## 4. Connect to it

There are three ways to connect, and each gives the same tools. The two hosted ways add `publish_diagram`, `list_diagrams` and `delete_diagram`.

| Way | Address or command | What it needs |
|---|---|---|
| Local, free | `npx -y @buun_group/plotwork-mcp@0.1.0-beta.10` | Node 22 or newer. No key, no sign-in, no account. The client starts it as a child process. |
| Hosted, with an API key | `https://mcp.plotwork.dev/mcp` | A key created at [app.plotwork.dev](https://app.plotwork.dev), sent in the `X-API-Key` header. |
| Hosted, with a browser sign-in | `https://mcp.plotwork.dev/mcp-oauth` | A Plotwork account. The client opens a browser and you approve the connection. |

Use the local server when you work on one machine. Use the hosted server when a client cannot start a local process, or when an agent runs on a server.

[Connecting an agent](https://docs.plotwork.dev/mcp/connect.md) shows the settings for Claude Code, Cursor, VS Code, and Claude Desktop.

## 5. Save diagrams to your library

Saving a finished diagram to Plotwork keeps it where your team can find it, beside the files and view links on your machine. Where it goes depends on how you connect.

| You use | What happens |
|---|---|
| The hosted MCP server, and an organisation you belong to keeps members' diagrams in its library | The server tells the agent to save each finished diagram to that private library with `publish_diagram`, without asking you, because only members can open it. Each valid drawing's next step says so too, and the answer names the library and gives the page for members. See [Where members publish](https://docs.plotwork.dev/organisations.md#13-where-members-publish). |
| The hosted MCP server with an organisation key | The same: the key's own library is private, so the agent saves there. |
| The hosted MCP server with only your own library | The agent publishes only when you ask, because that link is public. |
| The local MCP server | Nothing is saved: it has no account. Use the command line below. |
| The command line | `plotwork publish file.diagram` saves every diagram of a file with the key in `PLOTWORK_API_KEY`, where your organisations decide, and prints the link. `--org` names the library. |
| The Claude Code plugin | `PLOTWORK_PUBLISH=library` saves each file to the organisation in `PLOTWORK_ORG` after it is drawn. See [Claude Code plugin](https://docs.plotwork.dev/agents/claude-code-plugin.md#save-to-your-organisations-library). |

## See also

| Doc | Why |
|---|---|
| [Plotwork for AI agents](https://docs.plotwork.dev/agents/overview.md) | What an agent needs to know in one page, and the rules to paste into a project |
| [Connecting an agent](https://docs.plotwork.dev/mcp/connect.md) | Client settings and troubleshooting |
| [Writing diagrams with an agent](https://docs.plotwork.dev/mcp/agent-loop.md) | The validate and fix loop in practice |
| [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) | Publish a diagram with `publish_diagram`, see what is stored with `list_diagrams`, and remove one with `delete_diagram` |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Publish to, list, and delete from a team's private library with the `organization` option, and lock a diagram |
| [Plans and billing](https://docs.plotwork.dev/plans-and-billing.md) | The daily allowance of each plan, and what happens when it is spent |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | Arguments and results of every tool |
| [API reference](https://docs.plotwork.dev/api/reference.md) | The same operations over plain HTTP |