# embed_diagram

> Page: https://docs.plotwork.dev/mcp/tools/embed-diagram. Index of every page: https://docs.plotwork.dev/llms.txt

Write a snippet that shows a Plotwork picture in a web page or a React app with the viewer @plotwork.official/viewer (pan, zoom, trace). It is a single tool of the MCP server and the HTTP API, with the title "Embed diagram".

## TL;DR

| Question | Answer |
|---|---|
| What is it? | A single tool: it does one thing. |
| What does it do? | Write a snippet that shows a Plotwork picture in a web page or a React app with the viewer @plotwork.official/viewer (pan, zoom, trace). |
| How do I call it over HTTP? | [`POST /v1/diagrams/embed`](https://docs.plotwork.dev/api/post-v1-diagrams-embed.md) |
| Does it change anything? | No. It is read-only and idempotent, and it talks to nothing outside itself. It saves no file and returns its answer as data. |
| Which bounds apply? | None beyond the limits of each argument, which are in the schema below. |
| Where do I read its schema as data? | An MCP client gets the name, description, and JSON Schema of every tool from `tools/list`. |

## What it does

Write a snippet that shows a Plotwork picture in a web page or a React app with the viewer @plotwork.official/viewer (pan, zoom, trace). Send a hosted url, the svg text of a file the site serves, or both. pin adds the svg fingerprint so only that picture shows; live follows /l/ and /o/ links. A choice that cannot apply is left out and said in notes. Fetches nothing.

## Arguments

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | `string` | no | A hosted picture (/d/), stable link (/l/) or organisation embed link (/o/) on cdn.plotwork.dev. Never fetched. at least 1 character; at most 200 characters. |
| `svg` | `string` | no | The text of a Plotwork SVG; needed to pin. at least 1 character; at most 1000000 characters. |
| `path` | `string` | no | Where the page serves svg from, when there is no url. at least 1 character; at most 500 characters. |
| `format` | `"html" \| "react"` | no | html for any page, react for React. default "html". |
| `live` | `boolean` | no | Follow new versions: /l/ and /o/ links only. default false. |
| `pin` | `boolean` | no | Show only exactly this picture: needs svg. default false. |
| `label` | `string` | no | What the diagram shows, for a screen reader. at most 200 characters. |

## Result

| Field | Type | Required | Description |
|---|---|---|---|
| `ok` | `boolean` | yes | False when the url is not a hosted picture or the svg is not an SVG; message and hint say why. |
| `snippet` | `string \| null` | yes | The code to paste into the page or component, or null when ok is false. |
| `install` | `string` | yes | The command that installs the viewer. |
| `src` | `string \| null` | yes | The address the snippet loads the picture from. |
| `linkKind` | `"picture" \| "stable" \| "organisation" \| null` | yes | picture (/d/), stable (/l/), organisation (/o/), or null for a file the page serves. |
| `fingerprint` | `string \| null` | yes | sha256-<hex> of the svg text, whether or not the snippet pins it; null without svg. |
| `live` | `boolean` | yes | True when the snippet carries live. |
| `pinned` | `boolean` | yes | True when the snippet carries fingerprint. |
| `notes` | `string[]` | yes | Each choice left out and why, and what to know about the link. |
| `message` | `string` | yes | What happened, in one sentence. |
| `hint` | `string \| null` | yes | What to send instead, when ok is false. |

## Behavior hints

| Hint | Value |
|---|---|
| `readOnlyHint` | true |
| `destructiveHint` | false |
| `idempotentHint` | true |
| `openWorldHint` | false |

## See also

| Doc | Why |
|---|---|
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | Every tool, with the workflows first |
| [`POST /v1/diagrams/embed`](https://docs.plotwork.dev/api/post-v1-diagrams-embed.md) | The same operation over HTTP |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | What the diagram source may contain |
| [Writing diagrams with an agent](https://docs.plotwork.dev/mcp/agent-loop.md) | The loop in practice |