Centina MCP server

Quick start

In the desktop app: open a canvas, click Agent (top-right, beside Share), then Copy for agent. Paste that into any agent that already has Centina, and it paints on the page you are looking at. The one-time setup is in Centina desktop.

From a terminal: start the editor, then register the MCP command with your client (Claude Code shown):

1centina serve
2claude mcp add centina -- centina mcp

If serve uses --port, add the same --port to the mcp command. Any running Centina hands you its canvas from the Agent capsule; paste that reference into the agent to point it here.

The full setup — absolute paths, JSON client config, LAN sharing, firewall notes — is in the setup and self-hosting playbook.

The window connects to the bridge automatically within ~2.5 s. Open several windows at one address and the newest one wins — older ones go quiet. Then just talk to the agent: "what's on my canvas?", "build me a pricing section", "make this dark mode".

How it works

MCP client ⇄ stdio ⇄ centina mcp ⇄ WebSocket ⇄ bridge (centina serve) ⇄ the open Centina window

The serving process hosts the bridge, so a Centina window — a browser tab, or the desktop app — is reachable by agents whenever its server runs; centina mcp is a stateless client the MCP client launches. Any number of agent sessions can share one window concurrently — the bridge fans their requests in; windows still follow newest-window-wins. If the server runs but no window is connected, every tool fails fast with No Centina window is open at http://localhost:<port> (in the desktop app: The Centina desktop app has no canvas window open at http://localhost:8462); if the server itself is down, with Centina isn't running at http://localhost:<port>. ping and get_canvas_info report the instance, url, and app (desktop or browser) the agent reached, so it can say where it is. With no --port, centina mcp reaches a running centina serve (3000) or the desktop app (8462), preferring the one with a window open.

Instances are identified by their app URL. Canvases autosave in the browser's IndexedDB, which is per-origin — localhost:3000 and localhost:4500 are different libraries. Node refs therefore carry their origin (localhost:3000#ab12), and every tool routes each call to the instance its ids name; bare ids target the default instance. Tools that can run without any id (ping, get_canvas_info, get_selection, get_tree_summary, create_box, write_html, finish_working_on_nodes) take an optional instance param (localhost:3000, or a whole pasted canvas reference) for the same routing; page accepts a canvas reference too and draws on the page it names. One call targets one instance — mixing origins in a single call is an error. The bridge always listens at the web port + 701 (see ports and firewalls).

Concepts

• Everything is a box. Container nodes are boxes (what other tools call frames); the other node types are text and image. Tools say "node" when any type works and "box" only for container concepts.
• A canvas reference hands an agent the page you are on. Copy for agent in the Agent capsule (top-right, beside Share), ⇧⌘C with nothing selected, or right-click on empty canvas → Copy canvas for agent, puts this on the clipboard: [Centina localhost:8462#p1a2b3 “Untitled” · canvas · page “Page 1” — use centina MCP tools here: pass this token as instance, or as page to draw on this page]. Paste it into the chat: the agent passes it as instance (any id-less tool) or as page (write_html, create_box) and its work lands there, even after you move to another page.
• Node ids address everything. Get them from any read tool, or from the human: Copy for agent (right-click any node, ⇧⌘C, or the button at the bottom of the inspector) puts a self-describing reference on their clipboard — [Centina localhost:3000#ab12 "Hero" · box · 960×540 — use centina MCP tools with this id] — so a paste into any agent chat carries the id, the instance it lives in, and how to resolve it, no per-project setup needed. Every tool accepts the qualified token verbatim and routes to that instance. The context menu's Copy ID copies the bare id(s) for prompts that already have context. Id inputs accept the display form with a leading #.
• Every write is one undo step. A whole write_html import, a 12-node update_styles batch — each tool call reverts with a single ⌘Z. Validation is atomic: if any entry in a batch is invalid, nothing applies and the error names every offending path.
• Measured truth. layout.width/height values are stale for fit/fill sizing — the browser decides those. Read worldRect (from the live DOM) when you need actual geometry; it's null for hidden nodes.
• Style writes speak the model schema, not CSS. update_styles takes fills, radius, layout.width: {mode}, … — not CSS property names. The rawCss group is the escape hatch for arbitrary CSS (it applies last, so rendering stays faithful). It merges per declaration: {prop: "value"} sets one key (validated by the rendering browser's CSS.supports; custom --* properties exempt), {prop: null} removes it, null clears the whole map, untouched keys stay. disabledCss takes the same shape for declarations kept but toggled off; setting a key in either map removes it from the other. Read both back via get_node_info's style field — the same maps the panel's "Other styles" section edits.
• Presence. Nodes an agent touches show a shimmering "Crafting…" overlay — ephemeral, never in the document or history. The overlay draws only on the page the human is viewing; work on another page shows as a pulsing dot on that page's row in the folios panel, whose tooltip names the session. The Agent panel's roster lists, per session, the pages it has written (a live dot while the shimmer is on one; each name is a link to that page). Its lifetime is the agent session, not write recency: every tool call (reads and screenshots included) keeps it alive, so a half-built design never reads as finished while the agent thinks between writes. It clears on finish_working_on_nodes, instantly when the last agent session disconnects (the hub pushes agent head-counts to the tab), or via a 120 s idle backstop for agents that stay connected but silently move on. The human can also end it: the editor's Home button, pressed while the shimmer is live, confirms and then ends every agent session — the hub fails in-flight calls with "The human ended this agent session from the editor." and closes agent sockets (code 4002). A session ended this way reconnects on its next request; treat the error as "stop this task", not "the bridge is broken".
• Pages are no boundary. Ids resolve across every page of the document: reads mix pages freely (nodes not on the human's page carry a page: {id, name, active: false} field), and writes work on any page — the human's canvas stays wherever they are, and the folios panel marks pages being crafted with a shimmer + pulsing dot (the panel-side face of the canvas shimmer). Constraints that keep this sane: one write call edits one page (ids that span pages are an atomic error; each call is one entry in that page's own undo history), the id-less creators (create_box, write_html, get_tree_summary) take a page param (id or unambiguous name), and select_nodes {reveal: true} is the only call that switches the human's page — background-page geometry is still measured truth (a hidden, unpainted stage mounts those pages in the live tab), and background-page screenshots render through the headless fallback automatically.
• Contexts relate by membership. A context is a freeform-labeled group (canvas-wide, cross-page); elements that share one are thereby related — there is no directed edge, the shared membership IS the relationship. The driving use: a wiremap card and the hi-fi mock that realizes it share a context, so get_node_info on either lists the other under contexts with its page — read a node's contexts before editing it to find its siblings and intent. Join and leave with set_contexts (labels mint on first use, like tags); get_canvas_info.contextGroups is the full table.
• The human is watching. Every tool call paints in the live tab immediately, so an agent session is a performance by default: new canvas-root content lands beside the human's context — their selection if they have one, else whatever the agent last touched, else what's on camera — at the next slot in the row, and never on top of an existing root (see "Placement" below). Big builds should go shell-first then section-by-section (write_html with targetId — each call one undo step), and select_nodes {reveal: true} pans the camera to finished work. The server ships these habits as MCP instructions at initialize, so any connecting agent gets the workflow without per-project setup.
• Round trips are the only slow part. A tool call takes about a millisecond; the turn of model thinking wrapped around it takes seconds. So the cost of a session is the number of round trips, not the number of calls — which is what [batch](#batch--several-calls-one-round-trip) is for. Build and look in one trip, refine and verify in one trip, present in one trip.

Placement

Canvas roots are whole screens, so two of them overlapping is always a mistake. Creation tools (write_html, create_box) place new roots against the measured size of what they just built:

1. Never on top of existing work. The whole footprint has to be clear, not just the drop point — a page-sized import lands beside your screens, never across them.
2. Beside the reference. The anchor is your selection, else the root the agent last worked on, else the root nearest the middle of your view. New work takes the slot to its right, top edges aligned. A row that has run out of room wraps to a new one below.
3. On camera when it can be. Free slots you can see are taken first; a screen too big for the viewport at least starts on screen. Clearing existing work wins over staying on camera when the two conflict.

Passing x/y states a preference, not a licence to overlap: a position that lands on an existing root is nudged clear and the result carries a placement note saying where it went and why. When you mean an exact position — parking something off to the side, staging a comparison — create the node and then move_nodes it: moves are exact by design.

batch — several calls, one round trip

batch takes a list of {tool, args} and runs them in order, in a single request:

{ "calls": [
    { "tool": "write_html",       "args": { "html": "<section style=\"…\">…</section>" } },
    { "tool": "get_screenshot",   "args": {} },        // no nodeId: captures the write above
    { "tool": "get_tree_summary", "args": {} }
] }

Batching changes nothing except how many turns the work takes. Each call keeps its own undo step (two batched writes are still two Cmd+Zs), its own atomicity, and its own behaviour. The reply carries ran, failed, and results in order; any screenshots arrive as image content after the JSON.

• The whole batch is validated before any of it runs — an unknown parameter in the fifth call rejects the batch without applying the first four.
• A call that fails at runtime (a ghost node id) stops the rest by default; the calls that already ran stand — each was its own undo step — and the skipped ones say so. Pass stopOnError: false to run them all.
• Ids must be known when you write the batch. Nothing substitutes ids created earlier in the same batch, so end with get_tree_summary and address the new ids on the next turn.
• Up to 20 calls; batch can't nest.

The shapes worth memorizing:

Tool reference

Parameter names are strict: a call with a param the tool doesn't declare is a tool error naming the bad key and listing the valid ones. (A typo'd parentId for targetId, silently dropped, once sprayed nine page sections across the human's canvas as top-level roots — never again.)

Orient & read

Pages & folios

Two book-level creation tools. They never move the human — their canvas stays on their page; pass the returned id as page to write_html / create_box / get_tree_summary, and select_nodes {reveal: true} once there is something to show. Page and folio creation sits outside the undo stream (exactly as the folios panel's own Add buttons do), so these are the two write tools that are not one ⌘Z.

Edit

All edit tools are batch, atomic, and exactly one undo step each.

Wiremaps & wireflows

Structure planning as data (the wiremaps and wireflows guides cover the editor side). One tool family, one map object — a forest: top-level cards are hand-placed ROOTS (their position is user truth; a wireflow is a map of free roots wired with interactions), and nested children opt into the managed tree with trunk lines. The rule that makes the surface small: cards and sections are real boxes — rename with set_text_content, recolor with update_styles, wire flows and transitions with add_connectors between section/card ids, reposition ROOT cards with move_nodes (x/y are container-relative for cards), read deeper with get_tree_summary. The dedicated tools cover only what the generic ones can't: cross-card structure, reflow-coupled inserts, and wireframe styles. Every write is one undo step — each tree re-lays under its root, then the settle hugs (the container fits the forest; hand-placed roots never move).

One call, one site:

1{ "tool": "create_sitemap", "args": { "name": "Marketing site", "cards": [{
2  "title": "Home",
3  "sections": [{"label": "Header"}, {"label": "Hero"}, "Footer"],
4  "children": [
5    { "title": "Pricing", "sections": ["Plans", "FAQ"] },
6    { "title": "About", "children": [{ "title": "Team" }] }
7  ]
8}]}}

…then apply_schematics on the hero, add_connectors from a CTA section to the Pricing card, and an id-less get_screenshot to look.

One call, one flow — the same tool, every card a hand-placed root:

1{ "tool": "create_sitemap", "args": { "name": "First run", "cards": [
2  { "title": "Splash", "sections": ["Logo"] },
3  { "title": "Onboarding", "sections": ["Carousel", "CTA"], "x": 400, "y": 40 },
4  { "title": "Sign in", "sections": ["Form"], "x": 400, "y": 320 }
5]}}

…then add_connectors for the transitions (card-to-card arrows route as gutter elbows automatically; anchor the CTA section's id for an element-level arrow), marks: {decision: true} on the splash arrow and a branch out of its diamond — from: {connectorId, decorationId, side: "bottom"} leaves through the diamond's bottom vertex — for the signed-out path.

Exporting a map with get_component (html) preserves its lines: wiremap trunk edges AND every interaction whose two ends live inside the exported subtree ship as inline <svg> — routes, colors, and labels intact.

Components

The reusable-design loop (the components guide covers the editor side). The rule that keeps this family small: instances are real subtrees — customize them with the ordinary tools (update_styles, set_text_content, move_nodes) and the edit self-records as a CUSTOMIZATION that survives updates; read the records back on get_node_info.component.overrides. The dedicated tools cover only what the generic ones can't: the library table, links, variant FACES, and the override craft.

The instance seal. Property edits are open anywhere inside an instance; STRUCTURE is not. Below an instance root, write_html, create_box, move_nodes (reparents and reorders — x/y-only moves are fine), delete_nodes, duplicate_nodes, and update_styles's layout.constraints all refuse, and the error names the sealing instance, the definition to edit instead, and the detach spell (update_instances {"updates": [{"id": …, "detach": true}]}). Restructure the definition and Bring instances into sync — or detach the one copy that needs to diverge. The instance ROOT itself is an ordinary layer: move it, delete it, duplicate it (that's how you stamp another copy). Faces are CSS-native — a face's NAME is its identity and compiles to a real selector (hover → :hover, size=lg → [data-size="lg"]), and each instance can show one (variant). Every write is one undo step (per page for book-wide instance sweeps).

Import & export — the web-standard loop

Generate HTML, write_html it, refine with update_styles/move_nodes, then hand back get_component when the human wants code — the default html round-trips: get_component output is valid write_html input. Imported designs reference images by their original URLs; run embed_images only when the human wants the document to outlive the source site.

Look

Live-tab path (exact pixels, fast). Used when the editor tab lives in a Chrome started with remote debugging on the instance's debug port — the web port + 6333, so 9333 for the default port 3000:

1open -a "Google Chrome" --args --remote-debugging-port=9333

Chrome 136+ blocks DevTools on the default profile, so a normally-launched browser never qualifies — that's what the fallback is for.

Headless fallback (any browser, ~2–4 s slower). When the live tab is unreachable over the debug port — or the node lives on a page the human isn't viewing (the live tab can't photograph the hidden measurement stage) — the server pulls the canvas through the bridge, re-renders it in a throwaway headless Chrome served by the same Centina process with that page active, and clips the same screenshot there. Same engine, same bundle, same fonts — and the human's session is untouched: a capture tab never dials the bridge (newest-tab-wins is not disturbed) and never reads or writes the autosave. The fallback needs headless Chrome available on the serving machine; the editor tab merely needs to exist in any browser.

Presence

Everything at once

Troubleshooting

• "Centina isn't running at http://localhost:…" — nothing answers at that address. Start it: centina serve (add --port if the reference names a non-default port), or open the Centina desktop app for 8462. centina mcp with no --port looks for both; pin one with centina mcp --port <port>.
• "No Centina window is open at http://localhost:…" (in the desktop app: "The Centina desktop app has no canvas window open") — the server runs but no window is attached to its bridge. Open the URL in a browser (the page only connects on localhost/127.0.0.1) or open the app; or you opened a newer window that took over and later closed it: reload the window you want.
• An agent asks for an "active tab" — it is paraphrasing the message above. Nothing needs setup: open (or reload) Centina at that address — a browser tab or the desktop window — and only the newest one carries the connection.
• "ids name N different Centina instances" — one call routes to one window; split the call per instance.
• "the … port is already in use" at centina serve startup — another Centina (or another app) owns the web or bridge port; stop it or pick another base port (centina serve --port 4500).
• Screenshots black or wrong region — the node was offscreen and the pan failed to settle; re-run. File it if it reproduces.
• Style writes rejected — update_styles speaks the model schema (fills, radius, layout.width: {mode} …), not CSS property names. Errors list every offending path; nothing was applied. The rawCss group is the escape hatch for arbitrary CSS — but its values are validated by the rendering browser (CSS.supports), so a declaration Chrome can't parse is rejected rather than silently rendering nothing (custom --* props exempt).