@laplace.live/persona-mcp is Persona's official MCP (Model Context Protocol) server. It wraps the Plugin API into standard tools for AI assistants: switch scenes, load and place models, toggle expressions and motions, trigger automations, and capture stage screenshots to verify edits visually.
The server uses the same underlying API as the Web Console and the Stream Deck Plugin. It follows the same authentication model and respects all desktop security boundaries.
Prerequisites
| Requirement | Description |
|---|---|
| MCP Client | Claude Desktop, Claude Code, Cursor, Codex, or any MCP-compatible client |
| Node.js | Version 24 or later (required for npx to execute the package) |
| LAPLACE Persona | Running, with Plugin API enabled |
| API Key | Generated under Settings → Plugin API and passed as PERSONA_TOKEN |
Setup
Add the server definition to your MCP client configuration. Both Claude Desktop (claude_desktop_config.json) and Cursor (mcp.json) use the following format:
{
"mcpServers": {
"persona": {
"command": "npx",
"args": ["-y", "@laplace.live/persona-mcp"],
"env": { "PERSONA_TOKEN": "sk-lp-v1-…" }
}
}
}For Claude Code, add the server with a single command:
claude mcp add persona -e PERSONA_TOKEN=sk-lp-v1-… -- npx -y @laplace.live/persona-mcpEnvironment Variables
| Variable | Description |
|---|---|
PERSONA_TOKEN | The API key token generated in Persona. Required |
PERSONA_ADDRESS | Target instance address; defaults to 127.0.0.1:25034 when omitted. Accepts host, host:port, or a full ws:// URL |
Because MCP clients often launch server processes before Persona is running, the server connects on demand when the first tool call arrives. If the token is missing, Persona is closed, or the key has been revoked, the server returns structured diagnostic errors to guide the assistant rather than exiting.
Once connected, Persona lists Persona MCP (with the client identifier in brackets, developer: LAPLACE) under Connected Clients.
Treat the API token as a credential. An assistant holding this token can switch scenes, load models, modify the stage, and capture stage renders. The server listens only on loopback addresses unless Allow Access on Local Network is enabled.
Tool Reference
Tools are grouped around common tasks (just under thirty in total) rather than exposing a 1:1 wrapper for every raw protocol method, keeping tool selection simple and saving context space. Read-only operations set readOnlyHint, and destructive operations (delete_scene, remove_item, delete_automation, and switch_version) set destructiveHint so supported clients can prompt for confirmation.
| Tool | Description |
|---|---|
get_state | Retrieves application version, capabilities, scene list, and active items with IDs, formats, visibility, placement, and loadError (plus configured pluginFolders on local connections with asset-import) |
capture_stage | Captures the current stage render as an image so vision-capable assistants can check the result |
activate_scene create_scene | Switches to a specified scene, or creates a new empty scene and activates it |
rename_scene delete_scene | Renames a scene, or removes a scene and its layers (the last remaining scene cannot be deleted) |
list_models add_model | Lists available models, adds a model to the stage, or replaces an existing layer in place |
import_asset | Registers a local model or media file into the Inventory via asset.import (asset-import capability; prompts the user on screen if outside plugin folders) |
describe_model | Inspects an item in detail: transform, capabilities, available expressions and motions, and active playback state |
remove_item set_visible | Removes an item from the active scene, or toggles visibility without removing it |
set_placement reset_placement | Modifies position, scale, and rotation, or resets them to defaults; only specified fields update, and unsupported properties are reported as ignored |
set_text | Updates text on a text layer; set transient: true to display temporary text without saving or creating an undo step, or pass text: null to restore saved text |
set_expression | Enables or disables an expression by name; does nothing if already in that state |
play_motion stop_motion | Plays a motion by group and index, or fades out the active motion to return to idle |
list_automations get_automation | Lists automations and model shortcuts, or reads a single automation's full timeline, actions, and triggers (automation-editing capability) |
save_automation delete_automation | Creates or replaces an automation's timeline definition (newly created automations start disabled with no shortcut), or deletes an automation (automation-editing capability) |
describe_automation_kind | Returns the JSON Schema for a specific automation action or trigger kind (or lists all available kinds when omitted) without calling Persona |
run_automation control_automation | Runs an enabled automation from the start by ID, or drives the timeline transport (play, pause, stop, prepare, seek) and returns its run status (automation-transport) |
trigger_hotkey | Triggers an avatar shortcut on any on-stage model |
list_versions save_version | Lists a model's saved versions and unsaved file changes, or saves the model's files as a version with an optional name and notes |
switch_version | Restores the model's files to a saved version and reloads the model |
call_api | General-purpose escape hatch: calls any raw Plugin API method directly and forwards its arguments |
2D item placement is measured in pixels relative to the stage center (+y down) with rotation in radians. 3D items use meters and radians. Coordinate conventions and units are documented in each tool's schema.
The version tools require the model-history capability. Version history must be enabled for a model by the user in the desktop app; the MCP tools do not enable it automatically, and save_version returns invalid-state while it is off. Tool descriptions instruct the assistant to call save_version with a descriptive label before editing a model's bindings, hotkeys, or expressions so changes can be compared or rolled back later. switch_version carries destructiveHint: if switching would overwrite unsaved changes, the call fails so the assistant can ask whether to save them first as a backup version (unsavedChanges: 'save') or discard them ('discard').
Visual Stage Verification
The capture_stage tool uses the underlying stage.capture method to capture the current stage window as a transparent PNG, with a default longest edge of 1024 px (maximum 2048 px) and no upscaling. This requires the desktop app to report the stage-capture capability (available in Persona 0.55.0 and later; earlier versions prompt you to update).
Each capture pauses stage rendering for one frame, so use it to check results after changes rather than polling continuously.
General Invocation: call_api
Features without dedicated tools (such as camera controls, lighting, environment settings, layer effects, 3D props and web layers, tracking sources, lip sync, speech, and global preferences) can be called through call_api by passing the method name and parameters object. Unrecognized method names are forwarded directly, so new Persona API methods work without waiting for an MCP package update.
Invalid parameters return structured errors pointing to the invalid field, and protocol errors include hints showing which tool provides the expected values.
The MCP server acts as a protocol bridge, translating tool calls into Plugin API requests. For method specifications, parameter types, and return values, see the Plugin API and SDK Reference.
Last updated on November 3, 2026