Examples
Complete tool calls, with the response each one returns. Every request goes to POST https://api.vev.design/v2/mcp with your key, as described in Calling Tools over HTTP. The examples show only the params of each JSON-RPC message, and the response's structuredContent:
curl https://api.vev.design/v2/mcp \
--header "x-vev-key: [your-key]" \
--header "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params": PARAMS }'Keys and URLs in the responses are shortened examples.
Find a project
By search
{ "name": "find_projects", "arguments": { "search": "pricing page", "limit": 5 } }{
"projects": [
{
"key": "AbC123xyz45",
"title": "Acme pricing",
"description": "Plans and FAQ",
"published": true,
"publishedAt": 1779184000000,
"created": 1771000000000,
"updated": 1779270400000,
"account": "acme",
"thumbnailUrl": "https://api.vev.page/image/thumb/AbC123xyz45/Hk2Pq9",
"editorUrl": "https://editor.vev.design/edit/AbC123xyz45"
}
],
"notFound": []
}By URL
A published URL, an editor URL and an embed URL all work, so you can let your users paste any of them:
{ "name": "find_projects", "arguments": { "url": "https://www.acme.example/pricing" } }{ "name": "find_projects", "arguments": { "url": "https://editor.vev.design/edit/AbC123xyz45/Hk2Pq9" } }By key
{ "name": "find_projects", "arguments": { "ids": ["AbC123xyz45", "Zz9Yy8Xx7Ww"] } }Keys the user can't open are listed in notFound.
List a project's pages
get_project_sections exports every section by default. To get only the page list (for a page picker, say), ask for a section key that doesn't exist and turn off CSS and interactions:
{
"name": "get_project_sections",
"arguments": { "projectKey": "AbC123xyz45", "sectionKeys": ["-"], "includeCss": false, "includeInteractions": false }
}{
"project": { "key": "AbC123xyz45", "title": "Acme pricing", "account": "acme" },
"pages": [
{ "key": "Hk2Pq9", "title": "Home", "path": "", "isIndex": true, "sections": [] },
{ "key": "Lm4Rt7", "title": "Pricing", "path": "pricing", "isIndex": false, "sections": [] }
],
"globalSections": []
}Export a page section by section
Everything needed to rebuild a page's content in another system: screenshots, element trees, CSS, assets and interactions.
{ "name": "get_project_sections", "arguments": { "projectKey": "AbC123xyz45", "pageKey": "Lm4Rt7" } }At most 40 sections per call. For larger pages, pass sectionKeys in batches.
Export a section as HTML and CSS
One section
{ "name": "get_section_snippet", "arguments": { "projectKey": "AbC123xyz45", "sectionKey": "pRc8Ld2" } }{
"key": "pRc8Ld2",
"name": "Pricing table",
"html": "<section class=\"v-section\" data-vev-key=\"pRc8Ld2\"><div class=\"v-root vs-pRc8Ld2\">…<h2 class=\"v-el text v-pricing-title\">Simple pricing</h2>…</div></section>",
"css": "@import url(\"https://cdn.vev.design/css/snippet/9f2c….css\") layer(vev);\n.v-pricing-title{…}@container (max-width: 600px){…}",
"cssImages": { "--vev-img-3a1f": "https://cdn.vev.design/private/…/texture.webp" },
"widgets": [],
"delegated": [],
"script": "none",
"needsRuntime": false,
"tooLarge": { "html": false, "css": false },
"runtime": null,
"sharedCssUrl": "https://cdn.vev.design/css/snippet/9f2c….css"
}html and css are ready to paste: the CSS imports the project's shared stylesheet, which declares the --vev-img-* variables. When script isn't none, html ends with the one island script the section needs.
Several sections, or a whole page
{ "name": "get_section_snippet", "arguments": { "projectKey": "AbC123xyz45", "sectionKeys": ["hDr1", "pRc8Ld2", "fTr9"] } }{ "name": "get_section_snippet", "arguments": { "projectKey": "AbC123xyz45", "pageKey": "Lm4Rt7" } }{
"projectKey": "AbC123xyz45",
"pageKey": "Lm4Rt7",
"sharedCssUrl": "https://cdn.vev.design/css/snippet/9f2c….css",
"runtime": null,
"sections": [
{ "key": "hDr1", "placement": "header", "html": "…", "css": "…", "script": "none", "…": "…" },
{ "key": "pRc8Ld2", "placement": "content", "html": "…", "css": "…", "script": "none", "…": "…" }
],
"page": { "html": "<header>…</header>…<footer>…</footer>", "css": "@import url(…) layer(vev);…" }
}Use sections to store each section separately, or page to paste the whole page at once.
Detect changes made in Vev
For a given section, the export depends only on its content. But two parts of every export also change when the section didn't:
cssstarts with@import url(…)of the project's shared stylesheet. That stylesheet is named by a hash of its own content, which includes every section's CSS, the theme, the fonts and Vev's core CSS. Editing any other section, or a Vev release, gives it a new URL.- When
scriptisn'tnone,htmlends with an island that imports the runtime by Vev's viewer version (vev:interactions@…,vev:runtime@…) and the project's widget bundle by its hash (vev:bundle@…). These change with every Vev release and with any widget in the project.
Hash the export without those parts, and you can tell whether this section changed since you last fetched it, without storing the whole export:
import { createHash } from 'node:crypto';
function sectionHash(s: { html: string; css: string; cssImages: Record<string, string>; script: string }) {
const css = s.css.replace(/^@import url\([^)]*\) layer\(vev\);\s*/, ''); // the shared stylesheet
const html = s.html.replace(/vev:(runtime|interactions|bundle)@[\w.-]+/g, 'vev:$1'); // runtime versions
return createHash('sha256').update(JSON.stringify([html, css, s.cssImages, s.script])).digest('hex');
}
const current = await callVev('get_section_snippet', { projectKey, sectionKey });
if (sectionHash(current) !== stored.hash) {
// Changed in Vev: show "Vev has changes", or pull it in
}A change that only affects the shared stylesheet, such as a new theme colour or font, won't change this hash. When you pull a section, you get the current @import URL anyway, so your copy picks those changes up too.
The export reads the project as currently saved in the editor, not the last published version. Edits show up as soon as the designer makes them.
Import HTML into Vev
import_html_section recreates HTML as a native, editable Vev section on an existing page. It answers at once, and the import runs for 2–5 minutes.
A fragment with its CSS
{
"name": "import_html_section",
"arguments": {
"projectKey": "AbC123xyz45",
"pageKey": "Lm4Rt7",
"html": "<section class=\"cta\"><h2>Ready to start?</h2><p>Try it free for 14 days.</p><a class=\"btn\" href=\"/signup\">Start free trial</a></section>",
"css": ".cta{padding:96px 24px;text-align:center;background:#0b1020;color:#fff}.btn{display:inline-block;padding:14px 28px;border-radius:999px;background:#5b8cff;color:#fff}",
"name": "Call to action",
"position": 2
}
}A whole document, with relative assets
A Claude artifact, or a page rendered by your own app. baseUrl resolves relative image and font URLs:
{
"name": "import_html_section",
"arguments": {
"projectKey": "AbC123xyz45",
"pageKey": "Lm4Rt7",
"html": "<!doctype html><html><head><link rel=\"stylesheet\" href=\"/styles/site.css\"></head><body><section>…</section></body></html>",
"baseUrl": "https://app.acme.example/",
"name": "Testimonials"
}
}One part of a public page
{
"name": "import_html_section",
"arguments": {
"projectKey": "AbC123xyz45",
"pageKey": "Lm4Rt7",
"url": "https://www.acme.example/features",
"selector": "#customer-logos"
}
}The response is the same for all three:
{
"jobKey": "Qw3Er5Ty7Ui9",
"projectKey": "AbC123xyz45",
"pageKey": "Lm4Rt7",
"sectionKey": "nW5sec8Kp",
"status": "queued",
"editorUrl": "https://editor.vev.design/edit/AbC123xyz45/Lm4Rt7",
"message": "The section shows as pending in the editor and is filled in when the import finishes (usually 2–5 minutes). get_html_import with the jobKey reports progress and the result."
}sectionKey is the new section's key and never changes, so you can store it straight away, for example to export the section later.
Follow the import
{ "name": "get_html_import", "arguments": { "jobKey": "Qw3Er5Ty7Ui9" } }While it runs, step says what it is doing (capture, round 1, round 2, writing):
{ "jobKey": "Qw3Er5Ty7Ui9", "sectionKey": "nW5sec8Kp", "status": "running", "step": "round 2", "editorUrl": "…" }When it's done:
{
"jobKey": "Qw3Er5Ty7Ui9",
"projectKey": "AbC123xyz45",
"pageKey": "Lm4Rt7",
"sectionKey": "nW5sec8Kp",
"status": "done",
"step": "done",
"result": {
"score": 94,
"bestRound": 2,
"rounds": [
{ "round": 1, "score": 86, "fixes": ["Heading is 4px larger than the original", "Logos wrap to two rows at 375px"] },
{ "round": 2, "score": 94, "fixes": ["Button shadow is slightly softer"] }
],
"differences": ["Button shadow is slightly softer"],
"notes": ["The background video became a still of its first frame"],
"seconds": 148
},
"editorUrl": "https://editor.vev.design/edit/AbC123xyz45/Lm4Rt7"
}If it fails, status is failed, error says why, and the section in the editor shows the error.
A polling loop, using callVev from Calling Tools over HTTP:
async function importAndWait(args: { projectKey: string; pageKey: string; html: string }) {
const started = await callVev<{ jobKey: string; sectionKey: string }>('import_html_section', args);
const deadline = Date.now() + 15 * 60_000;
while (Date.now() < deadline) {
await new Promise((resolve) => setTimeout(resolve, 10_000));
const job = await callVev<{ status: string; error?: string; result?: { score: number } }>(
'get_html_import',
{ jobKey: started.jobKey },
);
if (job.status === 'done') return { sectionKey: started.sectionKey, score: job.result?.score };
if (job.status === 'failed') throw new Error(job.error ?? 'Import failed');
}
throw new Error('Import still running after 15 minutes');
}Each import costs the project's account about $0.15–0.30 of AI balance. If the balance is under $1, the call is refused before anything is written.
Round trip: build in Vev, then bring it back
This is how Kopla's Build in Vev keeps a section in sync with Vev, using only the tools above:
- Build. Render your section to HTML and call
import_html_sectionwith the target page. StoresectionKeyandjobKeynext to your section. - Wait. Poll
get_html_importuntil it's done. Then callget_section_snippetforsectionKeyand store its section hash as the baseline. - Check. When your user opens the project, call
get_section_snippetagain and compare section hashes. If they differ, the section changed in Vev. - Pull. Replace your copy with the export's
htmlandcss(andcssImages), and store the new hash.
Embed a page
{
"name": "get_embed_code",
"arguments": { "projectKey": "AbC123xyz45", "pageKey": "Lm4Rt7", "containerMode": true }
}{
"snippet": "<script src=\"https://embed.vev.page/…\" …></script>",
"embedUrl": "https://embed.vev.page/…",
"projectKey": "AbC123xyz45",
"pageKey": "Lm4Rt7",
"ready": true,
"published": true,
"hasEmbedDestination": true,
"pages": [{ "key": "Hk2Pq9", "title": "Home", "path": "", "isIndex": true }],
"parameters": [{ "name": "containerMode", "…": "every embed option, documented" }],
"notes": ["…"]
}The embed only loads once ready is true, which needs the project published with Get embed code turned on.
Create a project with an AI page
{ "name": "list_libraries", "arguments": { "accountKey": "acme" } }{
"name": "create_project",
"arguments": {
"title": "Spring launch",
"ai": {
"libraries": ["LiB4ryKey01"],
"prompt": "Launch page for our spring collection: hero, three product highlights, testimonials, newsletter signup. Warm, upbeat tone.",
"images": [{ "url": "https://cdn.acme.example/spring-hero.jpg", "description": "Model in a yellow raincoat" }]
}
}
}{
"projectKey": "Np7Prj2Key",
"title": "Spring launch",
"accountKey": "acme",
"created": 1779270400000,
"indexPageKey": "Ix1Pg3",
"editorUrl": "https://editor.vev.design/edit/Np7Prj2Key/Ix1Pg3",
"ai": { "status": "generated", "sectionsCreated": 5, "availableSections": 38 }
}If generation fails, ai is { "status": "failed", "message": "…" }, and the project is created anyway, with an empty home page.
To add another AI page to the same project:
{ "name": "create_page", "arguments": { "projectKey": "Np7Prj2Key", "title": "About us", "ai": { "libraries": ["LiB4ryKey01"], "prompt": "Our story and team" } } }A page from your own content, updated later
No AI: the library holds the design, and your call holds the content.
{ "name": "list_library_sections", "arguments": { "libraryKey": "LiB4ryKey01" } }{
"name": "create_page_from_data",
"arguments": {
"projectKey": "Np7Prj2Key",
"library": "LiB4ryKey01",
"title": "Oslo store",
"sections": [
{ "id": "hero", "section": "Hero", "fields": { "Headline": "Now open in Oslo", "background": "https://cdn.acme.example/oslo.jpg" } },
{
"id": "hours",
"section": "Opening hours",
"lists": { "Days": [{ "Day": "Mon–Fri", "Hours": "10–20" }, { "Day": "Sat", "Hours": "10–18" }] }
}
]
}
}{ "projectKey": "Np7Prj2Key", "pageKey": "Os1oPg", "sectionsAdded": 2, "editorUrl": "https://editor.vev.design/edit/Np7Prj2Key/Os1oPg" }Sections created with an id can be updated later. Fields you leave out keep their content:
{
"name": "update_sections",
"arguments": {
"projectKey": "Np7Prj2Key",
"pageKey": "Os1oPg",
"sections": [{ "id": "hero", "fields": { "Headline": "Grand opening this Saturday" } }]
}
}{ "sections": [{ "id": "hero", "result": "updated" }] }result is detached when a designer has taken the section over in the editor, and not_found when no section has that id.