Content
# Visily MCP
The Visily MCP server brings your Visily designs into your AI coding agent. Point it at a
Visily board or screen and your agent can find it, turn it into application code, or pull its
theme tokens — using your Visily design system as the source of truth.
> [!NOTE]
> **Access requirement.** The Visily MCP works only on workspaces on a **Pro or Business**
> plan where you are the workspace creator or have an **editor** license. Free workspaces and
> viewer/guest roles are not supported. This is enforced on every request.
## What you can do
- **Turn a Visily design into code.** Generate production-ready code from a Visily screen or
board — whether the UI was AI-generated in Visily or hand-authored. The agent rebuilds
semantic, responsive components (default stack: React + TypeScript + Tailwind v4 +
shadcn/ui) instead of pasting a static export.
- **Find a board or screen and get its link.** Ask for a design by description
(*"the board I was working on for the 4.6 release"*) and the agent returns a link to open
it — without leaving your editor.
- **Apply a board's theme.** Pull a board's design system as shadcn/Tailwind v4 tokens and
apply it to another app's styling.
## Install & connect
Authentication is **OAuth** — your client prompts you to sign in to Visily on first use.
There are no API keys to manage.
The current Visily MCP server URL is:
```
https://app.visily.ai/api/mcp
```
Each platform's drop-in files live under [`plugins/<platform>/`](plugins/).
### Claude Code
```bash
claude plugin marketplace add visily-app/mcp-plugins
claude plugin install visily@visily
```
Then reload Claude Code and run `/mcp` → select `visily` → complete the OAuth sign-in. Full
walkthrough: [`installation-guides/claude.md`](installation-guides/claude.md).
### Cursor
Cursor 2.5+ packaged plugin — install from a local clone in the agent chat:
```
/add-plugin ./plugins/cursor
```
Reload Cursor; the MCP server appears under **Settings → MCP** (OAuth on first use) and the
Visily skill loads automatically. Details: [`plugins/cursor/README.md`](plugins/cursor/README.md).
### Codex
```bash
codex plugin marketplace add visily-app/mcp-plugins
codex plugin add visily@visily
```
Authorize via OAuth on first use. Full walkthrough:
[`installation-guides/codex.md`](installation-guides/codex.md).
### ChatGPT
ChatGPT connects to remote MCP servers via **Developer Mode** custom connectors (Plus, Pro,
Business, or Enterprise). Enable **Settings → Connectors → Advanced → Developer mode**, add a
custom connector pointing at the server URL above, and complete OAuth. Then paste
[`plugins/chatgpt/AGENTS.md`](plugins/chatgpt/AGENTS.md) into a Project/GPT's instructions.
Steps: [`plugins/chatgpt/SETUP.md`](plugins/chatgpt/SETUP.md).
### Antigravity
Copy [`plugins/antigravity/.agents/`](plugins/antigravity) into your project root and merge
[`plugins/antigravity/mcp_config.json`](plugins/antigravity/mcp_config.json) into your global
MCP config. Details: [`installation-guides/antigravity.md`](installation-guides/antigravity.md).
### Kiro
Copy [`plugins/kiro/`](plugins/kiro) into your Kiro powers directory (it contains `POWER.md`,
per-intent `steering/` workflows, and `mcp.json`). Merge `mcp.json` into your Kiro MCP config
and authorize via OAuth. The Power activates on Visily URLs and find/build/theme intents.
### Lovable
Commit [`plugins/lovable/AGENTS.md`](plugins/lovable/AGENTS.md) to your repo root and add the
Visily MCP connector in the Lovable UI. Details:
[`plugins/lovable/SETUP.md`](plugins/lovable/SETUP.md).
### v0 (Vercel)
[v0](https://v0.app) supports custom MCP servers natively. Add the server URL above via
**Settings → MCP Connections** (or **Add MCP** in the prompt form) and authorize via OAuth,
then commit [`plugins/v0/AGENTS.md`](plugins/v0/AGENTS.md) to your repo root. Details:
[`plugins/v0/SETUP.md`](plugins/v0/SETUP.md).
### Other editors (Streamable HTTP)
Any client that supports Streamable-HTTP MCP can connect with this config:
```json
{
"mcpServers": {
"visily": {
"url": "https://app.visily.ai/api/mcp"
}
}
}
```
This covers VS Code (Copilot), Windsurf, Cline, Gemini CLI, and similar tools. Check your
client's docs for where MCP server config lives; OAuth runs on first use.
> [!NOTE]
> **Google AI Studio** does not natively support MCP connectors yet (it only works through
> third-party browser bridges, which we don't recommend). For a Google-native option, use
> **Firebase Studio**, which supports MCP servers via `.idx/mcp.json` — drop the same `url`
> config there. We'll add a first-class recipe when AI Studio ships native MCP support.
## Prompting your agent
Give the agent a Visily link and a clear intent. The agent extracts the IDs from the URL —
it doesn't open the page.
**Examples**
- "Find the Visily board I was working on for the 4.6 release and give me the link."
- "Build this Visily screen as React + Tailwind: `https://app.visily.ai/projects/abc/boards/456/elements/789`"
- "Implement this board in Next.js, reusing my `src/components/ui` components."
- "Apply my Visily board theme to this app's `globals.css`."
A Visily URL looks like:
```
https://app.visily.ai/projects/{projectId}/boards/{boardId}/elements/{elementId}
```
## Structure your Visily file for better code
The more intent your design carries, the better the generated code:
- **Name your screens and key groups semantically** in Visily — names flow into the export
and into the link-matching for "find my board."
- **Lean on Visily's theme / design system** so the agent can apply real tokens instead of
guessing colors and radii.
- **Ask for one screen at a time** for large boards — smaller selections produce more
reliable results.
## Tools
| Tool | Use |
|---|---|
| `get_design_context` | **Primary.** Returns `designData` + theme + screenshot metadata for one element. |
| `get_screenshot` | Fetch a screenshot for visual verification. |
| `get_board_theme` | Board design system as shadcn tokens (`JSON` / `CSS` / `Tailwind`). |
| `list_workspaces`, `list_projects`, `list_boards`, `list_elements` | Discovery / find-a-board. |
| `get_workspace`, `get_project`, `get_board`, `get_element`, `get_element_export` | Advanced — metadata and raw exports rarely needed for the three use cases; prefer the tools above. |
The server also ships **prompts** (e.g. `find_visily_board`, `generate_code_from_element`,
`apply_board_theme`) and **resources** (`visily://docs/...`) that your agent reads on demand.
## Custom rules (optional)
Set project-level guidance so output stays consistent — like onboarding notes for a new
teammate.
**Cursor** (`.cursor/rules/visily-quality.mdc`):
```yaml
---
description: Visily code-generation rules
alwaysApply: false
---
- Treat Visily `designData` as a reference, not final code — rebuild semantically.
- Apply the Visily `theme` tokens; never hardcode hex, radii, or spacing.
- Reuse existing components in `src/components/ui` instead of duplicating.
- Verify against `get_screenshot` for 1:1 layout before finishing.
```
**Claude Code** (`CLAUDE.md`):
```markdown
## Visily MCP rules
- Treat Visily `designData` as a reference, not final code — rebuild semantically.
- Apply the Visily `theme` tokens; never hardcode hex, radii, or spacing.
- Reuse existing components instead of duplicating; verify with `get_screenshot`.
```
## How this repo is built
`plugins/` is generated from a single shared source (`shared/`) by `scripts/build.mjs`. To
change the integration, edit `shared/` and run `npm run build` — never edit `plugins/` by
hand. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
