AI drawing

This page is a reference for how an AI client (ChatGPT, Claude, Gemini, Cursor, …) draws professional diagrams in LetDraw over the API and MCP. The model does not need to guess LetDraw’s schema: everything below is also presented to the model at call time, so a connected model can read it and draw correctly on the first try.

How the model learns LetDraw

You do not retrain the model; you give it context at call time. LetDraw exposes all of its drawing knowledge through the MCP server and REST API:

What	MCP	REST
How to draw (this guide, machine-readable)	resource `letdraw://capabilities`	`GET /capabilities`
Every icon library + all item labels	resource `letdraw://libraries`	`GET /libraries?items=1`
Library ids + counts	tool `list_shape_libraries`	`GET /libraries`
Find an icon for a component	tool `search_icons`	`GET /icons?query=…`
Create / update a diagram	tools `create_diagram` / `update_diagram`	`POST` / `PATCH /documents`

A well-behaved client reads the letdraw://capabilities and letdraw://libraries resources once, then draws. Point your AI at the MCP endpoint (see API and MCP); it discovers the rest on its own.

Golden rules for professional output

Use real icons, do not draw them. Call search_icons (e.g. "postgres", "redis", "kubernetes pod", "load balancer") and put the returned ref value into the box’s iconRef field (e.g. "databases/PostgreSQL"). The server stamps that exact icon and flows the label beneath it.
Keep containers clean. Large grouping boxes (a Kubernetes Cluster, a VPC, a subnet band) should be wide (> 420px) or a frame. Icons are only stamped onto node-sized boxes (60-420px wide, 40-260px tall). Place a container’s title as standalone text above it, not as a bound label.
Nest deliberately. Outer colored container to node-sized boxes inside, each with its own icon. Two or three levels read best (Cluster to Worker Node to Pod).
Route arrows cleanly. For right-angle / multi-bend connections, send an arrow with 3+ points; bind the ends to shapes so they stay attached.
Color-code by role and keep spacing consistent.

Sending a scene

create_diagram / update_diagram accept elements as either letdraw-native elements or standard Excalidraw JSON (auto-detected and converted on the server). Producing Excalidraw JSON is the easiest high-quality path; native LetDraw gives you the letdraw-specific features below.

Common element fields

Shape types

rectangle, ellipse, diamond, triangle, right-triangle, parallelogram, trapezoid, star, hexagon, heptagon, octagon, cross, cloud, cylinder, speech-bubble, document, manual-input, display, terminator, data-storage, preparation, block arrows (arrow-right/left/up/down), plus text, image (dataURL), frame (labeled dashed section; set name), embed (url), math (LaTeX in text), code (source in text, language). A shape carries its label with text inside (in Excalidraw format, via a text element with containerId).

Arrows

type: "arrow" and:

arrowShape: straight | curved | elbow | s-curve | smart | multipoint | multipoint-curved. smart automatically routes around other shapes. multipoint is a sharp multi-segment polyline; multipoint-curved is its smoothed version; both read their corners from points.
points: {x, y}[] in absolute world coordinates (first to last). 2 points = straight, 3 = elbow (single bend), 4+ = routed polyline. Right-angle connection: points: [{x1,y1},{x2,y1},{x2,y2}].
controlPoint / controlPoint2: bezier handles for curved / s-curve / elbow.
startArrowhead / endArrowhead: none | arrow | triangle | triangle-outline | circle | diamond | diamond-outline | bar | crows-foot | crows-foot-bar | double-bar | circle-bar | circle-crows-foot. Use UML heads (triangle-outline = generalization, diamond = composition) and ER crow’s-foot heads for cardinality.
startBinding / endBinding: {elementId, focus:{x,y}}: bind an end to a shape (focus is a 0..1 point in the shape’s bbox) so the arrow follows it.

In Excalidraw format, send the arrow with points + startArrowhead/endArrowhead; the converter maps 2 / 3 / 4+ points to straight / elbow / s-curve and recomputes the bindings.

Lines

type: "line" and lineShape: straight | multipoint | multipoint-curved. Multipoint lines carry points (same as arrows, without an arrowhead). Also freedraw (points[]) and highlight (semi-transparent marker).

Icons: the `iconRef` flow

search_icons({ query }) produces a ranked [{ library, label, ref }].
Set iconRef: "<library>/<Item Label>" (or { library, label }) on the target box.
create_diagram stamps that icon top-center and moves the label below it.

An explicit iconRef always wins; then any remaining labeled node without an icon automatically gets a best-guess keyword icon. In a cloud scene, specify the vendor (kubernetes / aws / azure / gcp) so the vendor icon sets are preferred. Browse ids with list_shape_libraries; the full label catalog is in letdraw://libraries (or GET /libraries?items=1).

Database products resolve to the Databases library: real logos where brand policy allows (PostgreSQL, MariaDB, Cassandra, DynamoDB, …), otherwise DB-appropriate generic icons (MySQL, Redis, MongoDB, …).

Small Excalidraw-format example

[
  { "id": "db", "type": "rectangle", "x": 0, "y": 0, "width": 200, "height": 90,
    "backgroundColor": "#eef2ff", "strokeColor": "#334155", "roundness": { "type": 3 },
    "iconRef": "databases/PostgreSQL", "boundElements": [{ "type": "text", "id": "dbt" }] },
  { "id": "dbt", "type": "text", "x": 10, "y": 30, "text": "Orders DB", "containerId": "db" },
  { "id": "a1", "type": "arrow", "x": 200, "y": 45, "points": [[0, 0], [80, 0], [80, 120]],
    "endArrowhead": "triangle", "startBinding": { "elementId": "db" } }
]

Other tools

diagram_from_code: send docker-compose / Kubernetes manifest / Graphviz DOT / PlantUML / Terraform / Helm values / SQL DDL; LetDraw auto-detects the format and lays it out.
export_to_code: a diagram to Mermaid or D2.
generate_from_prompt: natural language to diagram, using your account’s own AI key.

For authentication, endpoints, scopes, and client setup, see API and MCP.