Use Design Artifacts with Your Coding Agent
Create an app, dashboard, or set of pages as a Design in Drive → Design Artifacts, then hand it to your coding agent to build. Claude Code, Codex, OpenCode, and Cursor connect to Copera MCP Cloud and read the Design with get_artifact_handoff. API paths and MCP tool names use artifact.
What your agent receives
get_artifact_handoff returns the whole Design in one read:
| Part | What it contains |
|---|---|
| Spec | The Design's Spec — what it is for, who uses it, and how it should behave. |
| Notes | The notes people pinned to pages or to the Spec. |
| Design | The shared design: guidance, tokens, and components files, plus logos, fonts, and images with short-lived download links. |
| shadcn/ui setup | Only for designs built on shadcn/ui: your preset, the shadcn CLI commands that recreate it, and the components each page uses. See Designs built with shadcn/ui. |
| Pages | Every page with its surface, viewport size, entry file, and the files it loads. |
| Links | How the pages link to each other (the flows between screens). |
| Source files | The Design's source, with file contents included. |
Set it up
Coding agents that run on your computer connect with a Personal Access Token. In Copera, open Workspace Settings → Integrations, create a Personal Access Token, and give it Drive access (the access_drive scope). Copy the token (cp_pat_…) — treat it like a password. See Authentication for details.
Replace <YOUR_TOKEN> with your token. These are the same lines Copera shows in a design's Export → Build it with your coding agent menu.
- Claude Code
- Codex
- OpenCode
- Cursor
Run in your terminal:
claude mcp add --transport http copera https://mcp.copera.ai/mcp --header "Authorization: Bearer <YOUR_TOKEN>"
Add to ~/.codex/config.toml:
[mcp_servers.copera]
url = "https://mcp.copera.ai/mcp"
bearer_token_env_var = "COPERA_TOKEN"
Then make the token available to Codex:
export COPERA_TOKEN="<YOUR_TOKEN>"
Save this as opencode.json in your project. If the file already exists, add the copera entry inside its mcp object instead:
{
"mcp": {
"copera": {
"type": "remote",
"url": "https://mcp.copera.ai/mcp",
"headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
}
}
}
Save this as .cursor/mcp.json in your project. If the file already exists, add the copera entry inside its mcpServers object instead:
{
"mcpServers": {
"copera": {
"url": "https://mcp.copera.ai/mcp",
"headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
}
}
}
Restart or reload the agent so it picks up the copera server.
Copy the prompt from the same Export menu and send it to your agent:
Build the <design name> Design from Copera
Add anything about your stack, for example "as a Next.js app with Tailwind". The agent finds the Design with list_artifacts, calls get_artifact_handoff, and builds from the result.
How the agent builds
get_artifact_handoff tells the agent what to do next, in this order:
- Read the Spec — the intent, the people who use it, and the rules.
- Read the notes — feedback and decisions pinned to pages.
- Set up the design — tokens, components, fonts, logos, and images first, so every page shares them.
- Build each page from its files, at its surface and viewport size.
- Wire the links between pages so the flows work.
By default the agent gets the latest version of the Design that built successfully. To build a specific version, pass its versionId (find it with list_artifact_versions).
To keep tool results small, file contents are included up to 32 KiB by default. Larger files come back marked omitted: "over_budget", and the agent reads them with read_artifact_source. If your client accepts large tool results, the agent can raise maxInlineBytes (up to 1 MiB).
opencode.json and .cursor/mcp.json often live inside a project. If you paste your token there, do not commit the file. Rotate the token in Workspace Settings → Integrations if it ever leaks.
Designs built with shadcn/ui
When a Design's shared design is your shadcn/ui setup — the library, style, colors, fonts, icons, radius, and menu you picked on ui.shadcn.com/create — its pages use the real shadcn/ui components, written exactly as they would be in your own app (import { Button } from "@/components/ui/button"). The hand-off then adds a shadcn block, so your agent sets up your project with the shadcn CLI instead of copying component files.
In the shadcn block | What it gives the agent |
|---|---|
summary, library, style, baseColor, theme, iconLibrary, font, fontHeading, radius, … | Every choice of your setup, plus the preset code (presetCode). |
newProjectCommand, existingProjectCommand | npx shadcn@<version> init --preset <code> --base <library> --template vite --name <project> --yes for a new app, and npx shadcn@<version> apply --preset <code> --yes to run inside an app that already uses shadcn/ui. The new-project command names the project (after the Design) and skips the prompts: without --name the CLI asks "What is your project named?" and, with no terminal to answer, ends having created nothing. For Next.js, use --template next. The commands pin a shadcn release (never latest). A command Copera could not build safely is null, and nextSteps says so. |
projectDirectory | The sub-folder newProjectCommand creates (its --name). The CLI creates it inside the folder it runs in, so the agent runs cd <projectDirectory> and every later command runs there. |
addCommand | npx shadcn@<version> add … for exactly the components the design uses, including any hook the design keeps. |
registry | Which shadcn snapshot the design's components were installed from (snapshot) and the CLI release the commands pin (cli). |
customizedFiles, unknownFiles | The shadcn/ui files that come in full in files because the CLI would not write them as they are (see below). |
globalsCss, componentsJson | The design's real globals.css (colors, radius, fonts — including custom colors a preset code doesn't carry) and the components.json for your setup. globalsCss is the same text as shared/tokens.css, so that file comes back marked omitted: "in_shadcn_block". |
customTokens | The colors and radius you customized in Copera, token by token (light, dark, radius). Neither a preset code nor existingProjectCommand carries them (globalsCss has them all): an agent that keeps its app's own stylesheet adds just these. |
viteInputsSnippet | The build.rollupOptions.input of a Vite app without a router, with every page's HTML entry (null with a single page). Without it only index.html is built. |
dependencies, dependenciesNote | The npm packages the design is built with, with versions. The CLI installs current versions in a real app, so yours may differ: that is expected. |
pages[].suggestedRoute, pages[].components, pages[].htmlEntry, pages[].entryFile | Each Copera page is one screen: the route to mount it at in your router (/ for the default page), the shadcn/ui components it uses (directly or through other components), its HTML file (htmlEntry) and the module that file loads to mount the page (entryFile, with shared/ as src/). Every entryFile starts with import "./index.css". |
pathMapping | shared/ → src/. The @/ alias is the same in Copera and in your app, so imports don't change. |
To keep the result small, shadcn/ui components nobody changed in Copera are not included: they come back marked omitted: "shadcn_registry", because shadcn add writes them. (shadcn add always writes the current shadcn release, so a component your app gets can differ a little from the preview; the pages are built against the same names, variants and props.) Two kinds of component do come in full, each with a note:
- Components you customized in Copera:
customized after shadcn add — keep these changes. They are listed incustomizedFiles. - Components Copera has no record of writing (a design created before Copera kept those records) that differ from what
shadcn addwrites today:differs from what shadcn add writes today — use this file as it is. They are listed inunknownFiles.
Copy both over what the CLI wrote. If the size budget keeps one of them out of files, nextSteps names it and tells your agent to read it with read_artifact_source instead of assuming it is included.
The agent follows this order (the nextSteps of the pack number them 3a to 4e):
- New app: in an empty folder, run the
newProjectCommand(it installs your library, icon set, and fonts), thencdinto theprojectDirectory: every later command runs there. App that already uses shadcn/ui: run theexistingProjectCommandinside it. It applies the preset only, not your custom colors:customTokenslists them. - Run the
addCommandinside the project. - Make the design's stylesheet the app's: in a new app replace
src/index.csswithglobalsCss; in an existing app merge its:root,.darkand@themeblocks into the app's own global stylesheet and keep the app's other rules. A page's<link href="./shared/tokens.css">is not copied. Install any package fromdependenciesthat is still missing. - Copy the customized components over what the CLI wrote.
- Port each page, mapping
shared/tosrc/. Every page'sentryFilestarts withimport "./index.css": a Vite entry loads the stylesheet by import, and an entry without it builds without an error and renders unstyled. If the app has a router, mount each page's component at itssuggestedRoute. With no router (a fresh Vite template), keep each page'shtmlEntryas its own HTML file and list them all invite.configwith theviteInputsSnippet(otherwise onlyindex.htmlis built), keep the template's ownindex.htmlhead (favicon, fonts, meta) and set each page's<title>to the page's own title (the template'svite-apptitle stays otherwise), copy only the page's body and mount into it, and delete the template's unusedsrc/App.tsxandsrc/main.tsxif nothing imports them. Keep the component names, variants, props, and token classes exactly — no restyling, and no swapping shadcn/ui components for others. - The pages were built without type-checking, so fix unused imports and type errors while porting: the Vite template runs
tsc -bwithnoUnusedLocals, and the CLI installs current package versions, so types such asreact-day-picker's can differ from the preview's.
If the size budget kept files out of the pack (omitted: "over_budget"), the first line of nextSteps says how many and tells your agent to read them with read_artifact_source before porting the pages they belong to.
Copera's own scaffold from the draft a Design starts as (draft.css, draft.js, scaffold/…, and for a shadcn/ui design src/main.tsx and src/device-frame.tsx) is left out of the pack unless a page loads it.
A prompt that works well:
Build the "CRM" Design from Copera as a Vite app. Set up shadcn/ui with the commands in the hand-off's shadcn block, then port each page 1:1: same components, variants, and tokens, no restyling.
Start a design with your own setup from your agent
Your agent can also create a design from your shadcn/ui setup. Paste what shadcn gave you — a preset code, an npx shadcn@latest init --preset … command, a ui.shadcn.com link, theme CSS, or a components.json — and check it first with parse_shadcn_setup. It returns the setup it understood, what it recognized, and anything it could not apply (for example, a preset code never says whether your project uses Radix UI, Base UI, or React Aria, so you may need to add --base radix). Then call create_artifact with designStarterId: "shadcn" and one of:
shadcnSetup— the text you pasted;shadcn— the setup object returned byparse_shadcn_setup;designSystemId— a design system your workspace saved (list them withlist_artifact_design_systems).
The result of create_artifact includes a shadcn field that shows which setup was applied and any warnings. The project you send must be vite_react.
Troubleshooting
| Symptom | Likely cause |
|---|---|
401 Unauthorized | The token is missing, mistyped, or expired. Check the Authorization: Bearer … value. |
403 Forbidden on a Design Artifacts tool | The token lacks Drive access (access_drive), or Design Artifacts isn't available in your workspace. |
| The Design isn't found | The token's user can't open that Design. Ask its owner to share it with you. |
| The agent asks you to sign in | It's trying to connect without your token. Re-check the setup line from step 2. |
Related
- Tool reference — Design Artifacts — every tool for Design Artifacts and its inputs.
- Connect an MCP client — endpoint details and testing with the MCP Inspector.
- Design Artifacts in Drive — create, upload, share, and reuse designs in Copera.