Philips Hue

Introduction

The Philips Hue integration connects your Attlaz workspace to a Hue bridge so flows (and MCP-connected AI agents) can read light state and control lights — turn on/off, set brightness, change colour, set colour temperature.

The integration uses the Hue Remote API (cloud), so flows run from any environment; the bridge does not need to be on the same network as the runner.

Prerequisites

• A Philips Hue bridge v2 (the square model, white) linked to a meethue.com account. Older round v1 bridges are not supported by the Remote API.
• At least one light paired with the bridge.
• Physical access to the bridge during the first authentication (for the link-button step — see below).

Connecting

1. In the Web App, create a new Philips Hue adapter connection on the project where you want the integration available.
2. Open the connection's Settings tab.
3. Click Authenticate. A popup opens to meethue.com — sign in with the account that owns your bridge and approve the requested access.
4. The popup closes automatically when authentication completes and the connection is ready to use.

Behind the scenes, the authenticate step does three things in one flow:

• Performs an OAuth handshake against the Hue Remote API to obtain an access token.
• Remotely activates the bridge's link button (no physical press needed — the OAuth-authenticated remote activation counts as a press).
• Registers Attlaz as an application on the bridge and stores the resulting application key alongside the OAuth token. Both are needed for any subsequent API call.

You do not need to enter any credentials manually. Both the OAuth token and the application key are stored encrypted on the platform and can be revoked at any time from the connection settings page.

Re-authenticating

If you ever revoke the connection or the OAuth token expires past its refresh window, just click Authenticate again. The flow is idempotent — it will activate a new application key on the bridge without affecting any other apps you've paired with it.

Available operations

Once connected, the Hue adapter exposes four operations — usable from flows and from any MCP-connected AI agent:

Operation	What it does
listLights	Returns every controllable light on the bridge with its current state (on/off, brightness, colour, colour temperature) and capability flags (dimmable, supportsColor, supportsColorTemperature). Start any Hue workflow here — the id it returns is what setLightState / getLightState expect.
getLightState	Reads the state of one specific light by id. Use when you need a fresh read after a setLightState call; otherwise prefer listLights.
setLightState	Changes a light's state. Accepts any combination of on, brightness (0–100), colour (color: {r, g, b} / colorHex: "#ff0000" / colorXy: {x, y}), colour temperature (colorTemperature in mirek / colorTemperatureKelvin), and transitionMs for smooth fades. Omitted fields are left unchanged on the bulb.
listDevices	Returns all hardware connected to the bridge — bridges, lights, sensors, accessories. Use for hardware inventory questions; for controllable lights specifically, use listLights instead.

Notes and limitations

• Capability flags matter. Not every bulb supports every feature. Check supportsColor / supportsColorTemperature / dimmable from listLights before sending colour or brightness — the bridge silently ignores unsupported fields rather than returning an error.
• Mutually exclusive colour formats. Colour (RGB/hex/xy) and colour temperature (mirek/Kelvin) cannot both be applied to a Hue bulb at the same time — the bridge uses last-write-wins. Pick one per call.
• brightness: 0 is not the same as on: false. Brightness 0 sets the bulb to minimum visible level; it does not turn it off. Use on: false to actually turn a bulb off.
• No reachable flag yet. Hue v2 keeps reachability on a separate zigbee_connectivity resource that requires a multi-step join. If your flow needs to skip unreachable bulbs today, attempt the operation and catch the error.

Troubleshooting

Symptom	Likely cause
"Hue application key not configured" when invoking an operation	First-time authentication didn't complete — try Authenticate again. Make sure your bridge is reachable from meethue.com (i.e. the bridge has an internet connection and is registered with the Hue cloud).
"Hue link button activation failed" during authentication	The bridge rejected the remote link-button request. Power-cycle the bridge and retry. If it still fails, contact support — Hue rate-limits link-button activations per bridge.
Colour command appears to do nothing	The bulb may be white-only — check supportsColor: false in listLights. The bridge silently ignores unsupported colour input.