PixDrive Studio ships with a built-in MCP server (Model Context Protocol) that lets you have AI assistants like Claude Desktop, Cursor, or your own scripts control your light show — start effects, change parameters live, play sequences, run Lua scripts.
The server runs locally on 127.0.0.1 and is disabled by default. You enable it manually and can secure it with a password.
1. What is MCP?
Model Context Protocol is an open standard that lets LLM clients call the tools of a local program. PixDrive Studio provides ~20 tools (effects, devices, sequencer, scripts). This lets an assistant say, for example:
“Make the plasma effect slow in the background, and layer an audio-reactive strobe on top.”
And the client translates that into a series of tool calls.
2. Enabling the Server
- Open Settings (gear icon in the toolbar)
- Scroll to the MCP Server section
- Flip the Server active switch
- Restart the app — the TCP listener is only bound at startup
After the restart, the server is available at:
In the settings dialog you can copy the URL with one click.
3. Setting a Password (recommended)
Without a password, the server accepts any connection from localhost. That’s fine for single-user setups, but as soon as other processes are running on the machine (or you don’t fully trust the machine), you should set a password:
- Settings → MCP Server → Password
- Enter a password, click Save
- Active immediately — no restart needed
The password is never stored in plain text — PixDrive Studio only stores a salted SHA-256 hash in mcp.json. If you forget it, just set a new one.
Clients send the password as a Bearer token in the HTTP header:
Authorization: Bearer <your-password>
4. Client Configuration
Claude Desktop
Open the config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add an entry:
json
{
"mcpServers": {
"pixdrive": {
"transport": {
"type": "streamableHttp",
"url": "http://127.0.0.1:9847/mcp",
"headers": {
"Authorization": "Bearer YOUR-PASSWORD"
}
}
}
}
}If you have no password, omit the headers block. Restart Claude Desktop — PixDrive appears in the tool list.
Cursor / Continue / other MCP clients
Most clients likewise expect an HTTP MCP URL plus optional headers. Enter:
- URL: http://127.0.0.1:9847/mcp
- Header: Authorization: Bearer YOUR-PASSWORD
Exact paths vary — see the documentation of the respective tool.
Generic HTTP test
Quick connection test with curl:
curl -i -H "Authorization: Bearer YOUR-PASSWORD" \
-H "Content-Type: application/json" \
-X POST http://127.0.0.1:9847/mcp \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'200 OK response → connection works. 401 Unauthorized → password wrong or missing.
5. Available Tools (overview)
| Area | Tools |
|---|---|
| Effects | list_effects, start_effect, stop_effect, set_parameter, get_effect_parameters |
| Scripts | start_script_effect, validate_script, get_script_guide |
| Sequencer | play_sequence, pause_sequence, stop_sequence, set_sequence_position |
| Devices | list_devices, add_device, remove_device, add_fixture, apply_device_config |
Full descriptions are provided by the server itself via tools/list (standard MCP method).
Tip: Before an assistant generates a Lua script, it should call get_script_guide once — that tool provides the complete script API.
6. Demo and Trial Versions
In demo mode (no license), the MCP server does not start. A valid PixDrive Studio license is required.
7. Security Notes
- The server binds exclusively to 127.0.0.1 — no remote access over the network.
- Password comparison runs in constant time, salted, and re-salted each time it’s set.
- The token header protects against local foreign processes. It does not protect against an attacker who is already running code under your account.
- If you’re not using the server: disable it.
8. Troubleshooting
“Connection refused” in the client → server not enabled, app not restarted, or port 9847 occupied by something else. Check the log (Help → View Logs) for the line MCP server started on … or failed to bind port.
“401 Unauthorized” → password is set, but the client sends a wrong or missing Authorization header. Re-set the password in the settings dialog and update it in the client config.
“MCP server disabled via settings, not starting” in the log → the switch is off. Enable it and restart the app.
Tools don’t appear in the client, but the connection works → the client doesn’t support the MCP tools/list call, or it cached an old list. Restart the client.