MCP server

Hypercolor ships a Model Context Protocol server so AI agents can drive your lighting through structured tool calls instead of raw REST. It runs inside the daemon and speaks the MCP Streamable HTTP transport, mounted at /mcp on the same :9420 port as everything else.

#The transport at a glance

The server is built on rmcp’s StreamableHttpService. One endpoint handles the whole protocol (tool listing and calls, resource reads, prompt fetches) over HTTP with optional Server-Sent Events for streaming.

The server advertises tools, resources, and prompts in its capabilities and ships instructions that tell agents to read hypercolor://state or call get_status before making changes.

#Enable the server

Add an [mcp] block to your Hypercolor config and restart the daemon. The defaults below match the daemon’s McpConfig:

[mcp]
enabled = true            # off by default; this is the switch
base_path = "/mcp"        # endpoint path under :9420
stateful_mode = true      # session-tracked transport
json_response = false     # SSE streaming responses (set true for plain JSON)
sse_keep_alive_secs = 15  # SSE keepalive interval; 0 disables keepalive

Only enabled = true is required. Everything else has a sane default, so the shortest working config is a single line plus the header.

#Connect a client

Any MCP client that speaks Streamable HTTP can connect at the endpoint above. For Claude Code, point a server entry at it:

{
  "mcpServers": {
    "hypercolor": {
      "type": "streamable-http",
      "url": "http://localhost:9420/mcp"
    }
  }
}

Claude Desktop reaches the same endpoint through an mcp-remote bridge, and Cursor and Zed each have their own config shape. The copy-paste blocks for all of them live on the MCP setup page.

#What the server exposes

The three MCP primitives map cleanly onto Hypercolor’s engine.

graph TD
A[MCP client] -->|tools| T[17 tools: set_effect, get_status, ...]
A -->|resources| R[5 resources: hypercolor://state, devices, ...]
A -->|prompts| P[3 prompts: mood_lighting, troubleshoot, setup_automation]
T --> E[Daemon engine + event bus]
R --> E

Tools are actions and reads. Eight are listed as read_only (list_effects, get_devices, get_status, list_scenes, get_audio_state, get_sensor_data, get_layout, diagnose), and the mutating ones carry idempotent annotations so agents can reason about retries. set_effect, set_color, create_scene, and set_display_face are non-idempotent because repeated calls replace or add state.

Resources are live read-only snapshots the agent can pull for context. The hypercolor://audio resource updates at roughly 10 Hz when audio is active (not per render frame) so it is a summary surface, not a spectrum stream.

Prompts are guided workflows: mood_lighting (vibe to effect), troubleshoot (diagnostics-driven fixes, the only prompt with a required argument: issue), and setup_automation (scenes for external automation).

#Tool catalog

set_effect resolves an effect by exact ID, exact case-insensitive name, or a unique case-insensitive name substring. Scene, zone, layer, device, and display face selectors follow the same deterministic policy. No match or an ambiguous substring returns structured candidate details instead of choosing silently. Color text keeps its separate CSS and natural-language resolver. Scenes are whole-rig configs and zones are flexible canvas partitions; the tools follow that vocabulary exactly.

#Resources

#CLI as the scripting alternative

MCP is the structured-agent path. The hypercolor CLI is the scripting path for the same engine, and it carries a few capabilities MCP does not, notably effect installation and rescan. The CLI exposes three distinct top-level commands that are easy to confuse:

• hypercolor server: operate against the local daemon process
• hypercolor servers: manage multiple known daemon endpoints
• hypercolor service: manage the daemon as a system service

There is no MCP command in the CLI, and there is no install-or-rescan tool over MCP, so a build-and-apply workflow crosses from MCP to the CLI. See CLI scripting for agents and the CLI reference for the full command tree.

#Where to go next

• Agents & MCP overview: the canonical MCP home
• MCP setup: enable it, then configure your client
• Tools reference: every tool’s schema and a worked example
• REST API reference: the surface MCP tools sit on top of