Unilighter connects AI agents to the running console through the Model Context Protocol (MCP) in two ways:

• Local MCP server in Unilighter Desktop: external AI coding assistants and autonomous agents (such as Cursor, Claude Desktop, Google Antigravity, and custom LLM workflows) connect to the desktop application over a local HTTP endpoint.
• WebMCP in the web console: the browser version registers the same tools with the browser, so an AI agent running inside your browser can work with the open project. See WebMCP in the web console below.

Both let an agent inspect, author, and busk live lighting shows in the open project.

What does MCP give me?

MCP lets AI assistants such as Codex, Cursor, Claude Desktop, or other compatible agents connect directly to Unilighter Desktop.

Once connected, the agent can work with the project currently open in Unilighter: inspect fixtures and patching, create scenes and animations, modify node graphs, control devices, and help configure your show using natural-language requests.

Quick start

1. Open Settings → Desktop in Unilighter.
2. In the MCP section, enable Enable local MCP server.
3. Click Copy agent prompt.
4. Paste the copied prompt into your AI assistant.

The prompt contains everything the agent needs to connect to your local Unilighter instance.

You can then ask things like:

Patch four beam fixtures on Universe 1.

Create a warm wash scene at 60% brightness.

Check what is currently controlling channel 17.

If you work in the web console, follow WebMCP in the web console below instead.

The sections below describe the MCP architecture, available tools, security model, and manual connection options in more technical detail.

🌐 WebMCP in the web console

WebMCP is a new browser standard that lets a web page offer tools to an AI agent running in the same browser. The Unilighter web console uses it to provide the same four tools as the local MCP server (unilighter_help, unilighter_invoke, unilighter_troubleshoot, and unilighter_feedback). No URL, token, or configuration file is needed: the agent finds the tools on the open console tab.

Requirements

1. An active Unilighter Pro subscription and a signed-in account for the full tool set.
2. The web console open in a browser that supports WebMCP. Support is currently limited to recent Google Chrome versions.
3. An AI agent or browser extension that calls WebMCP tools on the page.

Without Pro, or when you are signed out, the agent sees only unilighter_help. It answers that the full tools need a signed-in Unilighter Pro account and gives the agent a link to the subscription or sign-in page. The agent can still help you through the regular interface.

If the console loses your sign-in token, full tool calls stop immediately, including documentation-gap reports. A previously cached Pro status does not keep these tools available after sign-out.

Turning WebMCP on and off

1. Open Settings → General in the web console.
2. Find the WebMCP section. It is turned on by default.
3. Use Expose tools to browser AI agents to turn the tools on or off for this browser.

The status line below the switch shows whether the tools are available. If it says This browser does not support WebMCP yet, use another browser or the local MCP server in Unilighter Desktop. When you sign out or the Pro plan ends, the full tools are replaced by the single help tool. Turning the switch off removes all tools.

Working with an agent

• Ask the agent to start with unilighter_help. The first response includes the usage rules that the desktop Copy agent prompt text normally provides.
• The agent works with the project open in that browser tab. Screen changes (context.navigate, *.open) still ask you to confirm in the app.
• unilighter_feedback sends documentation gaps to the Unilighter team instead of writing a local mcp-feedback.jsonl file.

Web console limitations

The web console cannot use features that need Unilighter Desktop, so the agent cannot use them either:

• Art-Net and sACN network output.
• LAN remote control.
• OSC control surfaces.

USB DMX interfaces and MIDI devices work in the web console, but you connect them yourself in Setup; the agent cannot connect hardware. context.get reports host: "web" and the list of unavailable features, so the agent can tell you when a request needs Unilighter Desktop.

🧠 What is Unilighter MCP?

The Model Context Protocol (MCP) is an open standard that connects AI agents to external applications and tool ecosystems.

Unilighter Desktop implements a local Streamable HTTP MCP server on loopback (127.0.0.1). When enabled, an external AI agent can:

• Patch Fixtures: Read fixture profiles, compute DMX footprints, and patch multi-fixture arrays across universes with semantic tags (#Beams, #Washes).
• Compose Lighting Scenes: Dial in dimmers, RGB/CMY color palettes, and moving head positions, or capture live looks into stored scenes.
• Program Complex Animations: Build step chases with tempo-locked beats and author multi-track keyframe timelines with easing curves.
• Wire Node Graphs: Instantiate audio FFT analyzers, LFO generators, and math routing nodes, connecting wires directly into fixture channels.
• Live Busking & Inspection: Read real-time 512-channel DMX output per universe with winning priority sources, and adjust manual override faders at priority 100.

🔒 Security & Architecture Split

The MCP integration is architected with strict security boundaries and human-in-the-loop safety:

1. Loopback & Bearer Token Authentication:

   • The server binds exclusively to IPv4 loopback (127.0.0.1, default port 3847). It never exposes ports to external network interfaces.
   • Every request requires a cryptographically secure Bearer token generated per installation and persisted in local application data (mcp-auth.json).
   • Cross-origin browser requests are strictly filtered by origin headers.

2. Host / Client Separation:

   • Desktop Shell (Electron main process): Acts as a lightweight transport host handling HTTP sessions, JSON-RPC envelopes, and request timeouts (60s).
   • Client App (Vue/Pinia): Owns the business logic, parameter validation, show databases, and live DMX state. Tool calls run through the exact same code paths as physical user clicks.
   • Each MCP connection has its own session. Connecting or disconnecting one agent does not disconnect the others. All agents control the same open project, and tool calls execute one at a time.

3. Human-in-the-Loop Confirmation:

   • Screen navigation operations (context.navigate or *.open) prompt an interactive confirmation modal in the app before switching views.
   • If the operator clicks Cancel, the agent receives a user_declined status code and gracefully stops without retrying in a loop.

🛠️ The 4 Core MCP Tools

Rather than registering hundreds of individual operations that overwhelm an agent's context window, Unilighter provides a clean, hierarchical CLI-style meta-tool interface:

1. unilighter_help

Discovers available modules and operations dynamically.

• Call with no arguments to get the list of all available show modules.
• Call with a specific module path (e.g. {"path": "scenes"}) to list operations.
• Call with a specific operation path (e.g. {"path": "scenes.create"}) to retrieve full argument schemas and typing requirements.

2. unilighter_invoke

Executes an operation by path with structured JSON arguments.

{
  "path": "scenes.create",
  "args": {
    "name": "Warm Sunset Wash",
    "capture": true,
    "priority": 10,
    "fadeTime": 1500
  }
}

When creating a Device Output node through graphs.addNode, omitting data.priority inherits the graph's priority. Supplying data.priority creates a Custom priority override, including when the value is 0. Set data.customPriority to false explicitly to request inheritance even when a priority value is supplied.

3. unilighter_troubleshoot

Provides instant diagnostic guidance and recommended repair workflows when an operation encounters an error or state conflict.

4. unilighter_feedback

Allows agents to report documentation gaps or missing API features for ongoing console improvements. Unilighter Desktop also logs them to userData/mcp-feedback.jsonl; in the web console they are sent to the Unilighter team.

📚 Module Operations Catalog

🚀 Quick Start: Connecting Your AI Agent

Connecting Cursor, Claude Desktop, or custom agent frameworks to Unilighter Desktop takes just a few clicks:

Prerequisites

1. Unilighter Pro Plan: An active Pro subscription is required to unlock the MCP server toggle.
2. Unilighter Desktop App: Download and run the native desktop version on Linux, macOS, or Windows.

1. Enable the MCP Server in Settings

1. Open Unilighter Desktop.
2. Click the Settings icon (⚙️) in the top navigation bar.
3. Locate the MCP section.
4. Toggle Enable local MCP server.
5. Once running, Unilighter displays the active endpoint URL, the Bearer token, and the pre-generated agent prompt.

2. Connect Your Agent

Method A: One-Click Prompt (Zero Manual Config — Recommended)

You don't need to manually write or edit configuration files:

1. In the MCP settings card, click Copy agent prompt (or copy the text directly from the prompt textarea).
2. Paste the prompt directly into your AI assistant's chat (Cursor Agent, Claude Desktop, Antigravity, etc.).
3. The prompt automatically instructs the agent:
   • How to connect to the Streamable HTTP endpoint (http://127.0.0.1:3847/mcp).
   • The private Bearer authentication token.
   • The hierarchical unilighter_help discovery workflow and parameter rules.
4. The AI agent configures its connection automatically and starts working immediately!

Method B: Manual Configuration (Optional)

If your environment requires static configuration files or command-line setup, use the verified configurations below:

1. Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "unilighter": {
      "url": "http://127.0.0.1:3847/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

2. OpenAI Codex CLI & Operator: Codex natively supports Streamable HTTP MCP servers via the built-in codex mcp command:

# Add server via CLI
export UNILIGHTER_MCP_TOKEN="YOUR_TOKEN_HERE"
codex mcp add unilighter --url "http://127.0.0.1:3847/mcp" --bearer-token-env-var UNILIGHTER_MCP_TOKEN

# Verify connection
codex mcp list

Or define it directly in your global ~/.codex/config.toml (or project .codex/config.toml):

[mcp_servers.unilighter]
url = "http://127.0.0.1:3847/mcp"
bearer_token_env_var = "UNILIGHTER_MCP_TOKEN"

3. Google Antigravity (IDE & SDK): For Antigravity sessions, add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "unilighter": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:3847/mcp"
      ]
    }
  }
}

Or in autonomous Python agent workflows using google-antigravity-sdk:

from google.antigravity import Agent, LocalAgentConfig, types

mcp_servers = [
    types.McpStreamableHttpServer(
        name="unilighter",
        url="http://127.0.0.1:3847/mcp",
        headers={"Authorization": "Bearer YOUR_TOKEN_HERE"},
    )
]

config = LocalAgentConfig(mcp_servers=mcp_servers)
async with Agent(config) as agent:
    response = await agent.chat("Turn on all warm wash fixtures at 70% dimmer.")

4. Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "unilighter": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:3847/mcp",
        "--header",
        "Authorization:Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

Reconnecting After a Restart

Restarting Unilighter Desktop, reloading its console, or disabling the local MCP server ends its active sessions. Once the server is running again, the agent must establish a new session. Requests using a previous session receive HTTP 404, allowing compatible agents to initialize again. If your agent does not reconnect automatically, reconnect the server in the agent or start a new agent session, then call unilighter_help.

Keep the URL and Bearer token from Settings → Desktop → MCP. Do not manually configure a fixed Mcp-Session-Id: the agent obtains it during initialization and sends it with subsequent requests. Older clients that omit this header work only while exactly one server session is active; with several sessions, those requests receive HTTP 400 because the server cannot identify the connection.

3. Start Conversational Lighting Design

Once connected, prompt your agent with natural requests:

• "Patch 4 Chauvet Rogue R2 Beams starting at address 1 on Universe 1, and tag them #Beams."
• "Create a static scene called 'Cyan Focus' with all wash lights in cyan at 80% dimmer, and capture current pan/tilt positions."
• "Build a 4-step chase that alternates odd and even beam fixtures in white and amber locked to the master BPM."
• "Inspect Universe 1 to see which cues are currently holding dimmer output on channel 17."

Repair fixture appearance without reprogramming

Describe the problem directly: “Four heads are arranged in a square instead of a bar” or “This B-Eye appears as two fixtures.” The agent can inspect Emitter Layout, preview a correction and change only visualizer settings. Both Unilighter Desktop and WebMCP expose the same operations.

• fixtures.getVisualizer reads effective emitters, Head bindings, inherited settings, warnings and a revision.
• fixtures.previewVisualizer validates a patch and returns proposed geometry without saving.
• fixtures.updateVisualizer applies that patch with expectedRevision, then returns the effective saved state.

Each call names scope: profile or mode requires fixture id and selected mode; device requires deviceId. Prefer device scope for one installed instance. Profile and mode changes affect other devices unless overridden. Null patch properties remove only those overrides. Coordinates are local renderer XYZ meters (Y up); rotations are XYZ degrees. Discover the complete patch schema through unilighter_help for fixtures.previewVisualizer.

For example, after reading the target and its revision, preview a patch {"emitterLayout":{"type":"linear","spacing":0.22}}. Here 0.22 is an example center spacing, not a manufacturer measurement. Apply only after checking the target, warnings and any estimates, then read back. Unknown Heads, invalid values, unsupported rectangular pixel segmentation and stale edits are rejected.

Visual repairs do not require fixtures.setChannels, devices.update, scene playback or live Pan/Tilt. Optional drawings or profile files provide reference evidence; they must not replace an existing DMX personality merely to change geometry. If the installed version lacks these operations, use the normal editor workflow.