@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 operates over the same underlying API as the Web Console and the Stream Deck Plugin. It adheres strictly to the existing authentication model and never bypasses desktop application 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 schema:
{
"mcpServers": {
"persona": {
"command": "npx",
"args": ["-y", "@laplace.live/persona-mcp"],
"env": { "PERSONA_TOKEN": "sk-lp-v1-…" }
}
}
}For Claude Code, configure 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 |
The server employs lazy connection initialization: because MCP clients often launch server processes before Persona is started, the WebSocket connection is deferred until the first tool invocation. 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 crashing the process.
Once connected, Persona displays a Persona MCP entry (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 inspect stage renders. The server listens exclusively on loopback addresses unless Allow Access on Local Network is explicitly enabled.
Tool Reference
Tools are structured around high-frequency operational tasks (around twenty in total) rather than exposing a 1:1 wrapper for every raw protocol method, reducing model decision overhead and conserving context space. All read-only operations specify readOnlyHint, and destructive operations (such as delete_scene and remove_item) declare destructiveHint to trigger user confirmation in supported clients.
| Tool | Description |
|---|---|
get_state | Retrieves application version, capabilities, scene list, and active items with IDs, formats, visibility, and placement; ideal initial query |
capture_stage | Captures the current stage render as an image, enabling vision-capable assistants to verify results |
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 |
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 removal |
set_placement reset_placement | Modifies position, scale, and rotation, or resets them to defaults; only specified fields update, and unsupported properties report 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; idempotent if the state is unchanged |
play_motion stop_motion | Plays a motion by group and index, or fades out the active motion to return to idle |
list_automations run_automation | Lists automations and model shortcuts, or executes an automation by ID |
trigger_hotkey | Triggers an avatar shortcut on any on-stage model |
call_api | General-purpose escape hatch: calls any raw Plugin API method directly with forwarded arguments |
2D item placement is defined in pixels relative to the stage center (+y down) with rotation in radians. 3D items use meters and radians. All coordinate conventions and units are fully declared in tool schemas.
Visual Stage Verification
The capture_stage tool relies on the underlying stage.capture method: it captures the current stage window as a PNG with transparency, with a default longest edge of 1024 px (maximum 2048 px) and no upscaling. This requires the application to declare the stage-capture capability (supported in Persona 0.55.0 and later; earlier versions prompt the assistant to update).
Each screen capture halts stage rendering for one frame, so it should be invoked selectively for verification rather than polled continuously.
General Invocation: call_api
Features not covered by dedicated tools — camera controls, lighting, environment settings, layer effects, 3D props and web layers, tracking sources, lip sync, speech, and global preferences — can be accessed via call_api: supply the method name and parameters object. Unrecognized method names are forwarded transparently, allowing newer Persona features to be called immediately without waiting for MCP package releases.
Invalid parameters return structured errors indicating the offending field, and protocol-level errors include remediation hints indicating which tool supplies the expected values.
The MCP server functions as a protocol bridge, translating tool calls into underlying Plugin API requests. For method specifications, parameter types, and return values, refer to the Plugin API and SDK Reference.
Last updated on October 15, 2026