Add policy enforcement for device control and automation tools

[L1AD]

This server exposes 86+ tools for controlling Home Assistant -- lights, locks, thermostats, automations, and dashboards:

• call_service -- triggers any Home Assistant service (unlock doors, disable alarms, turn off cameras)
• create_automation -- creates new automated triggers
• update_dashboard -- modifies UI dashboards

An agent with access to call_service can control physical devices in your home. The security implications of an agent unlocking a door or disabling an alarm system are significant.

Suggestion: Consider documenting support for PolicyLayer/Intercept, an open-source MCP proxy that enforces policies on tool calls before execution.

Example policy:

version: "1"
default: allow

tools:
  call_service:
    rules:
      - action: require_approval

  create_automation:
    rules:
      - action: require_approval

  update_dashboard:
    rules:
      - rate_limit: 5/hour

One line to set up: npx -y @policylayer/intercept init

[github-actions]

🔍 Analysis

The user is proposing a significant security improvement by documenting integration with PolicyLayer/Intercept, an open-source MCP proxy. This addresses a critical concern: providing AI agents with direct control over physical security devices (like locks and alarms) and system configurations (like automations and dashboards) without a "human-in-the-loop" for sensitive operations.

While ha-mcp provides module-level access control via the ENABLED_TOOL_MODULES environment variable, it does not currently support granular, per-call policy enforcement (e.g., "always allow lights, but require approval for unlocking doors"). The suggested approach leverages an external proxy to handle these policies, which keeps the core of ha-mcp focused on its primary function while providing advanced users with the security controls they need.

The tools mentioned in the issue correspond to the following actual tools in ha-mcp:

• call_service → ha_call_service (in src/ha_mcp/tools/tools_service.py)
• create_automation → ha_config_set_automation (in src/ha_mcp/tools/tools_config_automations.py)
• update_dashboard → ha_config_set_dashboard (in src/ha_mcp/tools/tools_config_dashboards.py)

🛠️ Suggested Steps

1. Verify Intercept compatibility: Test ha-mcp behind policylayer/intercept to ensure that streaming and tool calls work as expected through the proxy.
2. Add Security documentation: Create a new documentation section (e.g., docs/SECURITY_BEST_PRACTICES.md) or update the README.md to explain how to secure sensitive tools.
3. Provide example policies: Include a sample policy.yaml specifically tailored for ha-mcp tools, such as requiring approval for ha_call_service when targeting certain domains (lock, alarm_control_panel).
4. Update README: Add a "Security & Policies" section to the main README that mentions this as a recommended practice for production deployments.

📊 Technical Analysis (for maintainers)

Root Cause

The Model Context Protocol (MCP) by design allows the host application full access to all tools exposed by the server. In a smart home context, this means an LLM could potentially perform high-stakes physical actions. While ha-mcp has ENABLED_TOOL_MODULES for coarse-grained control, it lacks the ability to intercept individual tool calls based on their arguments (e.g., which service is being called via ha_call_service).

Affected Code

These are the primary tools that would benefit from policy enforcement:

• src/ha_mcp/tools/tools_service.py - Contains ha_call_service, the primary gateway for device control.
• src/ha_mcp/tools/tools_config_automations.py - Contains ha_config_set_automation for modifying system logic.
• src/ha_mcp/tools/tools_config_dashboards.py - Contains ha_config_set_dashboard for modifying the UI.
• src/ha_mcp/tools/tools_system.py - Contains tools for restarting or shutting down the system.

Proposed Fix

I suggest adding a "Security Best Practices" section to the documentation with a sample configuration for policylayer/intercept:

# policy.yaml for ha-mcp
version: "1"
default: allow

tools:
  ha_call_service:
    rules:
      - condition: "arg.domain == 'lock' or arg.domain == 'alarm_control_panel'"
        action: require_approval
      - condition: "arg.service == 'restart' or arg.service == 'stop'"
        action: require_approval

  ha_config_set_automation:
    rules:
      - action: require_approval

  ha_config_set_dashboard:
    rules:
      - rate_limit: 5/hour

Related Issues/PRs

• No similar issues found regarding external policy proxies.

---

🤖 Automated analysis by Issue Bot

[kingpanther13]

Thanks for the suggestion — this is a real gap and worth addressing. Agent-driven control of locks, alarms, and automations absolutely warrants finer-grained policy than the module-level ENABLED_TOOL_MODULES switch we have today.

We'll likely lean toward implementing this in-tree using the FastMCP middleware infrastructure we already build on — specifically an on_call_tool middleware that evaluates argument-level rules, plus RateLimitingMiddleware for throttling. That keeps it a single process with no extra deployment step for addon users, and lets us tie rules to ha-mcp's existing read/write/delete tool categories.

That said, Intercept's rules model is a good reference point and we could realistically port its YAML shape directly onto a FastMCP middleware, so credit will go where it's due once we land something. Going to do more research on the exact rule surface before committing to a design.

Appreciate the input.

[kingpanther13]

Just making a note for future reference: if/when we can implement this, we will probably be able to put it in the interface made by #960

[kingpanther13]

Just making a note, I haven't forgotten about this. Will find a way to put this into the web interface as an advanced setting at some point. This can be a great way to require granular approval for tools when using toolsearch mode . Toolsearch mode removes the ability to control individual tool permissions from the AI side, though tools can still be enabled/disabled, it would be clunky and require restarts. This could bring back the simple ability to just make it so certain tools require manual approval before use.

[Patch76]

Two pieces of context that have shifted since the April thread:

The web-UI panel KP13 referenced in #960 merged on 2026-05-02, so the surface for an "advanced settings" policy panel exists today. PR #1381 (in review) adds a persistent stdio-mode sidecar built on the same build_settings_handlers() factory — a policy panel could mount through that extension point and reach every install mode (stdio, ha-mcp-web, add-on) without a second UI surface to maintain.

FastMCP 3.3.1 (the pinned version) ships the middleware infrastructure KP13 sketched in April:

• Middleware.on_call_tool(context, call_next) at fastmcp/server/middleware/middleware.py:156 — the right hook for argument-aware allow / deny / require-approval decisions.
• Middleware.on_list_tools at line 177 — useful for filtering the advertised tool set in toolsearch mode based on the same rules.
• RateLimitingMiddleware (token bucket) + SlidingWindowRateLimitingMiddleware already implemented in fastmcp/server/middleware/rate_limiting.py — the rate_limit action from the proposed YAML composes directly with these rather than being re-implemented.

Two existing taxonomy axes a policy engine can key off:

• Per-tool tags — 24+ distinct category tags across the 89 registered tools today (Service & Device Control, Automations, Scripts, Dashboards, System, Add-ons, …). A rule like "deny all Service & Device Control writes whose target is a lock.* entity" is per-tag plus argument-aware, not per-tool-name.
• MCP safety annotations — 49 tools currently declare destructiveHint: True and 40 declare readOnlyHint: True. The simplest default policy ("require approval on every destructive call, allow every read-only call") is half-described in the tool metadata; the policy engine just enforces what the tools already declare.

The toolsearch-mode point KP13 raised on May 8 is the strongest motivator: per-tool enable/disable round-trips through a restart, but on_call_tool interception is runtime-dynamic and would let toolsearch users keep the broader tool surface while gating individual high-stakes calls per policy.

Open design choices the architecture path doesn't resolve on its own:

• Rules location — packaged-defaults shipped in the repo, runtime-editable via the new web UI, or both with override precedence?
• Approval surface — UI-side modal (only works while an interactive client is attached), an async approval queue (works headless), or both?
• Per-deployment scoping — same policy across stdio + addon + ha-mcp-web, or surface a "deployment context" axis (some installs are unattended, some have a human in front of them)?

[kingpanther13]

This should be the same surface between every install method to keep it simple... Everything should be in the web UI. It'll be completely opt-in though. We don't need to make it complicated or add various categories, we can simply keep it per-tool similar to how the web UI already is today. The only time I'd recommend making it on by default (but still disableable) would be with the dangerous beta tools, but that would be another discussion. The biggest win will be figuring out a way to require the llm to ask the user to confirm before using certain tools that are nested within toolsearch.

Edit: biggest obstacle, how do we make it so user confirmation is required for a tool to be used? We can't just rely on the LLM to follow instructions, BUT the only way for this to work smoothly would be some way to work THRU the LLM chat. Otherwise it will be no better than just enabling/disabling tools on the fly. Maybe the middleware that was original advertised has another clever way, I will look into that when I go to implement this. Maybe a password type of thing or something like that? WIll have to explore this; if it isn't possible to block the LLM from using a tool without explicit user aproval within the chat then this idea is a bust, since tools can be enabled/disabled on the fly now anyways. The point of this is to do something similar to having LLMs ask for approval before using a tool, but it would apply to hidden tools within the proxies and whatnot too (which currently isn't possible with normal LLMs).

[Patch76]

Status snapshot at 2026-05-22 — both architectural prerequisites the April thread waited on are merged; the design has converged; what's left is implementation.

Design state (converged per the April–May discussion):

• In-tree FastMCP middleware on on_call_tool, NOT external proxy documentation.
• Web-UI policy panel mounted through build_settings_handlers() — same surface across stdio / addon / docker / web modes.
• Per-tool granularity, mirroring the existing tool-enable/disable shape from feat: web-based settings UI for per-tool enable/disable/pin #960 (no per-category complication).
• Opt-in by default; possible default-on only for dangerous-beta tools (locks, alarms, factory-reset class).

Prerequisites now in place:

• feat: web-based settings UI for per-tool enable/disable/pin #960 (web-based settings UI for per-tool enable/disable/pin) — merged 2026-05-02.
• feat: persistent settings UI for stdio mode #1381 (persistent stdio-mode sidecar via build_settings_handlers()) — merged 2026-05-22. With this landed, a policy panel can reach every install mode through one mount point.

External landscape (the original suggestion + the broader 2026 ecosystem):

@L1AD's original pointer to PolicyLayer's MCP enforcement product names the proxy-pattern shape that several 2026 entrants share — YAML/JSON policy file, deterministic enforcement, rate-limit + approval + deny verbs. Adjacent options on the in-tree / library side:

• Cerbos + FastMCP — middleware that decouples authorization, dynamically filters the tool list per user.
• Permit.io's permit-fastmcp — RBAC/ABAC middleware specifically for FastMCP.
• FastMCP built-in elicitation — await elicit() inside a tool surfaces an approval prompt through the MCP client with zero server-side state. Two lines per dangerous tool.

Survey-level reading: obot.ai's 13-gateway 2026 roundup, DX Heroes governance landscape. For the centralized-portal / sub-millisecond-enforcement pattern: Cloudflare's enterprise MCP reference architecture (announced 2026-05-21) and Microsoft's Agent Governance Toolkit (open-source, April 2026; ships an MCP Security Gateway as one component).

The proxy pattern fits power users who self-host and can put a sidecar in front of their MCP server; in-tree FastMCP middleware fits ha-mcp's deployment shape (supervisor addon, docker container, stdio client) where the network-proxy approach breaks the zero-config story for most users.

Open implementation questions (2nd-order — for the implementation PR's design):

1. Approval mechanism — FastMCP elicitation (await elicit() per call) vs. a web-UI approval queue page vs. both. Elicitation is built-in and zero-state; the queue is more visible for batch / unattended scenarios.
2. Rate-limit shape — PolicyLayer-style 5/hour per session vs. per-tool counts in the web UI vs. just approve-or-deny. The simpler shape (approve-or-deny per tool, no rate caps) covers the originally-cited concerns (lock/alarm misuse) and can extend later.
3. Persistence — ~/.ha-mcp/policies.json alongside the feature-flag override file from feat: persistent settings UI for stdio mode #1381; addon-mode reads from config.yaml.
4. Auditing — log line per approve/deny, in standard logger / web UI history / both.

Label suggestion: needs-choices → ready-to-implement. The whether-to-build question is decided; the how-questions belong in an implementation PR's design.

Not proposing close — the design has converged but no implementation PR exists yet.