Connect an agent

The canvas and connected agents share one local daemon per design folder. That gives them one live state and one mutation path: an agent edit appears in the browser, and human feedback on the canvas is available to the agent.

Let Velloo write the configuration

velloo connect

The interactive flow detects installed agents, shows existing wiring, and offers global or project-only configuration. Without a terminal it wires Claude Code and Cursor at project scope.

Agent	Project	Global
Claude Code	claude-code	claude-code-global
Cursor	cursor	cursor-global
Codex CLI	codex	codex-global
Continue	continue	continue-global
opencode	opencode	opencode-global
Gemini CLI	gemini	gemini-global
VS Code / GitHub Copilot	vscode	None
Claude Desktop	None	claude-desktop
Droid	None	droid-global
Cline	None	cline-global
Windsurf	None	windsurf-global

Restart the agent after wiring it.

What it writes

Besides each agent’s MCP configuration, connect installs the guidance that agent reads:

• Claude Code: the Velloo plugin (skills, commands, and subagents) as a local marketplace at ~/.velloo/claude-plugins, registered and enabled in ~/.claude/settings.json. Only Velloo’s entries there are touched.
• opencode, Droid, Cline, Gemini CLI, and Codex: skill copies in the project’s .agents/skills/.
• Gemini CLI: also a Gemini extension at ~/.velloo/gemini-extension.
• Cursor: a project rule at .cursor/rules/velloo.mdc.

velloo upgrade refreshes whatever guidance is already installed; wiring something new stays velloo connect.

After connecting: set Velloo up for your app

Restart the agent, then ask it to set the design up for the app. The Claude Code and Gemini CLI plugins add a /velloo:setup command; in any other agent, say “set Velloo up for my app”. The agent matches your theme and fonts, checks that your components render, and proposes your design language for you to review on the canvas.

This is the first step after velloo init for any design that has an app to match, and the first task init gives your agent opens with it. What setup does →

Flags

velloo connect --agent claude-code-global,cursor-global
velloo connect --agent manual        # print a config for any other MCP client
velloo connect --http --mcp-url http://127.0.0.1:7301/mcp

• --agent takes comma-separated ids from the table above; manual prints the configuration instead of writing files.
• --project-root sets where project-scoped files go. The default is the nearest package.json above the design folder, otherwise its parent.
• --http wires the HTTP transport, where the agent dials a running server, instead of stdio. --mcp-url sets that URL.
• --no-skill writes only the MCP configuration and skips the plugin, skills, extension, and rule.

Manual stdio setup

Most MCP clients can spawn Velloo themselves:

{
  "mcpServers": {
    "velloo": { "command": "velloo", "args": ["mcp"] }
  }
}

Project-scoped configuration normally uses plain velloo mcp, so moving or renaming a design does not leave a stale path in the client. Velloo resolves a design from the working directory, application binding, the only associated design, or defaultDesign. You can still pin a deliberate name or path after mcp.

When a checkout has several designs, the session instructions identify the current one and the agent can call list_designs. A stdio session can call switch_design without restarting. If resolution is still ambiguous, Velloo opens the first design by name and tells the agent to confirm before changing anything. HTTP clients cannot switch in place; reconnect with velloo mcp --http <name> instead.

For a client that dials a URL, run velloo mcp --http. It starts or attaches to the daemon and prints the Streamable HTTP endpoint to put in that client’s configuration.

Guided by default

The default MCP surface is guided. It presents four compact tools:

• read_velloo invokes one native operation that only reads: the design, a render, a comparison, the code it emits.
• call_velloo invokes one native operation that changes the design.
• run_velloo_plan runs a deliberate sequence of operations.
• operation_schema returns the exact input schema for an operation.

read_velloo is annotated read-only, so you can let an agent read without being asked each time and still approve every change. In Claude Code, add the allow rule to your project’s .claude/settings.json:

{ "permissions": { "allow": ["mcp__velloo__read_velloo"] } }

The full catalogue still covers discovery, composition, focused edits, lifecycle, themes, visual verification, annotations, and code emission. Guided mode saves context by loading the operation contract when it is needed; it does not remove capabilities.

If a client performs better with conventional function schemas, use:

velloo mcp --surface full

Or set VELLOO_MCP_SURFACE=full in the environment that starts the MCP server. Both modes call the same operations against the same live state. The old progressive-disclosure and reveal_tools setup is no longer the current model.

Runtime guidance

At connection time Velloo adapts its instructions to the folder’s provider and styling channel. For a design that is bound to an app and has no boards yet, they also tell the agent to set the design up for that app first. It also exposes focused MCP guides at velloo://guide/*. Prefer those runtime resources and operation_schema over remembered argument shapes; they describe the build actually installed on the machine.

The arguments of the operations most sessions call are listed in the descriptions of read_velloo and call_velloo, so an agent rarely needs operation_schema for them. An argument name with only one possible reading, such as screen for screenId, is accepted and the result says how it was read.