PixDrive Studio MCP Setup – Documentation

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:

http://127.0.0.1:9847/mcp

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.