Connecting an agent
How to connect an AI agent or an editor to the diagram tools over MCP (Model Context Protocol). It is for anyone setting up Claude Code, Cursor, VS Code, Claude Desktop, or another MCP client.
- Claude Code
- Cursor
- VS Code
- Claude Desktop
TL;DR
| Way to connect | What you need | Use it when |
|---|---|---|
Local, with npx | Node 22 or newer. No key, no sign-in, no account. | You work on one machine. This is the way to start. |
| Hosted, with an API key | A key from app.plotwork.dev (opens in a new tab), sent in the X-API-Key header. | A client cannot start a local process, or an agent runs on a server. |
| Hosted, with a browser sign-in | A Plotwork account. Your client opens a browser. | You want no key to copy, store, or rotate. |
All three give the same tools and the same results. Pick one per client.
1. Connect locally, without a key
The local server is an npm package. Your client starts it with npx, it talks to the client over standard input and output, 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. Counting your use and sharing totals with Plotwork are options you turn on, and are off otherwise. It needs no key, no sign-in, and no account, because every tool is a pure computation over its arguments.
Claude Code
claude mcp add plotwork -- npx -y @buun_group/plotwork-mcp@0.1.0-beta.10Then run /mcp inside Claude Code to confirm that plotwork is connected and lists the Plotwork tools.
To have every diagram Claude saves drawn to an SVG in your docs as well, install the Claude Code plugin instead: it adds this server, a hook that runs the command line on save, and a preview on localhost.
Cursor
Add this to ~/.cursor/mcp.json:
{ "mcpServers": { "plotwork": { "command": "npx", "args": [ "-y", "@buun_group/plotwork-mcp@0.1.0-beta.10" ] } }}VS Code
Add this to .vscode/mcp.json:
{ "servers": { "plotwork": { "type": "stdio", "command": "npx", "args": [ "-y", "@buun_group/plotwork-mcp@0.1.0-beta.10" ] } }}Claude Desktop
Add this to claude_desktop_config.json, then restart Claude Desktop:
{ "mcpServers": { "plotwork": { "command": "npx", "args": [ "-y", "@buun_group/plotwork-mcp@0.1.0-beta.10" ] } }}Other clients
A client that starts an MCP server as a local process takes two parts: the command npx and the arguments -y @buun_group/plotwork-mcp@0.1.0-beta.10. The setting names differ between clients, so check your client's documentation for the exact keys.
Open and self-hosted models
For a model you run yourself (gpt-oss, Qwen, Gemma, or Llama on Ollama, LM Studio, vLLM, or llama.cpp) through Goose, Cline, Continue, LM Studio, or the OpenAI Agents SDK, set PLOTWORK_TOOLS=core so the server lists only its eight workflow tools, and give the model a context of 16,384 tokens or more. Use Plotwork with open and self-hosted models has the settings for each client and the results of each model we ran.
2. Connect to the hosted server with an API key
The hosted server is at https://mcp.plotwork.dev/mcp. Every request carries an API key in the X-API-Key header. The key gives your calls an identity, a rate limit per minute, and a share of your account's daily allowance: 300 calls on Free and 50,000 on Pro. Every tool call counts, from every key and every connected agent on the account. Listing the tools and connecting do not. Plans and billing explains the plans and how to upgrade. The Usage page at app.plotwork.dev/usage (opens in a new tab) shows today's count and the last 30 days.
A key can also belong to an organisation instead of a person. An owner or admin makes it on the organisation's Keys tab. With that key, publish_diagram files a diagram in the organisation's private library by default, it cannot publish to any other organisation, and its calls count toward the owner's allowance.
- Sign in at app.plotwork.dev (opens in a new tab) and create a key. Copy it then, or press Reveal in your list of keys to see it again later. A key made before Reveal existed cannot be shown again.
- Put it in an environment variable named
PLOTWORK_API_KEY, so it never appears in a file you share. - Add the server to your client.
Claude Code
claude mcp add --transport http plotwork https://mcp.plotwork.dev/mcp \ --header "X-API-Key: $PLOTWORK_API_KEY"Cursor
Add this to ~/.cursor/mcp.json:
{ "mcpServers": { "plotwork": { "url": "https://mcp.plotwork.dev/mcp", "headers": { "X-API-Key": "${env:PLOTWORK_API_KEY}" } } }}VS Code
Add this to .vscode/mcp.json. VS Code asks for the key once and keeps it out of the file:
{ "inputs": [ { "type": "promptString", "id": "plotwork-key", "description": "Plotwork API key", "password": true } ], "servers": { "plotwork": { "type": "http", "url": "https://mcp.plotwork.dev/mcp", "headers": { "X-API-Key": "${input:plotwork-key}" } } }}Claude Desktop
Claude Desktop starts local processes from its configuration file, so it reaches a hosted server through mcp-remote. Add this to claude_desktop_config.json, with your key in place of your-api-key, then restart Claude Desktop:
{ "mcpServers": { "plotwork": { "command": "npx", "args": [ "mcp-remote", "https://mcp.plotwork.dev/mcp", "--header", "X-API-Key:${PLOTWORK_API_KEY}" ], "env": { "PLOTWORK_API_KEY": "your-api-key" } } }}Write the header as X-API-Key:${PLOTWORK_API_KEY} with no space after the colon. Some clients split the argument on a space.
3. Connect to the hosted server with a browser sign-in
The sign-in address is https://mcp.plotwork.dev/mcp-oauth. It is the same server, and your client signs you in through a browser (OAuth) instead of sending a key. You copy nothing, and you can disconnect a client from your account at any time.
Add the address and nothing else. Your client sees that it must sign in and opens a browser, where you approve the connection.
The approval page names your account, the name the client gave itself, and where it returns to. A client that identifies itself by a web address (a client ID metadata document) instead of registering also shows the website that published that address, under Published by. Each computer you connect a client from is its own connection: connecting on a second computer keeps the first connected, and connecting again on the same computer replaces that computer's connection. Every connection is listed under Connected agents in the portal, where you can end it.
Claude Code
claude mcp add --transport http plotwork https://mcp.plotwork.dev/mcp-oauthThen run /mcp inside Claude Code and choose to authenticate plotwork.
Cursor
Add this to ~/.cursor/mcp.json. Cursor marks the server as needing a sign-in, and you complete it from its MCP settings:
{ "mcpServers": { "plotwork": { "url": "https://mcp.plotwork.dev/mcp-oauth" } }}VS Code
Add this to .vscode/mcp.json:
{ "servers": { "plotwork": { "type": "http", "url": "https://mcp.plotwork.dev/mcp-oauth" } }}Claude Desktop
Open Settings, then Connectors, then add a custom connector, and enter this address:
https://mcp.plotwork.dev/mcp-oauth4. Check the connection by hand
Each of these prints a JSON-RPC response when the server works.
| Check | Command |
|---|---|
| Local version | npx -y @buun_group/plotwork-mcp@0.1.0-beta.10 --version |
| Local handshake | echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' | npx -y @buun_group/plotwork-mcp@0.1.0-beta.10 |
| Hosted tool list | curl -s -X POST https://mcp.plotwork.dev/mcp -H "X-API-Key: $PLOTWORK_API_KEY" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' |
5. What the server exposes
| Item | Value |
|---|---|
| Server name | plotwork |
| Tools | Every tool in the tool reference, as tools/list returns them. The hosted server adds publish_diagram, which hosts a diagram at a public link, or in an organisation's private library when given the organization option, list_diagrams, which lists the diagrams you host, and delete_diagram, which deletes one of them: see Hosted diagrams and Organisations. The local server never has them. |
| Behavior hints | Every tool is read-only, idempotent, and closed-world, except publish_diagram and delete_diagram. They are on the hosted server only. publish_diagram stores a diagram, so it is not read-only, and it only ever adds, so it is not destructive. It is idempotent and closed-world. delete_diagram removes a diagram, so it is destructive, and a second call finds nothing to delete, so it is not idempotent. It is closed-world. list_diagrams is read-only, idempotent and closed-world like the rest. |
| Instructions | The server tells a model to read the syntax once, prefer the workflow tools, and call draw_diagram until the source is valid. A valid result carries the warnings, the outline, and the SVG. |
| Failures | A diagram with mistakes is a normal tool result marked as an error, with line, column, and hint for each mistake. A crash returns a generic message; the detail goes to the log. |
| Logs | One line per call: tool, outcome, duration, and argument size. Argument contents are never logged. The local server writes them to standard error. |
6. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The client cannot find the command | npx is not on the client's path | Use the absolute path to npx, or run which npx and use that. |
| The client reports invalid JSON from the server | Something other than the server printed to standard output | Remove any wrapper script around the command, and start it as npx -y @buun_group/plotwork-mcp@0.1.0-beta.10. |
| The local server does not start | Node is older than 22 | Run node --version, and install Node 22 or newer. |
| The hosted server answers 401 | The key is missing, wrong, or revoked | Send it in the X-API-Key header, or create a new key at app.plotwork.dev (opens in a new tab). |
| The hosted server answers 429 | The key spent its allowance for the minute | Wait a minute and call again. |
The hosted server answers 429 with usage.daily_limit | The account made all of its calls for the day (300 on Free, 50,000 on Pro), counted across every key and connected agent | Wait until 00:00 UTC, when the count starts again, or upgrade to Pro. The retry-after header says how many seconds that is. See Plans and billing. |
publish_diagram answers with hosting.quota_exceeded | The plan holds no more hosted diagrams, or no more bytes of them | Delete a diagram on the Diagrams page of the portal, or ask the agent to list your diagrams and delete the one you name, or upgrade. An agent does not delete anything to make room on its own. See Hosted diagrams. |
publish_diagram answers with not_found when it names an organisation | The organisation does not exist, or your account is not a member of it. The answer is the same for both. | Ask the person which organisation they mean, check its handle in the portal, and do not publish to another one or to the personal library instead. See Organisations. |
publish_diagram answers with orgs.key_wrong_org | The key belongs to one organisation and the call named another | Leave organization out to use the key's own organisation, or use a key for the one you want. |
publish_diagram answers with orgs.folder_restricted | The organisation's owner restricted that folder to some roles and people, and this account or key is not one of them. A key needs key named in the rule. | Ask the person which folder they may use, or ask the owner to change the rule. Do not publish somewhere else instead. See Organisations. |
publish_diagram answers with orgs.forbidden | The account is a reader in the organisation, and a reader can look and download but not publish | Ask an admin or the owner to change the role, or publish with a member's account or an organisation key. |
publish_diagram, list_diagrams or delete_diagram is not in the tool list | You are connected to the local server, which does not have them | Connect to the hosted server with an API key or a browser sign-in. |
delete_diagram answers with hosting.diagram_locked | The owner locked the diagram, and nobody can rename, move or delete it until the owner unlocks it | Unlock it in the portal if it is yours to unlock, or ask the owner. The agent does not work around a lock. See Hosted diagrams and Organisations. |
delete_diagram answers with orgs.forbidden | Your role in the organisation does not let you delete that diagram: a member deletes only their own, and a reader deletes none | Ask an admin or the owner to delete it, or to change your role. |
| A sign-in does not finish | The browser did not return to the client | Start the sign-in again from the client, and finish it in the same browser. |
| A tool call returns an error with diagnostics | The diagram source has mistakes | Fix each mistake using its line, column, and hint, then call again. |
See also
| Doc | Why |
|---|---|
| Writing diagrams with an agent | The validate and fix loop the tools support |
| Tool reference | Arguments and results of every tool |
| API reference | The same operations over plain HTTP |
| MCP server | What the server is and how it behaves |
| Open and self-hosted models | The core tool profile, client settings, and results for open models |
| Hosted diagrams | Publish a diagram with the hosted server and share the link |
| Organisations | Publish to a team's private library, with a key of the organisation or your own |
| Plans and billing | The daily allowance of each plan and how to upgrade |