Hosted diagrams and plans

Custom icons

Upload your company's own service logos to an organisation, and the hosted service draws them in your diagrams as icon=org:<name>. Icon search, map_icons and automatic icon matching find them by name and by alias.

TL;DR

Question	Answer
What is a custom icon?	An SVG or PNG logo of at most 32 KB, saved on an organisation under a name such as `payments-api`. A diagram uses it as `icon=org:payments-api`.
Which plan?	Pro. The organisation's owner must be on Pro for icons to be uploaded and drawn. Pro keeps up to 100 icons per organisation.
Who can upload?	The organisation's owner or an admin, on the organisation's Icons tab in the portal. Members and readers see the icons.
Which calls draw them?	The hosted MCP server, the REST API and publishing, for the organisation's API keys and for members who chose the organisation for their own calls.
Does the local package draw them?	No. The local MCP server, the npm package, the command line and the GitHub Action know no `org:` name, and report one as an unknown icon.
Is an uploaded SVG safe?	It is read with a strict parser and written again from an allowlist of drawing elements. Scripts, event handlers, embedded HTML, style blocks and any link outside the file are refused with a reason. The picture is then drawn as an image, which cannot run code or load anything.
Can an agent upload an icon?	No. No tool takes an icon. The hosted service picks the icons from who is calling.

1. Upload an icon

Open the organisation in the portal and choose the Icons tab.
Drop an SVG or PNG file on the upload area, or choose one.
Check the name. It is made from the file name, and you can change it: lowercase letters and digits joined by hyphens, at most 48 characters.
Add aliases, separated by commas, such as payments service, Acme Pay. Search and automatic matching find the icon by each of them.
Choose Upload icon.

Each icon is shown on a light and a dark background, the way diagrams draw it. Upload a file with a name that is already taken to replace that icon. To delete one, choose Remove on its tile.

Role	Can do
Owner	See, upload, replace and delete icons
Admin	See, upload, replace and delete icons
Member	See the icons
Reader	See the icons
Organisation API key	See the icons, and draw with them

If the owner moves from Pro to Free, the icons are kept but not drawn, and they are drawn again when the owner is back on Pro.

2. What a file may hold

The upload check keeps drawing and nothing else.

Kept	Refused, with a reason	Left out quietly
Paths, circles, ellipses, rectangles, lines, polylines, polygons, groups	`script`, event handlers such as `onload`	Editor metadata, `desc`, Inkscape and Sodipodi data
Linear and radial gradients, clip paths, masks, inside the file	`foreignObject`, `iframe`, `image`, `use`, `a`, animations	`class` and `data-` attributes
Fill, stroke, opacity, transform, and the same properties in a `style` attribute	A `<style>` block: export with presentation attributes	Style properties that do not paint
A title	A DOCTYPE, entities, CDATA, a link or `url()` to anything outside the file
	Text that is not converted to outlines, filters, patterns

Limit	Value
File size	32 KB
Elements	2,000
Nesting	24 levels
Path commands	4,000
PNG size	1,024 pixels on each side
Aliases	10, each at most 60 characters

A PNG keeps only the chunks that draw the picture, so text and EXIF metadata, which can hold a location, are not stored. Every id in an SVG is renamed after the icon, so two icons never share one.

When a file is refused, the Icons tab lists every reason beside the file, each with how to fix it. The REST API answers 422 icon.invalid with the same list in details.

3. Use an icon in a diagram

Write the name after org:, the same way as any other icon:

1flow "Checkout" direction=right2node shop  service  "Storefront"3node pay   service  "Acme Pay"   icon=org:acme-pay4node books database "Ledger"     icon=org:ledger5shop -> pay6pay -> books

An organisation icon is drawn in its own colors on a light tile, in both themes, like an official cloud icon. A node with no icon= whose whole label is an icon's name or alias, such as "Acme Pay", draws that icon by itself, as it does for a bundled product name. With icons=off in the header it is not drawn, and the check suggests icon=org:acme-pay instead.

Tool	What it does with your icons
`search_icons`	Lists `org:` icons first when they match as well as a bundled icon
`map_icons`	Resolves a name that is an icon's name or alias to that icon, with confidence `exact`
`draw_diagram`, `render_diagram`, `publish_diagram`	Draws `org:` icons
`validate_diagram`	Accepts `org:` names that exist, and suggests the nearest one for a misspelling

4. Which calls use which icons

Caller	Icons
An organisation's API key	That organisation's icons
A personal key, an agent connected by sign-in, the portal	The icons of the organisation chosen under "Organisation style for my own diagrams" on the Organisations page, or named by `brand.organization` in the repository settings, while you are a member
A diagram published into an organisation's library	That organisation's icons, whoever publishes
The local MCP server, the npm package, the CLI, the GitHub Action	None

A picture that is already published keeps the icon it was drawn with, even after the icon is replaced or deleted. Publish it again to draw the new one.

5. Privacy

An icon is organisation configuration, like a brand: the file the check wrote, its name and aliases, the account that uploaded it, and when. It is deleted with the organisation. No diagram is stored to draw one. The operator's audit trail records that an icon was saved or deleted, with the organisation's id, and never its name or file. On Pro and Enterprise the organisation's own audit log records the icon's name and who saved or deleted it, never the file.

Page	Why
Brand themes	Paint the same diagrams in your company's colors
Organisations	Roles, keys and the library icons sit beside
Cloud icon names	The bundled icons and how names are written
Plans and billing	What Pro includes
Privacy policy	What is stored, and for how long