Connect Your AI Agent to KinoViz (Claude Code, Codex, Cursor)
Drive KinoViz with your own AI agent over MCP. Install the local package, pair with a 6-digit code, write a brief, and watch Claude Code, Codex or Cursor build.
Bring your own AI agent lets the Claude Code, Codex or Cursor you already pay for drive the KinoViz editor. You write a short brief, your agent builds the animation layer by layer in a Studio tab you can watch, and you finish it by hand and export it like any other project. This guide takes about ten minutes to set up the first time.
What it is
KinoViz exposes its editor tools to your agent over MCP, the Model Context Protocol. A small package on your computer relays those tool calls to your open Studio tab, which executes them in the same editor you use by hand.
- Your agent, your subscription. The language model runs in your own Claude Code, Codex or Cursor account. KinoViz adds no AI charge.
- KinoViz is the director and the renderer. The brief tells the agent what to make. The editor and the export pipeline render it.
- Private by design. KinoViz does not send your prompts or project data to any third party for this feature. Tool calls travel only between your agent, a local process and your browser tab.
- A Pro feature. Included in Pro, Studio and the 7-day Pro trial.
The KinoViz AI Assistant is currently paused. This feature is separate: the AI is yours, not ours.
Requirements
- A Pro or Studio plan, or an active Pro trial.
- Node.js 18 or newer on the computer that runs your agent.
- Chrome, Edge or Firefox with Studio open.
- An MCP-capable agent: Claude Code, Codex or Cursor.
- The Studio tab kept in the foreground while the agent works. Browsers pause rendering in background tabs.
Step 1: Install the tools in your agent
In Studio, click Connect agent in the top bar. The dialog lists one install command per agent. For Claude Code:
claude mcp add kinoviz -- npx -y @kinoviz/agent-linkFor Codex, add the server to ~/.codex/config.toml:
[mcp_servers.kinoviz]
command = "npx"
args = ["-y", "@kinoviz/agent-link"]For Cursor, add it to ~/.cursor/mcp.json:
{
"mcpServers": {
"kinoviz": {
"command": "npx",
"args": ["-y", "@kinoviz/agent-link"]
}
}
}The dialog fills in the right settings for the site you are on, so copy from there if it differs from the examples above. Restart your agent after adding the server so it picks up the new tools.
Step 2: Connect
- In Studio, click Connect agent and copy the 6-digit pairing code. It is valid for 24 hours.
- Tell your agent:
Use the kinoviz tools, pairing code 123456, with your own code. - When the connection succeeds, a status dot appears in the top bar.
The code is the shared secret between your tab and the local package, so a stray local process cannot drive your editor without it.
Step 3: Write a brief
Open Agent brief from Studio. The brief is what separates a good result from a generic one. It has these fields:
| Field | What to put |
|---|---|
| Style family | Kinetic typography, product launch, social vertical, lower third, UI demo, or freeform |
| Aspect ratio | 1:1, 16:9, 9:16, 4:3 or 4:5 |
| Duration | 2 to 60 seconds |
| Palette | 1 to 6 hex colors |
| Fonts | Up to 3, chosen from KinoViz's font list |
| Copy | Title, subtitle, lines and captions, written out exactly |
| Assets | Cut-outs, logos or photos uploaded into the project |
| Reference notes | What the finished piece should feel like, in plain words |
| Check times | Optional moments the agent should render and inspect |
Why references and real assets matter. An agent that can see what "good" looks like, and has real images to place, produces consistent work. Without them it falls back to text and color blocks, and the result is usually plain.
About freeform. Freeform lets the agent decide everything. Studio asks you to confirm that you understand the result is usually mediocre. Pick a style family whenever you can.
Then tell your agent to start. In Claude Code you can run the /mcp__kinoviz__build prompt, or just ask it to read the brief and build.
Step 4: Let it build and watch
While the agent works, Studio shows an Agent is editing banner with a live activity feed of what it is doing.
- Pause or disconnect from the banner at any moment.
- Take over by hand. You can select, move and edit anything while the agent is connected.
- Undo every step. Each agent action is its own undo step, so you can step back through its work.
Keep the tab in the foreground. If it goes to the background, the agent waits for up to a minute for you to return before reporting an error.
Step 5: Review and export
When it believes it is done, the agent runs a finish check. It renders frames at the check times from your brief, counts unnamed layers, and reports the top layout problems it found. Look through the result in Studio, then ask for another pass or fix details yourself.
Exporting is the normal export dialog, with your plan's resolution, frame rate and format. Nothing changes because an agent built the project.
What works best
| Works well | Not a good fit yet |
|---|---|
| 2D kinetic typography | Cinematic 3D scenes |
| Product launch and feature reveals | Physics simulation |
| Social-media vertical clips | |
| Lower thirds and subtitle bars | |
| UI and app demos |
The agent gets a lean tool set chosen for reliability, not every editor tool. It is aimed at layout, timing, masks and presets rather than the heaviest 3D and effects features. You can always add those by hand afterwards.
Troubleshooting
"Not connected". The agent cannot find a Studio tab. Open a project in /studio, make sure the tab is signed in, and run kinoviz_status to check.
"Not paired". The agent has not been given the pairing code yet, or the code expired. Click Connect agent for a fresh code and tell your agent to pair with it.
The tab is in the background. Bring the Studio tab to the front. The agent queues its work for up to a minute, then reports an error if you have not returned.
plan_required. Your account is on a plan without this feature. Upgrade to Pro, or start the 7-day trial from the pricing page.
FAQ
Does KinoViz pay for the AI model?
No. The model runs in your own Claude Code, Codex or Cursor subscription, and its usage is billed there. The KinoViz AI Assistant is a separate feature and is currently paused.
Is my project or prompt sent to a third party?
KinoViz does not send your prompts or project data to any third party for this feature. The local package connects your agent to your own browser tab on your own computer. Your agent still talks to its own model provider under that provider's terms.
Which agents are supported?
Any agent that can run a local MCP server. We document Claude Code, Codex and Cursor.
Which plan do I need?
Pro or Studio. The 7-day Pro trial includes it.