Home Assistant MCP Server

Official

by homeassistant-ai

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Manage Assist Pipeline

ha_manage_pipeline

Destructive

Manage Home Assistant Assist pipelines and run sentences through Assist to test and execute voice commands.

Instructions

Manage Home Assistant Assist pipelines.

Use action='list' to discover pipeline IDs, action='get' to inspect one pipeline, action='create' or action='update' to write pipeline settings, action='set_preferred' to choose the preferred pipeline, and action='process' to run a sentence through Assist.

action='process' sends the sentence straight to Assist's conversation agent, so a matched intent executes: it turns on the light rather than reporting that it would. Its result carries response_type ('action_done', 'query_answer' or 'error') and, on an error, error_code such as 'no_intent_match' — Assist declining a sentence is an answer, not a tool failure, so inspect those fields rather than expecting a raised error. Use ha_call_service to act on an entity directly; use this to test what Assist itself understands. When the built-in agent answers, a matching conversation trigger runs its automation: that agent checks its sentence triggers before it matches intents, so this is not limited to intents. Even with pipeline_id, the sentence goes to the agent directly. So with an agent other than the built-in one, neither sentence triggers nor prefer_local_intents apply — a full pipeline run is what adds those for other agents.

EXAMPLES:

Get the preferred pipeline: ha_manage_pipeline(action="get", pipeline_id="preferred")
Create by cloning a pipeline: ha_manage_pipeline(action="create", base_pipeline_id="preferred", name="Local Assist", conversation_engine="conversation.local_llm")
Update the agent and clear the TTS voice: ha_manage_pipeline(action="update", pipeline_id="preferred", conversation_engine="conversation.local_llm", tts_voice="")
Run a sentence through one pipeline's agent: ha_manage_pipeline(action="process", sentence="turn on the kitchen light", pipeline_id="preferred")
Continue a conversation: ha_manage_pipeline(action="process", sentence="and the hallway?", conversation_id="")

Non-nullable fields such as name, language, conversation_language, and conversation_engine must be omitted or non-empty.

If a Claude Desktop user gets a 4-minute timeout with no result on this call, read the target back before repeating it, and tell them to wait a few seconds before clicking the manual-approve button, as clicking it too quickly is known to cause hangs in Claude Desktop. This workaround is specific to Claude Desktop.

Input Schema

Name	Required	Description
`name`	No	Pipeline display name. Required when action='create'.
`action`	Yes	Pipeline operation: list, get, create, update, set_preferred, or process.
`agent_id`	No	For process only, the conversation agent entity ID to answer, e.g. 'conversation.home_assistant'. Overrides the agent taken from pipeline_id; omit both for the default agent.
`language`	No	Pipeline language, e.g. 'en'. For process, the language to recognise the sentence in.
`sentence`	No	Natural-language command to run through Assist. Required when action='process'.
`tts_voice`	No	Text-to-speech voice. Pass empty string to clear.
`stt_engine`	No	Speech-to-text engine. Pass empty string to clear.
`tts_engine`	No	Text-to-speech engine. Pass empty string to clear.
`pipeline_id`	No	Assist pipeline ID. Required for get, update, and set_preferred. Optional for process, where it selects the conversation agent and language that pipeline is configured with.
`stt_language`	No	Speech-to-text language. Pass empty string to clear.
`tts_language`	No	Text-to-speech language. Pass empty string to clear.
`wake_word_id`	No	Wake-word ID. Pass empty string to clear.
`make_preferred`	No	For create/update only, also set the resulting pipeline as preferred. Ignored for other actions.
`conversation_id`	No	For process only, the conversation to continue. Returned in the response so follow-up sentences keep their context.
`base_pipeline_id`	No	Pipeline ID to clone when creating. Omit to clone the preferred pipeline. Ignored for non-create actions.
`wake_word_entity`	No	Wake-word entity ID. Pass empty string to clear.
`conversation_engine`	No	Conversation agent entity ID or engine ID. Required when action='create'.
`prefer_local_intents`	No	Whether Home Assistant local intents should be preferred before the conversation engine.
`conversation_language`	No	Conversation language, usually '*'.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv8.6.0Oct 1, 2026

changedInput schema / properties / make_preferred / description

Previous value: -"For create/update only, also set the resulting pipeline as preferred with an extra websocket call. Ignored for other actions."New value: +"For create/update only, also set the resulting pipeline as preferred. Ignored for other actions."

changedInput schema / properties / sentence / description

Previous value: -"Natural-language command to run through Assist. Required when action='process'. A matched intent executes, and with the built-in agent a sentence matching a conversation trigger runs that automation."New value: +"Natural-language command to run through Assist. Required when action='process'."

Changed7 schema fields changedv8.3.0Aug 19, 2026

changedInput schema / properties / action / description

Previous value: -"Pipeline operation: list, get, create, update, or set_preferred."New value: +"Pipeline operation: list, get, create, update, set_preferred, or process."

changedInput schema / properties / action / enum

Previous value: -[
-  "list",
-  "get",
-  "create",
-  "update",
-  "set_preferred"
-]New value: +[
+  "list",
+  "get",
+  "create",
+  "update",
+  "set_preferred",
+  "process"
+]

addedInput schema / properties / agent_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "For process only, the conversation agent entity ID to answer, e.g. 'conversation.home_assistant'. Overrides the agent taken from pipeline_id; omit both for the default agent."
+}

addedInput schema / properties / conversation_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "For process only, the conversation to continue. Returned in the response so follow-up sentences keep their context."
+}

changedInput schema / properties / language / description

Previous value: -"Pipeline language, e.g. 'en'."New value: +"Pipeline language, e.g. 'en'. For process, the language to recognise the sentence in."

changedInput schema / properties / pipeline_id / description

Previous value: -"Assist pipeline ID. Required for get, update, and set_preferred."New value: +"Assist pipeline ID. Required for get, update, and set_preferred. Optional for process, where it selects the conversation agent and language that pipeline is configured with."

addedInput schema / properties / sentence

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Natural-language command to run through Assist. Required when action='process'. A matched intent executes, and with the built-in agent a sentence matching a conversation trigger runs that automation."
+}

First observedv7.14.2Jul 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false. The description goes well beyond that: action='process' actually executes the matched intent (turning on a light rather than reporting), errors arrive as response_type='error' with error_code such as 'no_intent_match' rather than a raised exception, and conversation_id must be threaded to preserve context. It even discloses a Claude Desktop-specific timeout/hang workaround.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is front-loaded with the action taxonomy, then behavior, then examples, then edge-case caveats — a sensible progression, and nearly every sentence carries information. It is verbose for a description though, and the paragraph on sentence triggers versus intents ('that agent checks its sentence triggers before it matches intents, so this is not limited to intents') restates the same point in adjacent clauses, costing readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 19 parameters, an output schema, and full annotation coverage, this is a complex tool, and the description covers everything an agent needs: per-action requirements, the 'preferred' alias, empty-string clearing, error-shape expectations, and conversation continuation. Nothing required to invoke it correctly is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is already documented there, so the baseline is 3. The description still adds meaning the schema does not: the 'preferred' sentinel for pipeline_id, empty-string clearing conventions shown in examples (tts_voice=""), the rule that non-nullable fields such as name/language/conversation_engine must be omitted or non-empty, and base_pipeline_id cloning behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Manage Home Assistant Assist pipelines') and then enumerates all six actions with their distinct semantics (list/get/create/update/set_preferred/process). It explicitly contrasts itself with the sibling ha_call_service, so an agent can route correctly without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Every action has a stated use, and the boundary against the nearest alternative is explicit: 'Use ha_call_service to act on an entity directly; use this to test what Assist itself understands.' The create/update/process examples show concrete invocation contexts, and the note on preferring a full pipeline run for non-built-in agents clarifies when this tool alone is insufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server