MCP

Homecast provides an MCP endpoint that AI assistants use to read and control smart home devices.

Endpoint: https://api.homecast.cloud/mcp

Transport: Streamable HTTP (GET, POST, DELETE)

Authentication

MCP supports two authentication methods:

Method	Setup	Best for
OAuth 2.1	Auto-discovered via `/.well-known/oauth-authorization-server`	MCP clients with OAuth support (Claude Desktop, etc.)
Access Token	`Authorization: Bearer hc_...` header	Clients without OAuth

See the Authentication reference for details on both.

Tools

get_state

Read the current state of all accessible devices. Returns a hierarchical view of homes, rooms, and accessories.

Parameter	Type	Required	Description
`filter_by_home`	string	No	Filter to a specific home
`filter_by_room`	string	No	Filter to a specific room
`filter_by_type`	string	No	Filter by device type (e.g., `lightbulb`)
`filter_by_name`	string	No	Filter by device name

Annotations: Read-only tool. Does not modify device state.

set_state

Control one or more devices by setting characteristic values.

Parameter	Type	Required	Description
`updates`	array	Yes	List of device updates

Each update object:

Field	Type	Required	Description
`home`	string	Yes	Home name
`room`	string	Yes	Room name
`accessory`	string	Yes	Accessory name
`on`	boolean	No	Power state
`brightness`	integer	No	Brightness 0–100
`hue`	integer	No	Color hue 0–360
`saturation`	integer	No	Color saturation 0–100
`color_temp`	integer	No	Color temperature (mireds)
`active`	boolean	No	Active state
`heat_target`	float	No	Heating target temperature
`cool_target`	float	No	Cooling target temperature
`hvac_mode`	string	No	`off`, `heat`, `cool`, `auto`
`lock_target`	integer	No	`1` (lock), `0` (unlock)
`alarm_target`	integer	No	Security alarm state
`speed`	integer	No	Fan speed 0–100
`volume`	integer	No	Speaker volume 0–100
`mute`	boolean	No	Speaker mute
`target`	integer	No	Position 0–100

Annotations: Mutating tool. Requires mcp:write scope or control home permission.

run_scene

Execute a HomeKit scene by name.

Parameter	Type	Required	Description
`home`	string	Yes	Home name
`name`	string	Yes	Scene name

Annotations: Mutating tool. Requires mcp:write scope or control home permission.

OAuth scopes

Scope	Permissions
`mcp:read`	`get_state` only
`mcp:write`	`get_state`, `set_state`, `run_scene`
`mcp:admin`	Full access including management

Client configuration

With OAuth (recommended)

json

{
  "mcpServers": {
    "homecast": {
      "type": "url",
      "url": "https://api.homecast.cloud/mcp"
    }
  }
}

The client discovers OAuth endpoints automatically and prompts for authorization.

With access token

json

{
  "mcpServers": {
    "homecast": {
      "type": "url",
      "url": "https://api.homecast.cloud/mcp",
      "headers": {
        "Authorization": "Bearer hc_your_token_here"
      }
    }
  }
}

For a step-by-step setup guide, see Connect an AI Assistant.

MCP ​

Authentication ​

Tools ​

get_state ​

set_state ​

run_scene ​

OAuth scopes ​

Client configuration ​

With OAuth (recommended) ​

With access token ​

MCP