Wevi MCP Tools Reference

The @wevi/mcp package exposes 25 Model Context Protocol tools. The happy path is list templates → read schema → create one project with all scenes → trigger render → poll status. Every scene of a video lives in one project and is exported as one concatenated MP4.

1. wevi_list_templates — pick published templates from one aspect ratio.
2. wevi_get_template_schema — read each template's editable layer keys.
3. wevi_create_project — one project with scenes: [...].
4. wevi_trigger_render — render every scene and export one MP4.
5. wevi_get_render_status — poll until phase is completed, then use videoUrl.

---

1. wevi_list_templates

List published templates. Only published templates can be used in projects; drafts and archived templates are never returned to API keys.

Each result carries aspectRatio, storyboardRole (the beat it plays best: hook, problem, solution, proof, cta or transition), fitsBeats (every beat it can play), voiceoverBudget (max words and characters for the scene length; longer narration is trimmed at export), requiresUiCapture and uiCaptureSlots. Pick all templates for one video from a single aspect ratio. Templates with requiresUiCapture: true show real product UI: capture a page into those scenes with wevi_capture_scene after creating the project. Capture slots you leave unfilled render empty (no stock or demo imagery), so capturing fewer components than uiCaptureSlots.max is safe.

---

2. wevi_get_template_schema

Returns the editable layers of a template: key, label, type (text, color, slider, toggle, dropdown, image, …), role (logo, external_logo, avatar, background, brand_name, ui_component), autoFill (what Wevi fills the layer with when you leave it unset), description, default value, validation (min/max) and dropdown options. Hidden and protected layers are omitted. brandLogoLayers lists the keys that need a brand logo. The result also carries previewVideoUrl and thumbnailUrl, and the tool attaches the thumbnail as an image so you can judge the look of the animation before committing to it.

---

3. wevi_create_project

Create one project containing all scenes of the video. The aspect ratio is derived from the templates; mixing ratios is rejected.

Brand:

Scene:

Returns projectId, aspectRatio, sandbox, the resolved brand and the created scenes, each with autoFilled (layer keys Wevi filled from the brand: logo, app logos, avatars, backgrounds, colors). If a template has a logo slot and the brand has no logo, the call is refused with missingBrandAssets; ask the user for the product website and retry.

---

3c. wevi_update_scene

Change one scene after creation, typically to fix a failed render without rebuilding. The next wevi_trigger_render re-renders only scenes whose inputs changed.

---

3d. Revising a project

Change a project without rebuilding it. The next wevi_trigger_render re-renders only scenes whose inputs changed.

Text layers you leave unset on create, add or swap are filled from the scene title, else the start of the narration, else the project title. Layers that still show the template's own words are listed per scene as templateCopy; set them with wevi_update_scene when the copy matters. A required text layer with nothing to draw from is refused with missingText.

---

4. wevi_get_project

Inspect a project's scenes, layer values and lifecycle status. The response also lists pendingCaptures (scenes that still need wevi_capture_scene) and a nextStep.

---

5. wevi_trigger_render

Render every scene, then export them as one video with music and voiceover. Waits up to waitSeconds; if the video is not ready it returns the current phase for polling.

---

5b. wevi_get_scene_previews

Per-scene render results: state, a preview URL for each rendered scene (the scene alone, without music), and the error for failed ones. Scenes that failed before reaching the renderer say "Credit refunded". Takes projectId.

5c. wevi_list_music and wevi_list_voices

Library tracks with mood and genre tags, and narrator voices with preview clips. Pass musicTrackId or voiceId to wevi_trigger_render; without them Wevi picks a track for the brand's tone and the default narrator.

---

6. wevi_get_render_status

Poll render + export progress. Returns phase (rendering, exporting, completed, render_failed, failed) and videoUrl once completed.

---

7. wevi_generate_storyboard

Plan a storyboard from a brief against the published templates. The plan already follows the create rules, so its createPayload can go straight to wevi_create_project: every scene uses a published template from one aspect ratio, each scene's narration sits inside that template's voiceover budget as a complete sentence, on-screen copy is written for the template's text layers, and scenes that show real product UI are flagged so you know what to capture. Costs 1 credit on live keys and takes 20–60 seconds (progress is reported while it runs).

Returns draft (title, narrativeAngle, aspectRatio, totalDurationSeconds and scenes), createPayload, notes and nextStep. Each scene lists order, title, purpose, visualDirection, templateId, templateName, storyboardRole, durationSeconds, voiceover, voiceoverBudget (seconds, maxChars, maxWords), onScreenText, parameters (layer key → copy), textSource (ai, onScreenText or none), textLayerKeys (the template's text layers; empty when it has none), requiresUiCapture, captureSlots and captureHint. Show the plan to the user, adjust wording if asked (stay within voiceoverBudget.maxChars), then send createPayload to wevi_create_project; when the draft had no website, ask for it and add it as createPayload.brand.websiteUrl first. Sandbox keys are limited to 4 scenes per project, and drafts made with them respect that.

---

8. Browsing before you capture

Use these when the right shot is not the top of a public page: a tab, a modal, a dashboard behind a login the user walks you through, or a section further down.

Limits: 12 session opens per minute, 60 browse or outline calls per minute, 3 open agent sessions at a time, and a daily browser-time allowance (120 minutes on live keys, 40 on sandbox keys); past a limit the tool returns a 429 that says when it resets. A session stays on the site it was opened for, plus any site you open on purpose with a goto step: a step that lands on another site is undone and reported as refused.

wevi_open_page

Open a live browser session and get the page outline: headings, links, sections with their vertical positions, scroll state and a small screenshot.

wevi_browse

Run steps in the session and get the resulting outline and screenshot. Steps stop at the first failure.

Action: { type: "goto", url }, { type: "click", selector | text }, { type: "type", selector, text, submit?, clear? }, { type: "hover", selector }, { type: "scroll", selector | y | ratio }, { type: "wait", ms | selector }, { type: "press", key }, { type: "back" }.

wevi_close_page

Close the session. Agent sessions also close after 10 minutes idle or when the project is published. Browser time is metered: the first 5 minutes of each session are free, then 1 credit per started 5 minutes, shown as "Browser session" in the usage panel; sandbox keys are free. Each capture still costs 1 credit.

---

wevi_capture_from_image

Use a still image at a public URL as the captured page. Works for templates whose whole background is the page (uiCaptureSlots.fullPageBackground); templates that animate individual elements need the live page. Free.

---

8a. wevi_capture_scene

Capture a live web page into a scene whose template needs a UI capture. Loads the URL, detects UI components the same way the Wevi app does, auto-selects the best ones, and makes the scene render-ready. Costs 1 credit on live keys.

Returns the chosen components, the candidates list ranked best-first (label, type, size, selector, number, suggested), the template's slots (min/max picks or full-page background, plus the template's selection rubric: guide, smartGuide with the author's do and don't notes, prefer, avoid, size, targetFill), captureNotes explaining how captures work, elapsedMs, and renderReady. Candidates are ranked by your focus hints first, then by fit: page content over navigation, headers and footers; cards, buttons and inputs over loose text; readable sizes over slivers and whole sections. A capture opens the page in a real browser, closes cookie and consent notices (choosing "reject" or "necessary only" when offered, otherwise "accept" or the close control) after every navigation, hides sticky bars and chat widgets, recaptures the background with the chosen components hidden, and usually takes 40 to 70 seconds; the tool reports progress while it runs. The page is measured first without a screenshot, framed once if the picks need it, then captured once over a single browser connection, so auto framing no longer costs a second capture. timingsMs in the result shows where the time went (openSession, steps, probe, frame, capture, finalize). frame in the result says which viewport and scroll position were used. If the choice is wrong, re-pick without reloading:

8b. wevi_select_capture

Choose different components from an existing capture. Takes projectId, sceneId, captureId, and selectedComponentIds (for text templates the first id must be the text element). No credit.

8c. wevi_capture_web_ui

Standalone screenshot of a URL, returned as an image URL for templates with a plain image slot (logo, avatar, background).

---

0. wevi_get_capabilities

Returns what Wevi can and cannot make, the questions an agent should ask before building, the supported aspect ratios, sandbox limits, and credit costs. Takes no parameters and makes no API call. Agents should call it first in a new conversation, and whenever a request sounds outside Wevi's scope (for example "make a dance video").

The same statement is sent to the client as the server's instructions on connect, so assistants that honour MCP instructions already have it.

9a. wevi_list_brands

Brands saved on the account with website, logo and colors. Pass one as brandId to wevi_create_project to reuse it.

9. wevi_get_credits

Show the credit balance for the current key's account: plan allowance used and remaining, purchased credits, per-action costs, packs on sale and the top-up link. Takes no parameters. Call it before a large batch, or when a tool fails with 402.

---

💳 Credits

Live keys spend credits: 1 per scene render, 1 / 2 / 4 per 720p / 1080p / 4K export, 1 per storyboard draft or web capture. Free accounts include 10 credits, Pro includes 150 per month, and packs can be bought from the API Keys & MCP page. When credits run out the tool returns a 402 message with the missing amount and the top-up link.

---

🧪 Sandbox keys

With a wevi_test_ key every tool works the same, but renders are watermarked, exports are capped at 720p, and nothing counts against your credits. Status responses include sandbox: true.

Each test key has a hard daily allowance: 20 scene renders, 5 exports, and 4 scenes per project, resetting at 00:00 UTC. Past the cap, wevi_trigger_render returns a 429 message with the reset time.

---

🔐 Capturing Private & Authenticated Dashboards

Templates often need real product UI that sits behind a login. Wevi keeps the human in the loop:

1. Never share passwords with an assistant. Agents are told not to ask for them, and Wevi never stores typed text in its logs.
2. Log in once, in your own browser. Every page the agent looks at reports whether it is a sign-in screen (authWall) and carries loginUrl, a link of the form https://app.wevi.ai/browse/live?sessionId=…. When a page needs a login, the agent sends you that link; it opens the same cloud browser the agent is using. You sign in there (SSO and 2FA included) and press I am signed in. The agent waits with wevi_wait_for_login, then reads the app's routes (its own navigation: dashboard, reports, settings…) and captures the view the scene needs. A sign-in screen never costs a credit: wevi_capture_scene returns loginRequired: true instead of capturing the form.
3. Logins persist per account. The browser profile is kept for your Wevi account, so later captures from the same site are already signed in. The same profile is used by the capture browser inside the Wevi app.
4. Reset any time. The Browser logins control on the API Keys & MCP page clears the stored browser profile.
5. Sandbox keys never reuse logins. wevi_test_ keys always browse in a fresh, anonymous profile.
6. Guardrails. Agent steps cannot click anything that looks like a payment, purchase, deletion or account change, are limited to 12 per call and 150 per session, cannot open non-web URLs, and every step is recorded on the project (what was clicked or typed into, never the text).

Direct image fallback still works: drop a screenshot into the chat and ask the agent to use it as a plain image layer.

---

⚖️ Capture Methods Compared: Wevi Browser Engine vs. Chat Drag-and-Drop