Discover the Hue Bridge IP on the local network via https://discovery.meethue.com or mDNS; accept the self-signed bridge TLS certificate (or pin its public key) since the bridge uses a Philips-issued certificate not in the standard trust store
Create an application key by pressing the physical link button on the bridge within 30 seconds, then POST to https://<bridge-ip>/api with body {"devicetype":"my_app#my_device","generateclientkey":true}; save the returned username (hue-application-key) and clientkey
Set the hue-application-key header on all subsequent API v2 requests; list all light resources with GET https://<bridge-ip>/clip/v2/resource/light to get their UUIDs
Control a light by PUT to https://<bridge-ip>/clip/v2/resource/light/<uuid> with a JSON body; for example {"on":{"on":true},"dimming":{"brightness":80}} to turn on at 80% brightness
Subscribe to real-time events via the Server-Sent Events (SSE) endpoint: GET https://<bridge-ip>/eventstream/clip/v2 with the hue-application-key header; events arrive as JSON arrays describing state changes across all resources
For color control, use the color.xy object (CIE 1931 xy color space) or the color_temperature.mirek field for whites; check each light's color.gamut_type to know which xy values are valid for that bulb model
Known gotchas
The CLIP API v2 uses resource UUIDs, not the integer IDs of the older v1 API; hardcoding v1 integer IDs will break if the bridge firmware is updated and the mapping changes
The bridge self-signed TLS certificate must be accepted manually or its public key pinned; using standard certificate validation without pinning will cause all HTTPS requests to fail with a certificate error
The SSE eventstream connection drops after an inactivity period and after bridge restarts; implement automatic reconnection with exponential backoff and re-fetch full state on reconnect to avoid missing events
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp