[FEATURE] Use MCP Apps to expose server settings via in-client UI

[kingpanther13]

What would you like to see?

FastMCP 3.2 introduced MCP Apps — tools that can return interactive UIs rendered directly inside the client. ha-mcp could use this to let users view and change server settings (tool visibility, pinned tools, tool search result count, and potentially other settings) through an interactive UI within their MCP client, rather than only through the add-on configuration.

Beyond settings, this could also be used with tools to let users control things directly in their Home Assistant interface — dashboards, entity controls, etc. There are a lot of possibilities here.

Why do you need this?

Currently, changing settings like which tools are disabled or pinned requires editing the add-on configuration and restarting. An in-client UI (e.g., toggle switches for tool groups, sliders for result counts) would make this faster and more discoverable. This would complement the add-on settings — add-on config sets defaults, and the in-client UI allows adjustments during use.

Additional context

Related: #857 (user-configurable tool disable/pin in add-on settings) introduces the tool visibility configuration that could be a first candidate for an in-client UI (closed in favor of #960 which uses a web UI).

See latest comment; reopened this because Claude Desktop users connecting with quick connect from the setup guide using STDIO don't have an easy way to access settings other than modifying their settings json; therefore, this is still relevant for people with similar setups. They also don't have an easy way to access the web UI set up with #960; so I think that this mostly should just piggyback off of #960 if possible and provide the same settings (and #960 will start including more configuration options, like what's currently available in the addon version). We also should update the astro site to tell users how to access the settings menus when using Claude Desktop, by A) accessing the #960 web UI directly via the URL or B) by using this method within the LLM itself, if it is supported. Also should allow the LLM to control the settings as well if asked by the user, though this may need to have some kind of safety toggle or something....but when working properly the user can simply say "hey, enable/disable toolsearch" and it can do it. Definitely needs a manual toggle though because we don't want a confused LLM just randomly doing it.

[github-actions]

🔍 Analysis

This is a valid feature request that leverages recent capabilities in the underlying framework. ha-mcp is already using FastMCP 3.2.0 (verified in pyproject.toml), which introduced MCP Apps. These apps allow tools to return interactive UIs (built with Prefab UI) that render directly inside supporting MCP clients like Claude Desktop.

Currently, server settings such as fuzzy_threshold, entity_search_limit, and tool visibility are configured via environment variables or the Home Assistant add-on configuration. An in-client UI would make these settings much more discoverable and allow users to adjust them on-the-fly without restarting the server.

The project's modular tool architecture (using ToolsRegistry for auto-discovery) makes this easy to implement. By adding a new module following the tools_*.py naming convention, the settings UI would be automatically registered at startup.

🛠️ Suggested Steps

1. Create a new tool module: Add src/ha_mcp/tools/tools_settings_ui.py to the codebase.
2. Implement the UI using Prefab components: Use fastmcp.apps.PrefabApp and components like Form, Heading, and DataTable to build the interface.
3. Connect to global settings: Use get_global_settings() from ha_mcp.config to read and update the server's configuration state.
4. Register the tool: Ensure the module contains a register_settings_ui_tools(mcp, client, **kwargs) function so it is picked up by the ToolsRegistry.

📊 Technical Analysis (for maintainers)

Root Cause

The current configuration model is static (loaded at startup from .env or environment variables via pydantic-settings). While effective for the Home Assistant add-on, it lacks interactivity for users interacting solely through an MCP client. FastMCP 3.2's app=True tool parameter provides the necessary plumbing to bridge this gap.

Affected Code

• src/ha_mcp/config.py - Contains the Settings singleton that would be manipulated by the UI.
• src/ha_mcp/server.py - Orchestrates the FastMCP instance and tool registration.
• src/ha_mcp/tools/registry.py - Will auto-discover the new settings tool module.

Proposed Fix

Create src/ha_mcp/tools/tools_settings_ui.py with the following structure:

from typing import Any
from fastmcp import FastMCP
from fastmcp.apps import PrefabApp, Heading, Form, TextField, NumberField, Switch
from ..config import get_global_settings
from ..client.rest_client import HomeAssistantClient

def register_settings_ui_tools(mcp: FastMCP, client: HomeAssistantClient, **kwargs: Any) -> None:
    settings = get_global_settings()

    @mcp.tool(app=True)
    async def server_settings() -> PrefabApp:
        """View and adjust ha-mcp server settings via an interactive UI."""
        with PrefabApp() as app:
            Heading("ha-mcp Server Settings")
            
            with Form(action="update_settings"):
                NumberField("Entity Search Limit", name="search_limit", value=settings.entity_search_limit)
                NumberField("Fuzzy Threshold", name="fuzzy_threshold", value=settings.fuzzy_threshold)
                Switch("Enable Tool Search", name="enable_search", value=settings.enable_tool_search)
                Switch("Enable Skills", name="enable_skills", value=settings.enable_skills)
        return app

    @mcp.tool(visible=False) # Backend tool for the UI
    async def update_settings(search_limit: int, fuzzy_threshold: int, enable_search: bool, enable_skills: bool) -> str:
        settings.entity_search_limit = search_limit
        settings.fuzzy_threshold = fuzzy_threshold
        settings.enable_tool_search = enable_search
        settings.enable_skills = enable_skills
        return "Settings updated successfully!"

Related Issues/PRs

• feat: user-configurable tool disable/pin in add-on settings #857 - Introduced user-configurable tool visibility options that this UI would expose.

---

🤖 Automated analysis by Issue Bot

[Patch76]

Picking this up as the assignee. Before I cut a worktree, I want to surface what I found in the FastMCP 3.2.4 surface and the open design questions, because the bot sketch above is misleading on the API and the implementation would touch enough of the existing settings story that I'd rather get a steer first.

What FastMCP 3.2.4 actually exposes

The bot's from fastmcp.apps import PrefabApp, Heading, Form, TextField, NumberField, Switch does not match the installed package. Verified locally against fastmcp==3.2.4:

• fastmcp.apps public exports are AppConfig, FastMCPApp, PrefabAppConfig, ResourceCSP, ResourcePermissions, UI_EXTENSION_ID, UI_MIME_TYPE. No PrefabApp, no Heading/Form/TextField/NumberField/Switch.
• The Prefab UI components live under fastmcp.apps.form / fastmcp.apps.choice / fastmcp.apps.approval / fastmcp.apps.generative / fastmcp.apps.file_upload, but importing any of them raises ImportError: FormInput requires prefab-ui. Install with: pip install 'fastmcp[apps]'. The prefab-ui package is not in our uv.lock — fastmcp==3.2.4 (no [apps] extra) is what we currently pin.
• The real programming model is FastMCPApp(name) with @app.ui for entry-point UI tools and @app.tool for backend tools the UI calls (those default to visibility=["app"], hidden from the model unless model=True). @mcp.tool(app=True) is also valid syntax, but the body in the bot's example would still need real components from the prefab-ui surface.

So a real implementation of this issue requires pulling in fastmcp[apps] (or prefab-ui directly) as a hard or optional dependency.

Open questions before I write code

1. Dependency policy. Are we OK adding prefab-ui to the runtime closure? It's not a tiny package, and it only pays off on clients that render Prefab UI. Two paths: hard dep on fastmcp[apps], or optional install-extra plus a feature flag (e.g. ENABLE_MCP_APPS_UI) that no-ops the registration when the import fails.

2. Client compatibility. Do we know which MCP clients actually render Prefab UI today? If only one or two do, the value vs. maintenance ratio for a parallel UI shifts, and the answer might steer us toward a flag-gated minimal entry point rather than a full settings surface.

3. Scope vs. existing web UI (feat: web-based settings UI for per-tool enable/disable/pin #960). The web UI at /settings already covers tool enable/disable/pin and persists to get_data_dir() / "tool_config.json". I see two reasonable scopes for the MCP App version:

   • MVP — mirror only the tool-visibility view (the killer use case from this issue's body), reusing the same JSON file as the source of truth so both UIs stay in sync.
   • Wider — also expose the runtime settings (fuzzy_threshold, entity_search_limit, enable_tool_search, tool_search_max_results, the code_mode_* group, etc. — Settings has 27 env-aliased fields total, of which a subset is plausibly user-tweakable).

   The bot's snippet mutates settings.entity_search_limit = … directly, which would change the in-memory pydantic singleton without writing anywhere — those edits would be lost on restart. Whatever scope we pick, persistence has to go through the same channel settings_ui.py already uses, not a parallel one.

4. UI/state-sharing extraction. If the answer to (3) is anything beyond "skip", I'd want to extract the read/write helpers out of settings_ui.py into a small shared service first, so the Starlette HTML route and the MCP App tool both call the same code. That refactor is small but worth its own commit.

Proposed next step

I'd like to not auto-implement until (1) and (2) above have a clear answer. My preference, if you agree:

• Short discussion here on dep policy and client target, then
• A minimal spike PR: tool-visibility MCP App only, behind ENABLE_MCP_APPS_UI=false by default, with fastmcp[apps] as an optional install extra (so the addon image isn't bloated for users on clients that can't render it). That gives us something testable against a Prefab-rendering client without committing the project to a second full UI surface.

If you'd rather I just go and build the wider scope, say so and I'll plan it that way — but I wanted the dependency and client-target call to be yours, not mine.

[kingpanther13]

I'm honestly thinking this one is not quite as useful now that we have #960, implementing this would just be duplicating what #960 does or will be able to do in the future anyways. Additionally, you're right that some AI clients might not even support this in the first place. Probably should close this then rework it to a spinoff to just add more functionality to the web interface.

Also yeah never trust the triage bot lol, it's mostly guessing.

[Patch76]

Your issue, close it, if you dare. 😁

[kingpanther13]

Superseded by #1164 — folding the runtime-settings exposure into the existing #960 web UI rather than a parallel MCP App surface.

[kingpanther13]

I'm reopening this one, after trying the Claude Desktop version from the quick install instructions, I realize that there's still no easy way to modify settings in that environment. There's also no obvious way to get to the web interface even though it's possible. Without the addon installed a lot of stuff is hidden. So I plan to experiment with this and see if it will be able to work in Claude Desktop as a minimum; I plan to make it as simple as possible, instead of a whole new interface to maintain I'm hoping to see if I can just make it use the existing web interface, or just allow the LLM to change the settings itself or something like that; not completely decided yet.

[kingpanther13]

@Patch76 do you use Claude desktop regularly? This one is meant specifically for Claude desktop, I think it would be a good one for you to tackle if you do.

[Patch76]

Actually, I installed my Claude Code directly on my HA instance, running HAOS, and I use NAbuCase via the terminal from any browser (at home, at work, at my weekend cabin)—always on the same system.