Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Vev MCP Server

Vev ships a Model Context Protocol server, so AI assistants and agents — Claude, ChatGPT, Claude Code, or anything else that speaks MCP — can find your Vev projects, generate embed code, export project content section by section, and create new projects and pages — optionally generated with AI from your section libraries.

https://api.vev.design/v2/mcp

The server is stateless Streamable HTTP: JSON-RPC 2.0 over POST, one JSON response per request. Every tool requires the list:project scope; create_project, create_page, list_library_sections, create_page_from_data and update_sections also require create:project.

Connecting

Claude (claude.ai and Claude Desktop)

Go to Settings → Connectors → Add custom connector and paste the server URL. Claude discovers the OAuth endpoints automatically and opens the Vev consent screen — log in, review the access, and click Allow access.

Claude Code

claude mcp add --transport http vev https://api.vev.design/v2/mcp

The OAuth flow starts automatically on first use. Alternatively, skip OAuth entirely with an API key:

claude mcp add --transport http vev https://api.vev.design/v2/mcp \
  --header "x-vev-key: [your-key]"

Any other client

Two authentication options:

  • OAuth 2.1 — authorization code + PKCE (S256), with dynamic client registration. Discovery documents are at https://api.vev.design/.well-known/oauth-authorization-server and https://api.vev.design/.well-known/oauth-protected-resource/v2/mcp. The access token you receive is a Vev API key — it stays valid until revoked from your user profile. To connect your own app's users, follow Connect Your App with OAuth.
  • API key — create a key with the list:project scope, plus create:project to create projects and pages (see Authentication), and send it as an x-vev-key header or as Authorization: Bearer [your-key].

Connections authorized before the create tools existed only hold list:project: the create tools answer with an error naming the missing scope. Remove and re-add the connector to grant it.

Test the connection:

curl -X POST 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/list"}'

Calling the server from your own code instead of an AI client? Calling Tools over HTTP shows the raw requests, responses and errors, and Examples has a complete call for every tool.

Tools

ToolWhat it does
find_projectsFind projects by key, free-text search, or URL
get_embed_codeBuild the embed snippet for a project page, with every embed parameter documented
get_project_sectionsExport a project section by section, for rebuilding its content in another system
get_section_snippetExport sections, or a whole page, as clean, self-contained HTML + CSS for any site or CMS, without AI
list_librariesList the section libraries AI pages can be built from
create_projectCreate a project, optionally with its home page generated by AI
create_pageAdd a page to a project, optionally generated by AI
list_library_sectionsList a library's sections and the content each can take
create_page_from_dataBuild a page from library sections filled with given content, without AI
update_sectionsChange the content of linked sections by their id
import_html_sectionRecreate any HTML (a snippet, a Claude artifact, a public page) as a native, editable Vev section, with AI
get_html_importProgress and result of an import_html_section

Only projects the authenticated user can access are ever returned, and pages can only be added to projects the user can edit.

find_projects

Look up projects three ways, combinable in one call:

  • ids — project keys to fetch directly (max 20)
  • search — free-text search across titles, descriptions, tags, and page text
  • url — a published site URL, an editor URL, or an embed URL, resolved to its project
  • accountKey — restrict search to an account (defaults to your own), limit — max results (default 10)

Each result includes the project key, title, publish state, a thumbnail URL, and an editor link.

get_embed_code

Takes a projectKey (and optionally pageKey — defaults to the index page) plus the embed options fill, shadowdom, containerMode, target, and templateVariables. Returns the ready-to-paste script tag, the embed URL, the project's page list, and a readiness check: the project must be published to an embed destination (enable Get embed code in the editor's publish dialog) before the embed resolves.

Tip: containerMode: true rewrites the design's media queries to container queries, so the embed responds to the width of its slot instead of the viewport — the right choice when embedding a Vev page as a section inside another layout.

get_project_sections

Exports everything needed to rebuild a project's content elsewhere. For every section of every page (filter with pageKey or sectionKeys):

  • a screenshot URL (1200px wide, generated when a project version is saved)
  • the element tree with text content as HTML
  • the section's real per-breakpoint CSS (includeCss, default on)
  • every image, video, shape (inline SVG), and font the section uses, with URLs and dimensions
  • interactions and animation keyframes (includeInteractions, default on) — animations are CSS-property keyframes with WAAPI-style timing, and triggers reference elements by their key, which is also the element's DOM id
  • captured rendered HTML where available (includeHtml), and the raw Vev content models for full fidelity (includeModels)

Project-level, the export carries the resolved design theme (colors, text styles, spacing, radii), the breakpoint definitions, and the project color swatches.

Calls are capped at 40 sections — narrow with pageKey or sectionKeys for larger projects.

get_section_snippet

Takes a projectKey and one of sectionKey (one section), sectionKeys (several, in that order) or pageKey (a whole page: its header sections, its own sections, its footer sections), and returns snippets any site, CMS or site builder (Kopla) can store, edit and host. It is deterministic and uses no AI. One section answers one snippet; several or a page answer sections (each a snippet with its placement) and page, the paste-it-whole form (html with header and footer wrapped, css importing the shared stylesheet once). Pinned elements are listed in notExported. Each snippet has:

  • html and css: frames, text and images become one element each, with readable classes named after the elements (v-hero-title), and the section's real per-breakpoint CSS on those classes. Vev's layout is kept exactly: every element is still placed in the section grid by its own size and margins.
  • Copy and pictures stay literal HTML (the text's own markup, the image's URL), so the receiving builder can make each of them editable.
  • css begins with @import url(…) layer(vev): the project's shared stylesheet (sharedCssUrl, on Vev's CDN, one address per project: theme, fonts, base rules, background images, widget CSS), so a snippet works pasted anywhere and a page of many snippets downloads it once. Breakpoints are container queries: a section follows the width it is placed in, a CMS column included.
  • cssImages: background images from the CSS, as variables (var(--vev-img-<hash>)) the shared stylesheet declares, mapped to their URLs.
  • delegated: elements that stay rendered by Vev (coded widgets, component instances, shapes), each with the reason. Each becomes its own small Preact island, hydrated when it already has markup.
  • script: the smallest runtime the section needs, added to html as one island: none (pure HTML and CSS), interactions (kopla-interactions.js, about 32 KB, no Preact: interactions are plain DOM and find their targets by id), or widgets (kopla.js plus one ES module holding every coded widget of the project).
  • tooLarge: set when the HTML is over 24 KB or the CSS over 16 KB.

Every section of a project with the same script carries the same island, so the page loads each runtime once.

list_libraries

Lists the libraries AI page generation can build from: your account's own libraries plus public Vev libraries, limited to AI-enabled ones (a library admin turns on AI for a library in the editor, which analyzes its sections). Scope the list to where the page will go — projectKey for an existing project, or accountKey / workspace for a new one — since team-limited libraries are only available inside their teams. Each result has the library key, title, description, and whether it is public or your own.

create_project

Creates a project with an empty Home page. Takes a title, and optionally accountKey (defaults to your own), workspace (the folder to create it in), and preset (desktop or mobile first). Returns the project key, the home page key, and an editor link.

Pass ai to fill the home page with AI — the same library page AI as the editor's AI page draft:

  • libraries — library keys from list_libraries (1–5)
  • prompt — what the page is for: audience, purpose, tone, sections you want
  • text — source copy or facts to use (optional)
  • images — { url, description } pairs to place on the page; URLs must be public https (optional)
  • imageStyle — a style prefix for generated images, e.g. flat pastel illustration (optional)
  • useOnlyProvidedAssets — never generate images, only use the ones provided (optional)

The AI picks sections from the libraries and writes their copy, images, and icons. It spends AI credits from the project's account (and team), and the call is refused up front if the balance can't cover a page. Generation takes up to about a minute; images the AI asks for keep rendering in the background for a minute or two after the call returns. The result's ai.status is generated (with the number of sections written) or failed with a message — the project is created either way.

create_page

Adds a page to an existing project you can edit. Takes projectKey, an optional title (default Untitled; a title already used in the project gets a number appended), and the same optional ai object as create_project. Returns the page key and an editor link.

list_library_sections

Takes a libraryKey. Returns each section with its fields (text, image, background) and lists, the same as See what a library can fill.

create_page_from_data

Builds a page from library sections with your content: the same input always gives the same page, and it uses no AI credits. Takes projectKey, library, sections and an optional title, or a pageKey to add to an existing page. A section is { id?, section, page?, fields?, lists? }, as in Create a page with your content. A section with an id is linked: designers cannot change its content by accident, and update_sections can change it later.

update_sections

Takes projectKey, pageKey and sections: [{ id, fields?, lists? }]. Fields you leave out keep their content; a list replaces the whole list. Each id reports updated, detached (a designer took the section over) or not_found. See Update linked sections.

import_html_section

The other direction from get_section_snippet: takes HTML from anywhere and recreates it as a native Vev section, with frames, text, images and icons you can edit like any other. Takes projectKey, pageKey, and either html (a fragment, or a whole document such as a Claude artifact) or url (a public https page). Optional:

  • selector — CSS selector of the part to import, when html or url holds more than one section. Default: the whole fragment, or <body>.
  • css — a stylesheet for a fragment that depends on outside CSS; baseUrl — the base for relative image, font and link URLs.
  • name — the section's layer name; position — its index among the page's sections (default: last).

How it works: the HTML is rendered in a browser, so its scripts run (a React or Tailwind artifact renders itself), and measured at 1440 px and 375 px: every visible element's box, layout, typeface, size and colour. An AI model (openai/gpt-6.2-sol) writes the section from those measurements and screenshots; Vev renders it with the project's own theme, and a vision check (openai/gpt-6.1-terra) compares that render with the original at both widths. Up to three rounds of fixes follow, and the best one is written.

  • Images, SVGs (logos, illustrations) and the section's typefaces are copied into the project: Google fonts by name, self-hosted fonts with their files.
  • A video becomes a still image of its first frame.
  • Behaviour is not imported yet: hover states, scroll reveals, tabs and other interactions render in their resting state, and content hidden behind them is left out.

The call returns at once with a jobKey and the sectionKey: the section shows as pending in the editor until the import finishes, usually in 2–5 minutes. It spends AI credits from the project's account (about $0.15–0.30 per section), and is refused up front when the balance is under $1.

get_html_import

Takes the jobKey from import_html_section. Returns status (queued, running, done, failed), the current step, and when done a result: the match score (0–100, the vision check's comparison of the Vev section with the original), the differences it still sees, the rounds it took, and notes on what could not be carried over (a video turned into a still, an image that could not be copied). Only someone who can edit the project can read its imports.