@laplace.live/persona-mcp is Persona's first-party MCP server, which hands the Plugin API to an AI assistant: switch scenes, load and place models, toggle expressions, play motions, run automations, and take a screenshot of the stage to see what an edit did
It uses the same API as the web console and the Stream Deck plugin, and opens nothing beyond it. It never touches the desktop application's own code — anything it can do, the Plugin API can do
Prerequisites
| You need | Notes |
|---|---|
| An MCP client | Claude Desktop, Claude Code, Cursor, Codex, or any other |
| Node.js | 24 or later, so npx can run the package |
| LAPLACE Persona | Running, with the Plugin API enabled |
| An API key | Create one under Settings → Plugin API and pass it as PERSONA_TOKEN |
Setup
Add this block to your MCP client's configuration — Claude Desktop's claude_desktop_config.json and Cursor's mcp.json both take this shape:
{
"mcpServers": {
"persona": {
"command": "npx",
"args": ["-y", "@laplace.live/persona-mcp"],
"env": { "PERSONA_TOKEN": "psk_…" }
}
}
}Claude Code takes the same thing as one command:
claude mcp add persona -e PERSONA_TOKEN=psk_… -- npx -y @laplace.live/persona-mcpTwo environment variables:
| Variable | What goes in it |
|---|---|
PERSONA_TOKEN | The token of the key you created in Persona. Required |
PERSONA_ADDRESS | Empty means this machine's 127.0.0.1:25034. Also takes host, host:port, or a full ws:// URL |
It never fails at startup: MCP clients tend to launch the server before Persona is open, so it dials on the first tool call. A missing token, a closed application or a revoked key all come back as text telling the assistant what to fix, rather than a crash
Once it connects, Persona's Connected Clients lists a row reading Persona MCP with the client's self-declared name in brackets, by the developer LAPLACE
Treat the token like a password. An assistant holding it can switch scenes, load models, change the stage, and see what the stage looks like. The server listens on loopback only unless you turn on local network access
Tools
The tools are task-shaped, around twenty of them, rather than one wrapper per protocol method — a long list makes a model worse at picking, and costs context every turn. Every read-only tool carries readOnlyHint, and delete_scene and remove_item carry destructiveHint, so clients that confirm destructive calls do
| Tool | What it does |
|---|---|
get_state | App version and capabilities, every scene, and each item in the active one with its id, format, visibility and placement. Call it first |
capture_stage | A screenshot of the stage, so the assistant can look at the result |
activate_scene create_scene | Switch to a scene; add an empty scene and switch to it |
rename_scene delete_scene | Rename one; remove a scene and everything in it. The last scene cannot be deleted |
list_models add_model | Every model Persona can load; put one on the stage, or swap an existing layer to it in place |
describe_model | One item in detail: placement, capabilities, and a model's expressions and motions with what is playing |
remove_item set_visible | Take an item out of the active scene; show or hide it without removing it |
set_placement reset_placement | Move, scale, rotate; ease back home. Only the fields passed change, and fields the item cannot take come back reported as ignored |
set_expression | Turn one expression on or off by name. Already in that state is a no-op |
play_motion stop_motion | Play a motion by group and index; fade the running one out and let the idle resume |
list_automations run_automation | List automations and the active model's hotkeys; run one by id |
trigger_hotkey | Fire one of the active model's shortcuts |
call_api | Call any Plugin API method directly, with params forwarded verbatim |
A 2D item's placement is in pixels from the stage centre with +y down and rotation in radians; a 3D item's is in metres and radians. Each tool says so in its own description, so the assistant does not have to guess
Looking at the Stage
Behind capture_stage is the new stage.capture method: the stage window as displayed, as a PNG with transparency, its longest edge 1024 px by default and 2048 at most, never upscaled. It needs the application to report the stage-capture capability — 0.55.0 and later; on anything older the tool says to update
Each capture costs the stage a frame, so it belongs at the point where a result needs checking, never on a timer
The call_api Escape Hatch
Whatever the other tools do not cover — the camera, lighting, the environment, layer effects, objects and webpages, spawning props, tracking sources, lip sync, speech and settings — goes through call_api: hand it a method name and a params object. It forwards method names it does not recognize too, so a newer Persona's methods are reachable without waiting for this package to catch up
Bad params come back as an error naming the field; a protocol-level error also carries a hint saying which tool the right value comes from
This package is only a bridge — it translates MCP tool calls into Plugin API method calls. For what a method actually does and what it takes, see the Plugin API and the SDK
Last updated on September 20, 2026