DEV Community

Shayan
Shayan

Posted on

How a local MCP server connects an agent to a browser motion editor

When Claude Code moves a layer in SoloMotion, there are three pieces involved: the MCP client, a local Node process, and the editor tab. I make SoloMotion, and the separation is useful both for understanding the setup and debugging it.

Piece Job
MCP client Starts the local server over stdio and calls its tools
SoloMotion MCP server Exposes editor commands and bridges them to the linked tab
Editor tab Owns the scene, applies edits, and can render previews

The local bridge listens on loopback. The publicly hosted browser editor is the UI. The package is available on npm, and the source documents pairing for hosted and self-hosted builds.

Debug from the outside in

First check whether your client can start the stdio server and see its tools. If it can’t, verify your Node and npm installation and the executable configured in the client. If tools appear but the editor is unavailable, look at pairing next. In the editor, use Agents → Use your agent app → Link and keep the tab open.

Once connected, ask the agent to create one shape and stop. Confirm it appears, select it yourself, then undo the agent’s change. That checks the entire round trip without the noise of a complicated scene. If you self-host, consult the package setup for its allowed origins and pairing token.

Trace one request end to end

SoloMotion editor showing editable layer properties and a timeline curve

Ask the MCP client to create a shape named Bridge Test, then inspect the layer list in the tab. Next ask it to add two position keys a second apart. Before rendering anything, move the second key yourself and check whether playback reflects that change. The exercise uses four observable results: tool discovery, a new layer, two visible keys, and a playback change. If something goes wrong, the last successful result tells you where to look.

Last successful result Look here next
Client opened Local Node and npm, package command, and the client's MCP configuration
Client discovered SoloMotion tools Tab is open, linked, and accessible to the bridge
Shape appeared on the layer list Layer selection, frame times, and the position key values
Scene plays back as expected Export settings or the render-preview workflow

Why the editor remains the source of truth

During a revision, the agent and the person share a scene. You can ask for a circle, move its keys yourself, then ask the agent to adjust the ease. Naming the layer in the request makes it easier to pinpoint the intended edit in a busy project. The package exposes editor commands and preview renders such as view_render and view_frames. A preview gives the agent a way to inspect the resulting image rather than assume a successful command made a good scene.

For a reproducible bug report, include your MCP client, the stage that failed, the editor URL origin, and which of the four results you saw. Leave credentials and pairing tokens out of the report.

AI assistance was used to draft this article.

Top comments (0)