# Connecting an agent

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

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.

## 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](https://app.plotwork.dev), 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](https://docs.plotwork.dev/mcp/usage.md), 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

```sh
claude mcp add plotwork -- npx -y @buun_group/plotwork-mcp@0.1.0-beta.10
```

Then 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](https://docs.plotwork.dev/agents/claude-code-plugin.md) 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`:

```json
{
  "mcpServers": {
    "plotwork": {
      "command": "npx",
      "args": [
        "-y",
        "@buun_group/plotwork-mcp@0.1.0-beta.10"
      ]
    }
  }
}
```

### VS Code

Add this to `.vscode/mcp.json`:

```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:

```json
{
  "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](https://docs.plotwork.dev/mcp/open-models.md) 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](https://docs.plotwork.dev/plans-and-billing.md) explains the plans and how to upgrade. The Usage page at [app.plotwork.dev/usage](https://app.plotwork.dev/usage) shows today's count and the last 30 days.

A key can also belong to an [organisation](https://docs.plotwork.dev/organisations.md) 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.

1. Sign in at [app.plotwork.dev](https://app.plotwork.dev) 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.
2. Put it in an environment variable named `PLOTWORK_API_KEY`, so it never appears in a file you share.
3. Add the server to your client.

### Claude Code

```sh
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`:

```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:

```json
{
  "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:

```json
{
  "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

```sh
claude mcp add --transport http plotwork https://mcp.plotwork.dev/mcp-oauth
```

Then 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:

```json
{
  "mcpServers": {
    "plotwork": {
      "url": "https://mcp.plotwork.dev/mcp-oauth"
    }
  }
}
```

### VS Code

Add this to `.vscode/mcp.json`:

```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:

```text
https://mcp.plotwork.dev/mcp-oauth
```

## 4. 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](https://docs.plotwork.dev/mcp/tools.md), 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](https://docs.plotwork.dev/hosted-diagrams.md) and [Organisations](https://docs.plotwork.dev/organisations.md). 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](https://app.plotwork.dev). |
| 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](https://docs.plotwork.dev/plans-and-billing.md). |
| `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](https://docs.plotwork.dev/hosted-diagrams.md). |
| `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](https://docs.plotwork.dev/organisations.md). |
| `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](https://docs.plotwork.dev/organisations.md#6-restrict-a-folder). |
| `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](https://docs.plotwork.dev/hosted-diagrams.md#lock-a-diagram) and [Organisations](https://docs.plotwork.dev/organisations.md#who-may-delete-and-lock). |
| `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](https://docs.plotwork.dev/mcp/agent-loop.md) | The validate and fix loop the tools support |
| [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 |
| [MCP server](https://docs.plotwork.dev/mcp/overview.md) | What the server is and how it behaves |
| [Open and self-hosted models](https://docs.plotwork.dev/mcp/open-models.md) | The core tool profile, client settings, and results for open models |
| [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) | Publish a diagram with the hosted server and share the link |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Publish to a team's private library, with a key of the organisation or your own |
| [Plans and billing](https://docs.plotwork.dev/plans-and-billing.md) | The daily allowance of each plan and how to upgrade |