ha-mcp-dev 7.13.0.dev1973__tar.gz → 7.13.0.dev1977__tar.gz

{ha_mcp_dev-7.13.0.dev1973/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.13.0.dev1977}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.13.0.dev1973
+Version: 7.13.0.dev1977
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -118,6 +118,7 @@ These run the server outside Home Assistant — useful for **Container** / **Cor
 - **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
 - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).
 - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant.
+- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, Google, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
 
   > ⚠️ **stdio has known transport issues.** The stdio transport has connection problems that streamable HTTP does not ([#1713](https://github.com/homeassistant-ai/ha-mcp/issues/1713)). It is recommended only for demo/testing tinkering — for a real setup, use the custom component or an HTTP method above.
 

{ha_mcp_dev-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1977}/README.md

@@ -85,6 +85,7 @@ These run the server outside Home Assistant — useful for **Container** / **Cor
 - **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
 - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).
 - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant.
+- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, Google, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
 
   > ⚠️ **stdio has known transport issues.** The stdio transport has connection problems that streamable HTTP does not ([#1713](https://github.com/homeassistant-ai/ha-mcp/issues/1713)). It is recommended only for demo/testing tinkering — for a real setup, use the custom component or an HTTP method above.
 

{ha_mcp_dev-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1977}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.13.0.dev1973"
+version = "7.13.0.dev1977"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's
@@ -59,6 +59,7 @@ hamcp-test-env = "tests.test_env_manager:main"
 ha-mcp-web = "ha_mcp.__main__:main_web"
 ha-mcp-sse = "ha_mcp.__main__:main_sse"
 ha-mcp-oauth = "ha_mcp.__main__:main_oauth"
+ha-mcp-oidc = "ha_mcp.__main__:main_oidc"
 
 [tool.setuptools]
 package-dir = {"" = "src", "tests" = "tests"}

{ha_mcp_dev-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1977}/src/ha_mcp/__main__.py

@@ -979,6 +979,39 @@ def _healthz_enabled() -> bool:
     return os.getenv("MCP_HEALTHZ", "").strip().lower() in ("1", "true", "yes", "on")
 
 
+def _oidc_verify_id_token_enabled() -> bool:
+    """True when OIDC_VERIFY_ID_TOKEN opts in to ID-token verification.
+
+    Off by default: FastMCP's OIDCProxy verifies the access token as a JWT,
+    which works for providers like Authentik and Keycloak. Providers that
+    issue opaque access tokens (Google always; Auth0 without an API
+    audience) need ``verify_id_token=True`` so FastMCP verifies the ID token
+    instead.
+    """
+    return os.getenv("OIDC_VERIFY_ID_TOKEN", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def _oidc_allowed_client_redirect_uris() -> list[str] | None:
+    """Parse OIDC_ALLOWED_CLIENT_REDIRECT_URIS into a list, or None if unset.
+
+    Comma-separated list of redirect URI patterns FastMCP's OIDCProxy will
+    accept from dynamically-registered clients. With no allow-list set,
+    FastMCP still validates a client's redirect URI against that same
+    client's own registered redirect URIs — the exposure is that open DCR
+    lets an attacker register their own client with their own redirect URI;
+    internet-facing deployments should set this to constrain what any
+    dynamically-registered client may register in the first place.
+    """
+    raw = os.getenv("OIDC_ALLOWED_CLIENT_REDIRECT_URIS", "")
+    uris = [uri.strip() for uri in raw.split(",") if uri.strip()]
+    return uris or None
+
+
 def register_browser_landing(
     mcp_instance: "FastMCP | _DeferredMCP",
     path: str,
@@ -1225,5 +1258,192 @@ async def _run_oauth_server(
     )
 
 
+def main_oidc() -> None:
+    """Run server with OIDC authentication over HTTP.
+
+    This mode enables authentication via an external OIDC provider
+    (Authentik, Keycloak, Auth0, Google, etc.). All authenticated users
+    share the same Home Assistant instance via the configured credentials.
+
+    Unlike OAuth mode which collects per-user HA credentials via a consent form,
+    OIDC mode is purely an access gate — users authenticate through the OIDC provider,
+    then all requests use the shared HA credentials from environment variables.
+
+    Environment:
+    - OIDC_CONFIG_URL (required): OIDC discovery URL (.well-known/openid-configuration)
+    - OIDC_CLIENT_ID (required): OAuth client ID registered with your OIDC provider
+    - OIDC_CLIENT_SECRET (required): OAuth client secret from your OIDC provider
+    - MCP_BASE_URL (required): Public HTTPS URL where this server is accessible
+    - HOMEASSISTANT_URL (required): Home Assistant instance URL
+    - HOMEASSISTANT_TOKEN (required): Home Assistant long-lived access token or supervisor token
+    - OIDC_JWT_SIGNING_KEY (optional): Secret key for signing FastMCP JWTs. Sessions
+      persist across restarts by default (the key is derived from OIDC_CLIENT_SECRET);
+      set this to decouple the signing key from the client secret. Generate with:
+      python -c "import secrets; print(secrets.token_urlsafe(32))"
+    - OIDC_ALLOWED_CLIENT_REDIRECT_URIS (optional): Comma-separated list of redirect URI
+      patterns accepted from dynamically-registered clients. Strongly recommended for
+      internet-facing deployments.
+    - OIDC_VERIFY_ID_TOKEN (optional, default: false): Set true for providers that issue
+      opaque access tokens (e.g. Google, or Auth0 without an API audience).
+    - OIDC_AUDIENCE (optional): Expected `aud` claim for IdP-issued access tokens.
+      Without it (and with OIDC_VERIFY_ID_TOKEN off), FastMCP's JWT verifier checks
+      issuer, signature, and expiry but not audience. With OIDC_VERIFY_ID_TOKEN=true,
+      verification pins `aud` to OIDC_CLIENT_ID instead and this value is only
+      forwarded to the IdP's authorize/token endpoints (it is what makes Auth0
+      issue JWT rather than opaque access tokens).
+    - MCP_HOST (optional, default: "0.0.0.0"; set 127.0.0.1 to restrict to loopback
+      behind a same-host reverse proxy)
+    - MCP_PORT (optional, default: 8086)
+    - MCP_SECRET_PATH (optional, default: "/mcp")
+    - LOG_LEVEL (optional, default: INFO)
+    """
+    # Configure logging for OIDC mode (force=True needed since logging may already be configured)
+    log_level = os.getenv("LOG_LEVEL", "INFO").upper()
+    _setup_logging(log_level, force=True)
+    for logger_name in ["ha_mcp", "ha_mcp.auth", "ha_mcp.auth.provider"]:
+        logging.getLogger(logger_name).setLevel(getattr(logging, log_level))
+    logger.info(f"OIDC mode logging configured at {log_level} level")
+    _log_startup_version()
+
+    # Validate HA credentials (OIDC mode needs them — unlike OAuth mode)
+    from ha_mcp.config import get_settings
+
+    settings = get_settings()
+    _validate_standard_credentials(settings)
+
+    # Validate OIDC-specific env vars
+    oidc_config_url = os.getenv("OIDC_CONFIG_URL")
+    oidc_client_id = os.getenv("OIDC_CLIENT_ID")
+    oidc_client_secret = os.getenv("OIDC_CLIENT_SECRET")
+    base_url = os.getenv("MCP_BASE_URL")
+
+    missing = []
+    if not oidc_config_url:
+        missing.append("OIDC_CONFIG_URL")
+    if not oidc_client_id:
+        missing.append("OIDC_CLIENT_ID")
+    if not oidc_client_secret:
+        missing.append("OIDC_CLIENT_SECRET")
+    if not base_url:
+        missing.append("MCP_BASE_URL")
+
+    if missing:
+        logger.error(
+            f"Missing required environment variables for OIDC mode: {', '.join(missing)}"
+        )
+        logger.error(
+            "OIDC mode requires an external OIDC provider (Authentik, Keycloak, Auth0, etc.)"
+        )
+        sys.exit(1)
+
+    assert oidc_config_url is not None
+    assert oidc_client_id is not None
+    assert oidc_client_secret is not None
+    assert base_url is not None
+
+    host, port, path = _get_http_runtime(default_port=8086)
+
+    _run_entrypoint(
+        _run_oidc_server(
+            config_url=oidc_config_url,
+            client_id=oidc_client_id,
+            client_secret=oidc_client_secret,
+            base_url=base_url,
+            host=host,
+            port=port,
+            path=path,
+        ),
+        "OIDC server",
+    )
+
+
+async def _run_oidc_server(
+    config_url: str,
+    client_id: str,
+    client_secret: str,
+    base_url: str,
+    host: str,
+    port: int,
+    path: str,
+) -> None:
+    """Run the OIDC-authenticated MCP server.
+
+    Unlike OAuth mode which uses OAuthProxyClient for per-user credential routing,
+    OIDC mode uses the standard HomeAssistantClient with shared credentials.
+    OIDC is purely an access gate — all authenticated users share the same HA instance.
+
+    Args:
+        config_url: OIDC discovery URL (.well-known/openid-configuration)
+        client_id: OAuth client ID from the OIDC provider
+        client_secret: OAuth client secret from the OIDC provider
+        base_url: Public HTTPS URL where this server is accessible
+        host: Bind host (typically 0.0.0.0; override via MCP_HOST)
+        port: Port to listen on
+        path: MCP endpoint path
+    """
+    from fastmcp.server.auth.oidc_proxy import OIDCProxy
+
+    from ha_mcp.server import HomeAssistantSmartMCPServer
+    from ha_mcp.transport_security import ensure_host_origin_guard_default_off
+
+    # OIDC mode is deployed behind a public reverse proxy or LAN hostname;
+    # disable FastMCP's Host/Origin rebinding guard so proxied requests are
+    # not rejected with 421/403 before OIDC auth runs.
+    ensure_host_origin_guard_default_off()
+
+    proxy_kwargs: dict[str, Any] = {
+        "config_url": config_url,
+        "client_id": client_id,
+        "client_secret": client_secret,
+        "base_url": base_url,
+        # "external" tells FastMCP that consent is handled by the upstream
+        # IdP (Authentik, Keycloak, etc.) -- unlike `False`, this does not
+        # log a security warning at startup that consent is disabled.
+        "require_authorization_consent": "external",
+        # Preserve `or None`: an empty-but-set env var must not bypass
+        # FastMCP's derive-from-client-secret default for jwt_signing_key.
+        "jwt_signing_key": os.getenv("OIDC_JWT_SIGNING_KEY") or None,
+    }
+
+    allowed_redirect_uris = _oidc_allowed_client_redirect_uris()
+    if allowed_redirect_uris:
+        proxy_kwargs["allowed_client_redirect_uris"] = allowed_redirect_uris
+    else:
+        logger.warning(
+            "OIDC_ALLOWED_CLIENT_REDIRECT_URIS is not set: any dynamically-registered "
+            "(DCR) client's own redirect URIs are accepted. Internet-facing "
+            "deployments should set it."
+        )
+
+    if _oidc_verify_id_token_enabled():
+        proxy_kwargs["verify_id_token"] = True
+
+    audience = os.getenv("OIDC_AUDIENCE", "").strip()
+    if audience:
+        proxy_kwargs["audience"] = audience
+
+    # Create OIDC auth provider — auto-discovers endpoints from config_url
+    auth = OIDCProxy(**proxy_kwargs)
+
+    # Standard server with shared credentials (no proxy client needed)
+    global _server
+    _server = HomeAssistantSmartMCPServer()
+    mcp_instance = _server.mcp
+    mcp_instance.auth = auth
+
+    logger.info("Server created with OIDC authentication")
+    # Unlike standard/OAuth HTTP modes, OIDC mode intentionally registers no
+    # browser landing page and no settings-UI sidecar: an unauthenticated
+    # browser GET gets a bare 405 rather than a friendly page, and there is
+    # no settings UI surface here.
+    if _healthz_enabled():
+        _register_healthz_route(mcp_instance)
+    logger.info(f"Starting OIDC-enabled MCP server at {base_url}{path}")
+
+    await _run_with_shutdown(
+        mcp_instance.run_async(**_http_run_kwargs("http", host, port, path))
+    )
+
+
 if __name__ == "__main__":
     main()

{ha_mcp_dev-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1977}/src/ha_mcp/backup_manager.py

@@ -1296,14 +1296,18 @@ async def _restore_scene(client: Any, entity_id: str, config: Any) -> Any:
 async def _fetch_dashboard(client: Any, entity_id: str) -> Any:
     """Fetch a dashboard config via the same helper the get tool uses.
 
-    Delegates to ``tools_config_dashboards._get_dashboard_config_internal``
-    which handles the WS envelope, force-cache-bypass, and structured
-    error wrapping consistently with how the rest of the dashboard surface
-    fetches state. Imported lazily to avoid an import cycle.
+    The identifier is pre-resolved to its canonical url_path via the shared
+    ``_resolve_dashboard`` (component ``list`` when available), then the config is
+    read through the component ``get`` (one in-process frame) with a fall back to
+    the legacy ``lovelace/config`` read (``_get_dashboard_config_internal``, which
+    handles the WS envelope, force-cache-bypass, and structured error wrapping).
+    The component refuses YAML bodies, so those capture through legacy unchanged.
+    Imported lazily to avoid an import cycle.
     """
     from fastmcp.exceptions import ToolError
 
     from .tools.tools_config_dashboards import (
+        _component_dashboard_config,
         _get_dashboard_config_internal,
         _resolve_dashboard,
     )
@@ -1329,6 +1333,12 @@ async def _fetch_dashboard(client: Any, entity_id: str) -> Any:
             err,
         )
 
+    # Component fast path (freshness-safe in-memory read); None ⇒ legacy below,
+    # which also covers YAML dashboards and not-found (nothing to back up).
+    component_config = await _component_dashboard_config(client, fetch_path)
+    if component_config is not None:
+        return component_config
+
     try:
         config, _config_hash = await _get_dashboard_config_internal(client, fetch_path)
     except ToolError as err:
@@ -1442,10 +1452,21 @@ def _strip_readonly(config: dict[str, Any], *extra: str) -> dict[str, Any]:
 
 
 async def _fetch_label(client: Any, entity_id: str) -> Any:
-    items = _require_list(
-        await _ws_send(client, {"type": "config/label_registry/list"}),
-        "config/label_registry/list",
-    )
+    # Route the capture through the component's ``registries`` capability when
+    # available (one in-process read of the label registry) instead of dumping
+    # the whole registry via WS. Lazy import to avoid the backup_manager →
+    # tools → backup_manager cycle (same pattern as ``_fetch_device``). ``None``
+    # from the helper means "component unavailable"; fall back to the full list.
+    from .tools.component_registries import fetch_registries_via_component
+
+    component_result = await fetch_registries_via_component(client, ["label"])
+    if component_result is not None:
+        items = component_result.get("labels") or []
+    else:
+        items = _require_list(
+            await _ws_send(client, {"type": "config/label_registry/list"}),
+            "config/label_registry/list",
+        )
     for item in items:
         if item.get("label_id") == entity_id:
             return item
@@ -1466,12 +1487,22 @@ async def _fetch_category(client: Any, entity_id: str) -> Any:
     scope, _, cat_id = entity_id.partition(":")
     if not cat_id:
         return None
-    items = _require_list(
-        await _ws_send(
-            client, {"type": "config/category_registry/list", "scope": scope}
-        ),
-        "config/category_registry/list",
+    # Same component-first routing as ``_fetch_label``; categories are scoped,
+    # so the requested scope rides ``category_scopes``.
+    from .tools.component_registries import fetch_registries_via_component
+
+    component_result = await fetch_registries_via_component(
+        client, ["category"], category_scopes=[scope]
     )
+    if component_result is not None:
+        items = (component_result.get("categories") or {}).get(scope, [])
+    else:
+        items = _require_list(
+            await _ws_send(
+                client, {"type": "config/category_registry/list", "scope": scope}
+            ),
+            "config/category_registry/list",
+        )
     for item in items:
         if item.get("category_id") == cat_id:
             return {"scope": scope, **item}
@@ -1607,19 +1638,30 @@ async def _fetch_area_or_floor(client: Any, entity_id: str) -> Any:
     kind, _, real_id = entity_id.partition(":")
     if not real_id:
         return None
+    # Same component-first routing as ``_fetch_label`` / ``_fetch_category``.
+    from .tools.component_registries import fetch_registries_via_component
+
     if kind == "area":
-        items = _require_list(
-            await _ws_send(client, {"type": "config/area_registry/list"}),
-            "config/area_registry/list",
-        )
+        component_result = await fetch_registries_via_component(client, ["area"])
+        if component_result is not None:
+            items = component_result.get("areas") or []
+        else:
+            items = _require_list(
+                await _ws_send(client, {"type": "config/area_registry/list"}),
+                "config/area_registry/list",
+            )
         for item in items:
             if item.get("area_id") == real_id:
                 return {"kind": "area", **item}
     elif kind == "floor":
-        items = _require_list(
-            await _ws_send(client, {"type": "config/floor_registry/list"}),
-            "config/floor_registry/list",
-        )
+        component_result = await fetch_registries_via_component(client, ["floor"])
+        if component_result is not None:
+            items = component_result.get("floors") or []
+        else:
+            items = _require_list(
+                await _ws_send(client, {"type": "config/floor_registry/list"}),
+                "config/floor_registry/list",
+            )
         for item in items:
             if item.get("floor_id") == real_id:
                 return {"kind": "floor", **item}

{ha_mcp_dev-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1977}/src/ha_mcp/tools/backup.py

@@ -30,10 +30,21 @@ from ..backup_manager import (
     MandatoryBackupError,
     get_backup_manager,
 )
-from ..client.rest_client import HomeAssistantClient, HomeAssistantError
-from ..client.websocket_client import HomeAssistantWebSocketClient
+from ..client.rest_client import (
+    HomeAssistantClient,
+    HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
+    HomeAssistantError,
+)
+from ..client.websocket_client import HomeAssistantWebSocketClient, get_websocket_client
 from ..config import get_global_settings
 from ..errors import ErrorCode, create_error_response
+from .component_api import (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
 from .helpers import (
     exception_to_structured_error,
     get_connected_ws_client,
@@ -89,6 +100,9 @@ _BACKUP_PROGRESS_INTERVAL_S = 10
 # _wait_timeout) can be too tight for a slow or rate-limited remote agent —
 # same class of false-timeout problem this file already fixes for creation.
 _BACKUP_DELETE_WAIT_S = 60.0
+# WS command name is a module-local constant per the component-routing seam
+# pattern (see component_api.py / component_devices.py).
+WS_BACKUP_PREP = "ha_mcp_tools/backup_prep"
 
 
 def _get_backup_hint_text() -> str:
@@ -217,6 +231,91 @@ async def _get_backup_password(
     return cast(str, default_password)
 
 
+async def _backup_prep_via_component(
+    client: HomeAssistantClient,
+) -> dict[str, Any] | None:
+    """One ``ha_mcp_tools/backup_prep`` read; ``None`` ⇒ run the legacy two-call path.
+
+    Returns the component's ``{agent_ids, local_agent_id, default_password}``
+    payload, replacing the sequential ``backup/agents/info`` (local-agent
+    discovery, :func:`_get_local_backup_agent_id`) + ``backup/config/info``
+    (default password, :func:`_get_backup_password`) WS round-trips with one
+    in-process read. ``None`` on capability miss, downgrade (``unknown_command``
+    → invalidate the cached caps), or command error/timeout (logged) — the
+    caller falls back to the legacy sequential calls. A
+    ``HomeAssistantConnectionError`` (pooled-WS drop) or the plain ``Exception``
+    ``get_websocket_client()`` raises on a failed (re)connect is caught here and
+    mapped to ``None``: the legacy probes (``_get_local_backup_agent_id`` /
+    ``_get_backup_password``) run on a DEDICATED ``get_connected_ws_client`` socket
+    already connected before this read, NOT this pooled one — so a wedged pooled
+    socket must fall back to the legacy calls rather than fail create/restore.
+    Same caps-gate discipline as ``component_devices.fetch_device_via_component``.
+    """
+    caps = await get_component_caps(client)
+    if not component_supports(caps, "backup_prep"):
+        return None
+    try:
+        ws = await get_websocket_client(url=client.base_url, token=client.token)
+        raw = await ws.send_command(WS_BACKUP_PREP)
+    except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+        else:
+            logger.warning("%s failed; fell back to legacy: %r", WS_BACKUP_PREP, exc)
+        return None
+    except Exception as exc:
+        # HomeAssistantConnectionError (pooled-WS drop) OR the plain Exception
+        # get_websocket_client() raises on a failed (re)connect. The legacy probes
+        # ride a dedicated already-connected socket, so fall back rather than fail
+        # create/restore on a wedged pooled socket.
+        logger.warning(
+            "%s connection error; falling back to legacy: %r", WS_BACKUP_PREP, exc
+        )
+        return None
+    result = raw.get("result")
+    if not isinstance(result, dict) or "local_agent_id" not in result:
+        logger.debug(
+            "%s returned a malformed result (missing 'local_agent_id' key); "
+            "falling back to legacy",
+            WS_BACKUP_PREP,
+        )
+        return None
+    return result
+
+
+def _raise_no_local_backup_agent_error(agent_ids: list[Any] | None) -> NoReturn:
+    """Same "no local agent" error ``_get_local_backup_agent_id`` raises.
+
+    Used when the ``backup_prep`` component read comes back with
+    ``local_agent_id: None`` — the SAME outcome as the legacy probe finding no
+    agent named ``"local"``, so both paths fail identically.
+    """
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            "No local backup agent found",
+            context={"available_agents": [a for a in (agent_ids or []) if a]},
+            suggestions=[
+                "Backup creation requires a local agent (hassio.local on "
+                "Supervised, backup.local on Core); none is registered",
+            ],
+        )
+    )
+
+
+def _raise_no_default_password_error() -> NoReturn:
+    """Same error ``_get_backup_password`` raises when no default password is configured."""
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            "No default backup password configured in Home Assistant",
+            suggestions=[
+                "Configure automatic backups in Home Assistant settings to set a default password"
+            ],
+        )
+    )
+
+
 def _parse_backup_date(raw: Any) -> datetime | None:
     """Parse an HA backup `date` (ISO-8601, may use `Z` suffix) to a tz-aware
     datetime, returning None on missing/malformed input. Naive timestamps are
@@ -530,13 +629,24 @@ async def create_backup(
             )
         ws_client = cast(HomeAssistantWebSocketClient, ws_client)
 
-        # Get backup password (raises ToolError on failure)
-        password = await _get_backup_password(ws_client)
+        # One component read replaces the sequential password + local-agent
+        # probes when the ha_mcp_tools component supports backup_prep.
+        prep = await _backup_prep_via_component(client)
+        if prep is not None:
+            password = prep.get("default_password")
+            if not password:
+                _raise_no_default_password_error()
+            local_agent = prep.get("local_agent_id")
+            if not local_agent:
+                _raise_no_local_backup_agent_error(prep.get("agent_ids"))
+        else:
+            # Get backup password (raises ToolError on failure)
+            password = await _get_backup_password(ws_client)
 
-        # Discover the local backup agent at call time. HA Core registers
-        # `backup.local`; HA Supervised registers `hassio.local`. Hardcoding
-        # either breaks the other deployment.
-        local_agent = await _get_local_backup_agent_id(ws_client)
+            # Discover the local backup agent at call time. HA Core registers
+            # `backup.local`; HA Supervised registers `hassio.local`. Hardcoding
+            # either breaks the other deployment.
+            local_agent = await _get_local_backup_agent_id(ws_client)
 
         # Generate backup name if not provided
         if not name:
@@ -768,19 +878,38 @@ async def restore_backup(
                 )
             )
 
-        # Discover the local backup agent (Supervisor's hassio.local on
-        # Supervised, backup.local on Core). Used for both the safety backup
-        # and the restore call below.
-        local_agent = await _get_local_backup_agent_id(ws_client)
+        # One component read replaces the sequential local-agent + password
+        # probes when the ha_mcp_tools component supports backup_prep.
+        prep = await _backup_prep_via_component(client)
+        if prep is not None:
+            # Local backup agent (Supervisor's hassio.local on Supervised,
+            # backup.local on Core). Used for both the safety backup and the
+            # restore call below.
+            local_agent = prep.get("local_agent_id")
+            if not local_agent:
+                _raise_no_local_backup_agent_error(prep.get("agent_ids"))
+
+            # Create safety backup BEFORE restoring
+            logger.info("Creating safety backup before restore...")
+            password = prep.get("default_password")
+            if not password:
+                # No default password - log warning but continue (restore might still work)
+                logger.warning("No default password - proceeding without safety backup")
+                password = None
+        else:
+            # Discover the local backup agent (Supervisor's hassio.local on
+            # Supervised, backup.local on Core). Used for both the safety backup
+            # and the restore call below.
+            local_agent = await _get_local_backup_agent_id(ws_client)
 
-        # Create safety backup BEFORE restoring
-        logger.info("Creating safety backup before restore...")
-        try:
-            password = await _get_backup_password(ws_client)
-        except ToolError:
-            # Password error - log warning but continue (restore might still work)
-            logger.warning("No default password - proceeding without safety backup")
-            password = None
+            # Create safety backup BEFORE restoring
+            logger.info("Creating safety backup before restore...")
+            try:
+                password = await _get_backup_password(ws_client)
+            except ToolError:
+                # Password error - log warning but continue (restore might still work)
+                logger.warning("No default password - proceeding without safety backup")
+                password = None
 
         safety_backup_id, safety_warnings = await _create_safety_backup(
             ws_client, password, local_agent, ctx=ctx