MCP Server

The MCP server is for the components we did not write: yours. Describe the interaction you are building and it says whether the runtime has a primitive for it, which ones and in what order, what each one guarantees and what it conflicts with — then reads the file your agent wrote for the mistakes that compile cleanly.

That is what the open-source runtime is for. Installing one of our components is one way to use it. Writing your own against the same scheduler, sensors and quality governors is the other, and this is how an agent learns to wire them. None of it needs a Vector Vesper component in the codebase, or an account.

Connect it when the work involves more than copying a component.

The workflow it adds

Four steps, in this order.

1. Decide. Describe what you are building. The server says whether it needs a primitive, which ones, and in what order.

2. Read the contract. Options, frame lane, conflicts, and the cases where a primitive is the wrong choice.

3. Write the code.

4. Check it. A static review of the file for the motion mistakes that compile cleanly and still ship a bad page.

Step one is the one people skip, and it is the one that saves the most work.

Set it up

Install the MCP server from your project directory:

npx vectorvesper mcp install

With no client name, VV configures every supported editor it finds. To configure one editor explicitly, name it:

npx vectorvesper mcp install cursor

Restart the editor, then confirm the connection:

npx vectorvesper mcp status

No token is required to discover the runtime and its documentation. Authentication only affects which Pro components the install workflow can access.

Supported clients

The installer merges Vector Vesper into an existing MCP config; it does not replace the other servers you rely on. If it finds a config it cannot parse, it leaves the file untouched and prints the snippet for you to add manually.

What your assistant can do

Plan before you build

plan_motion takes a plain description of what you are making. One component or several working together. It answers four things:

• whether this needs a Vector Vesper primitive at all;
• which ones, listed in wiring order;
• what that combination conflicts with; and
• when the recommendation it just gave would be the wrong call.

The first answer matters most, because a good part of the time the answer is that you do not need the library. A hover state is a pseudo-class. A fade when something mounts is a transition. A one-time reveal as a card scrolls in is a viewport observer and a class name. All three run off the main thread already, so rebuilding them on a frame loop costs time and gives nothing back. Around one in five of the tool's answers points at a platform feature instead of a primitive.

Ask it the way you would ask a colleague:

For that one it separates the two halves. The fade is a viewport observer and CSS. The tilt reads the pointer every frame, so it names the pointer parallax pattern and the primitives behind it.

You can also hand it a set you have already chosen:

It reads both contracts and reports what actually matters when they sit together. Which one owns the element's transform, so you know what to move onto a wrapper. What each of them fights with. Whether the file needs a client boundary. Whether anything re-renders during animation. It also names what they share, because sharing is the design here: one frame loop and one set of sensors serve the whole page, so a second primitive costs a subscriber rather than a second loop.

For a 3D scene it goes further and hands you a starting point. Ask for a hero in plain three.js and the first answer includes a complete file built on useThreeScene, with the scene gate, the pixel-ratio cap, context-loss recovery, cleanup and reduced motion already wired, and a stand-in shown while the scene is not drawing. You replace the torus knot with your scene. For React Three Fiber it names useSceneGate with useRenderQuality instead.

It also knows when to wait. Ask it to hold a heavy chart until the scroll settles and it answers useSceneGate({ content: true }), which waits for the same things a 3D scene does and still shows the chart to a visitor who asked for less motion.

Run a motion check

check_motion reviews any file with animation code for issues that are valid JavaScript and still create a poor motion system. Every finding names the file, the line, the rule, and the fix.

Twenty-one rules, in three severities. Errors are code that will break or silently discard something you asked for. Warnings work and cost more than they should. Info means what is written is incomplete rather than wrong. Four of the warnings are for hand-built three.js: a scene that keeps drawing off screen, a pixel ratio with no cap, a context that is never given back, and a renderer rebuilt every time a setting changes.

None of them is something tsc would catch. A few examples: a private frame loop that cannot yield under load; React state written sixty times a second; a layout read taken in the write lane, which on one page cost 46ms a frame while the runtime's own work was 2.4ms; a lost graphics context nothing is watching, which leaves a black canvas and a clean console.

The full list, with what each rule catches and how to fix it, is on check_motion Rules.

Ask your assistant to run it after adding a new interactive section or before you ship a motion-heavy page.

Configure it by hand

Use manual configuration only when the installer cannot write the file for you. Claude, Cursor, Windsurf, and Antigravity use this shape:

{
  "mcpServers": {
    "vectorvesper": {
      "command": "npx",
      "args": ["-y", "vectorvesper@latest", "mcp", "--stdio"]
    }
  }
}

OpenCode uses a different shape. Servers sit directly under mcp, and command is one array:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vectorvesper": {
      "type": "local",
      "command": ["npx", "-y", "vectorvesper@latest", "mcp", "--stdio"],
      "enabled": true
    }
  }
}

If OpenCode reports a schema error for mcp.servers, the config is using the Claude/Cursor shape. Move vectorvesper directly under mcp instead.

Keep @latest in the command. Without it, npx may reuse a global install, project dependency, or cached package. Your assistant can then miss tools added in newer VV releases without an obvious error.

Running npx vectorvesper mcp in a terminal prints setup help rather than starting the server, since a server with nothing connected to it is almost never what you meant. --stdio starts it anyway, which is why the configs above include it: the server always starts when your editor launches it.

If you do not use MCP

You can still give a coding assistant the most important runtime rule. Running:

npx vectorvesper init

adds a Vector Vesper block to AGENTS.md. It tells assistants not to start a private animation loop and to use the shared conductor instead.

That is enough for simple work. MCP is the deeper layer: the planning step, the full contract for every primitive, and a check of the motion code you actually wrote.