Croqui.dev docs

Croqui.dev is a collaborative design canvas where AI agents write real React screens. This page covers connecting an MCP client, the tools an agent gets, and the concepts behind the canvas. New here? Start with what Croqui.dev is.

On this page

Connect an agent over MCP
Give the agent a role
Tool surface
Build contract
Canvas concepts
The review and delivery loop
Limits and billing

Connect an agent over MCP

Croqui.dev exposes one MCP server at https://croqui.dev/mcp. It speaks the HTTP transport and authorizes over OAuth: any active account can use it. Register it once and the agent gets your canvas, your screens and your notes as tools. There is no per-call quota — connect as many agents as you want.

Claude Code

Recommended: the Croqui.dev plugin. It installs the MCP server plus the agent skills (croqui-canvas, croqui-notes, croqui-import, croqui-sync). Source: github.com/croqui-dev/croqui-mcp. Run this in the terminal:

claude plugin marketplace add croqui-dev/croqui-mcp
claude plugin install croqui@croqui

Then open Claude Code, run /mcp, choose croqui and pick Authenticate. A browser window opens for you to authorize; approve it and go back to the terminal.

MCP server only, without the skills: run this inside any project, then authorize the same way.

claude mcp add --transport http croqui https://croqui.dev/mcp

Codex

codex mcp add croqui --url https://croqui.dev/mcp
codex mcp list

codex mcp list confirms the server is registered. Authorization happens in the browser the first time a tool is called.

Cursor, Grok and any other MCP client

Add the server to the client's MCP configuration file:

{
  "mcpServers": {
    "croqui": {
      "url": "https://croqui.dev/mcp"
    }
  }
}

Anything that speaks MCP works: Cursor in agent mode, Grok through xAI tools, a terminal agent you wrote yourself. They all draw on the same stage, read the same notes and ship the same files.

Give the agent a role

With the plugin, start Claude Code with the role in CROQUI_AGENT_ROLE. The value goes into the server URL as is, so URL-encode it (a space is %20):

CROQUI_AGENT_ROLE=Designer claude

With the MCP server only, append ?as= to the server URL to declare the name the agent shows up as on the canvas:

claude mcp add --transport http croqui "https://croqui.dev/mcp?as=Designer"

The role becomes the agent's label and colour next to the presence cursors, so a team running several agents can tell the copywriter from the designer at a glance. The team can rename or recolour it later from the canvas.

Tool surface

Once connected, the agent has these tools:

Tool	What it does
`croqui_list_projects`	List the projects the caller can see.
`croqui_create_project`	Create a project.
`croqui_delete_project`	Permanently delete a project; team owners and admins only, with the project id repeated as confirmation.
`croqui_open`	Open a project and focus the canvas on it.
`croqui_context`	Return the project brief, conventions and current state.
`croqui_list_files`	List the screens, components and references in a project.
`croqui_read_file`	Read one file.
`croqui_write_file`	Create or overwrite a screen or component.
`croqui_edit_file`	Replace one snippet in a file — one region per call while building.
`croqui_delete_file`	Delete a file.
`croqui_search`	Search across the project's files.
`croqui_ds_reference`	Return the build contract, the screen format, the project's components and the design system reference the screens must compose.
`croqui_screenshot`	Render a screen on the server, desktop or mobile, and return the image.
`croqui_read_annotations`	Read the human pins and notes on a frame.
`croqui_resolve_annotation`	Close an annotation once it is addressed.
`croqui_import_design`	Import an existing design into the project.

A well-behaved agent calls croqui_context and croqui_ds_reference before writing anything: that is the difference between a screen that could belong to any company and a screen that belongs to yours.

Build contract

Every connected agent receives the same rules for building a screen, through the MCP instructions, the write tools and croqui_ds_reference:

Structure first. The screen is laid out in document flow with flex or grid. Absolute positioning is only for things that float over the flow (badges, floating buttons, decorative art), never to place a whole screen element by element — not even when copying a screenshot.
Components before screens. Reuse in this order: the design system, then the project's components/, and only then create. Anything that repeats, across screens or inside one screen (list rows, cards, tabs, nav items, tiles, chips), becomes components/<Name>.tsx rendered from mock data.
Build live, in cycles. A skeleton write with the layout regions first, then one region at a time, top to bottom, each wired into the screen with croqui_edit_file as soon as its component exists, then states, interactions and Present wiring. The team watches the agent assemble the screen on the canvas instead of receiving it in one write.
Interactive by default. Anything clickable is a real <button> or <a> with pointer, hover, active and focus styles. Tabs, toggles, accordions and steppers work with local state; carousels scroll; inputs accept typing.
Wire Present. Elements that lead somewhere carry navigation attributes (below). Agents link only to screens and frames that exist and report the flows they left inert.
Copying a reference image. The agent reads the structure and rebuilds it with these rules, taking colors, type scale, radii and spacing from the image. It never slices the image into sprites and never measures pixels to place elements. Photos, logos and illustrations become neutral placeholders unless you provide the asset.
The canvas is the workspace. Agents don't render screens locally, keep local copies or upload drafts at the end: every step lands on the canvas.
Verify cheaply. The compile result of each write is the per-step check, and one croqui_screenshot after the last pass; then a report of files written, components created or reused, what is wired in Present and what is a placeholder.

Present navigation attributes

In Present, a click on an element with one of these attributes navigates. Outside Present they do nothing, and the element's own click handler always runs.

Attribute	Value	In Present
`data-croqui-goto`	Screen path, e.g. `screens/checkout/payment.tsx`	Go to that screen.
`data-croqui-open`	Export name listed in the screen's `meta.frames`	Show that drawer, modal or sheet over the screen.
`data-croqui-close`	—	Close the open frame.
`data-croqui-back`	—	Go back to the previous screen.

Canvas concepts

Project

A project holds screens, components and reference material. Desktop and mobile viewports share the same project, so the same design system covers both.

Screen

Each frame on the canvas is a React file under screens/. It renders live on the stage; it is not a picture of a screen. Every screen keeps a file history, so a bad edit rolls back without leaving the canvas.

Component

Components are the pieces of this product's design system. Agents compose them instead of regenerating a button on every prompt — that is what keeps twenty generated screens looking like one product.

Annotation

A pin on a frame, with a note and optional reference images. Humans mark what is wrong; agents read the pins through croqui_read_annotations and close them with croqui_resolve_annotation.

Bundle

A project exports as a product bundle so another surface can run the same screens.

The review and delivery loop

An agent writes or edits a screen. A badge on the canvas shows which frame it is touching.
The team and the client annotate the frame with pins.
The agent reads the pins and resolves them.
A human approves the screen.
Automatic delivery hands the approved screen to the agents that implement it in the real product.
Those agents compare their implementation against the approved design and publish it.

The approval step is the point of the product: nothing reaches production because an agent decided it was finished.

Limits and billing

MCP calls are unlimited on every plan, including Free. What the plans change is seats, projects, screens and the team features — shared presence, client viewers, automatic delivery, SSO, audit log and custom domains. See pricing for the current plans; billing runs on Stripe, in USD, cancellable anytime.