The sketch tool

Register the server

In Claude Code:

claude mcp add excalix --scope user -- npx -y excalix mcp

Any other client that launches stdio servers takes this entry:

{"mcpServers":{"excalix":{"command":"npx","args":["-y","excalix","mcp"]}}}

The server needs Chromium, like the CLI; see getting started. It opens one browser on the first call and reuses it until the client disconnects. A sketch finishes inside the call, so the tool declares execution.taskSupport as "forbidden".

What the agent reads

The tool description is the whole guide the agent gets unless the skill is installed too. It is served verbatim from tools/list:

Draws an architecture diagram. You give the topology, what exists and what talks to what; excalix picks every shape, colour, size and route, so there is nothing visual to configure.

A node sits in exactly one group: name the group it runs in, and let an edge across the boundary carry any other relationship.

List nodes in reading order, sources first. That is all order does: place siblings beside each other. It never steers where an arrow is routed; what moves a layout is the direction of an edge, which nodes share a group, and direction itself.

Look at the returned image and call again with an adjusted spec if labels overlap or the flow reads wrong.

Those are excerpts. Between them the description defines the six node kinds and two edge styles and gives the sizing advice from the spec reference. The full text and both schemas live in the contract snapshot, which the test suite keeps in step with the server.

Input

The input schema is the spec, unchanged, plus one optional field:

Every object in the schema sets additionalProperties: false, and each field carries a description written for the model reading it.

A successful result

A call with the order pipeline spec and no out comes back in three parts. The paths are absolute; here the project lives in /path/to/project.

A text block

The three paths, one per line, in this order:

/path/to/project/diagrams/order-pipeline.excalidraw
/path/to/project/diagrams/order-pipeline.svg
/path/to/project/diagrams/order-pipeline.png

An image block

The PNG itself, base64 encoded with mimeType image/png. It is the same file as the .png on disk, so the agent can look at the diagram without a separate read and call again if a label collides or the flow reads backwards.

Structured content

The same paths as fields, plus the PNG's size, matching the tool's output schema:

{
  "excalidraw": "/path/to/project/diagrams/order-pipeline.excalidraw",
  "svg": "/path/to/project/diagrams/order-pipeline.svg",
  "png": "/path/to/project/diagrams/order-pipeline.png",
  "pixels": { "width": 2498, "height": 1059 }
}

A very wide pixels.width usually means a long label stretched the layout.

Errors

A spec that fails validation does not throw a protocol error. The result has isError: true and one text block with every problem on its own line, the same lines excalix validate prints:

nodes[0].kind: got "gateway", expected one of "client", "service", "datastore", "queue", "cache", "external"
edges[0].to: unknown node "apy", did you mean "api"?

Anything else that goes wrong while drawing comes back the same way, as a single line starting error:. The one most people meet first:

error: Chromium is not installed. Run: npx -y playwright@1.63.0 install chromium

After an error of that kind the server closes its browser and opens a fresh one on the next call. A call to any tool name other than sketch gets a protocol error instead.

Large diagrams

When the longest side of the PNG passes 6000 pixels, the text block gains a fourth line after the paths:

note: 9578x2101 px, too big to read once it is scaled down. Split it into an overview and a detail diagram, or shorten the longest labels.

Past that size the copy of the image a model sees is scaled down far enough that thin lines and small labels go missing. The usual answer is two diagrams: an overview that collapses each region to one node, and a detail diagram of the part under discussion.