en

MCP Server (AI Agents)

MCP Server (AI Agents)

The editor has a built-in MCP server — a way for AI agents such as Claude Code, Claude Desktop and other clients of the Model Context Protocol to see and operate the editor the way a person does. With the server enabled you can ask an agent to build or tune an effect for you: it opens projects, edits emitters, draws paths and masks, reads the preview with screenshots, configures exporters and exports the result — while you watch every step happen live in the editor and keep the full undo history of what it did.

The server is off by default. It only ever listens on 127.0.0.1 (your own computer), so nothing outside your machine can reach it.

Enabling the server

There are two ways to switch the server on:

  • Editor Settings — open Windows → Editor Settings... and tick Enable MCP server in the MCP Server (AI Agents) group. The change applies immediately, no restart needed, and is remembered across editor runs.

    The Port field picks the TCP port the server listens on. It defaults to 3742, and keeping it fixed is the point: you register the editor with your agent once, and the address keeps working across editor restarts. If the port is already taken by another program (or a second editor), pressing OK shows an error and reopens the dialog so you can pick a different number.

  • Command line — start the editor with --mcpServer=3742 (fixed port) or bare --mcpServer (picks a free port for that run and prints it to the log). The command-line switch takes precedence for that run and does not change the saved setting, which makes it handy for scripts that launch the editor for an agent session.

With the server running, the editor log (and the console, when started from a terminal) shows the address:

[MCP] Server listening on 127.0.0.1:3742

Connecting an agent

Any MCP client can connect over Streamable HTTP. For Claude Code, register the editor once (with the fixed port you chose):

claude mcp add --transport http --scope user npeditor http://127.0.0.1:3742/mcp

After that, a Claude Code session on the same machine sees the editor's tools and can drive it whenever the editor is running with the server enabled. Other MCP clients follow their own registration flow — the endpoint is always http://127.0.0.1:<port>/mcp.

A good first prompt is simply to ask the agent what it sees — it will call the editor's status tool and describe the open projects and the current effect.

What an agent can do

The agent sees the editor as a live tree of named UI elements — every panel, button, checkbox and menu — plus a set of higher-level tools for the surfaces where clicking alone is not enough. In practice it can:

  • Projects and effects — open and create projects, list resources, create, open and save effects, and undo/redo. Every change an agent makes lands in the same undo history as yours, one undo step per action, so anything it does can be rolled back step by step.
  • Emitter Guide and every panel — press buttons, switch modes, set values, pick from menus and drive dialogs, the same way a person would.
  • Emitter Scheme — inspect the block scheme of the current emitter, create and delete blocks, connect and disconnect them, and move them around the canvas.
  • Graphs — edit the curves of a Curves block: add, move and delete keys, change key and segment types, toggle track looping.
  • In-preview editors — edit paths point by point, place and size collision primitives, draw and erase Area masks (including loading a picture as a mask), and lay out grids.
  • Preview scene and timeline — add, arrange and configure scene objects (pictures, videos, image sequences, other effects), move and rotate them, and write recorded motion along the timeline.
  • Preview and screenshots — play, pause and scrub the preview, move the camera, and take screenshots of the viewport to actually see the effect it is building. Screenshots need the editor window visible on screen (not minimized).
  • Exporting — read and change the project's export configuration (enabled exporters, versions, output folders) and export effects, honouring the same rules as the Export button, including your post-export command.
  • Feedback to the developers — when the agent hits something it cannot reach, behavior that looks wrong, or a bug, it can send a short report (optionally with screenshots) straight to the NeutrinoParticles team. Reports require a signed-in account, are rate-limited by the server, and automatically carry only the editor version, the operating system and the active renderer — never file paths or project names.

What stays in your hands

A few things are deliberately reserved for the human at the keyboard:

  • Signing in is yours alone. Agents can check whether you are signed in and whether your plan allows exporting, but they cannot log in, cannot read or type credentials, and are instructed to ask you to sign in through the editor's Account button when an export needs the server.
  • Exports run under a progress window. While an agent exports, the editor shows the same progress dialog as a manual export. It blocks stray edits (yours and the agent's alike) so the files being written stay consistent, and you can press Cancel at any time to stop the remaining items.
  • Feedback is sent only with your consent. Agents are instructed to show you the exact report — title, text and attachments — and get your approval before sending anything to the NeutrinoParticles team. A report may include screenshots of your effect, so review it as you would any outgoing message.
  • You can always take over. The editor stays a normal, interactive editor while the server runs. Anything the agent did is in the undo history, and closing the editor (or just switching the checkbox off) ends the agent's access instantly.

Practical notes

  • The server accepts connections only from the same computer (127.0.0.1). To use an agent from another machine you would have to build your own tunnel — nothing is exposed by default.
  • One agent action executes at a time; the editor stays responsive between actions.
  • Debug-heavy effects can make the preview resimulate for a while after an edit; agents are told to wait for the preview to settle before taking screenshots, so do not be surprised by short pauses.
  • If you use the editor and an agent at the same time, an open menu or a modal dialog temporarily blocks the agent's model-changing tools — it resumes once the dialog is closed.