feat!: remove ha-mcp-sse entry point (#2032)

* feat!: remove ha-mcp-sse entry point

The MCP specification has formally deprecated the HTTP+SSE transport.
No install method or documentation advertised ha-mcp-sse; Streamable
HTTP (ha-mcp-web) is the supported HTTP mode.

Removes main_sse, the ha-mcp-sse console script, fastmcp-sse.json, the
SSE branches in _http_run_kwargs / ProbeAccessLogFilter /
register_browser_landing, the SSE entry-point detection in the bug
report tool, and the SSE notes on the setup page.

BREAKING CHANGE: the ha-mcp-sse console script and SSE transport mode
are removed; use ha-mcp-web (Streamable HTTP) instead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* test: cover FASTMCP_TRANSPORT=sse env hint; sweep stale HTTP/SSE comments

Review findings: the FASTMCP_TRANSPORT=sse branch in _detect_mcp_transport
is now the sole path to "sse" detection and had no direct test, and seven
comments/docstrings outside __main__.py still described an HTTP/SSE
deployment mode that no longer exists.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

SECURITY.md

@@ -34,8 +34,8 @@ Consequences:
 
 ### Local network is the trusted zone for standard mode
 
-The HTTP entrypoints (`ha-mcp-web`, `ha-mcp-sse`) authenticate by URL-path
-secrecy and are designed for loopback HTTP or LAN HTTP with a high-entropy
+The HTTP entrypoint (`ha-mcp-web`) authenticates by URL-path
+secrecy and is designed for loopback HTTP or LAN HTTP with a high-entropy
 `MCP_SECRET_PATH`. Any peer that can reach the configured path is treated as
 trusted — securing the local network is outside ha-mcp's scope.
 
@@ -79,7 +79,7 @@ Operators who front ha-mcp differently can re-enable the guard by setting
 
 ### Standard mode is single-tenant
 
-The secret-URL model (`ha-mcp-web`, `ha-mcp-sse`) assumes a single operator.
+The secret-URL model (`ha-mcp-web`) assumes a single operator.
 All MCP clients that share the same `MCP_SECRET_PATH` get identical access —
 there is no per-client authorization or isolation. Reports that assume "client A
 shouldn't be able to see client B's data" don't apply to standard mode; that

fastmcp-sse.json

@@ -56,7 +56,6 @@ ha-mcp = "ha_mcp.__main__:main"
 ha-mcp-smoke-test = "ha_mcp.smoke_test:main"
 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"
 

pyproject.toml

@@ -1769,13 +1769,13 @@ ingress:
     }
 
     // Transport disclaimer (all HTTP-based setups): Streamable HTTP is the modern standard
-    // supported by virtually all current clients; SSE is legacy and only applies to the
-    // dedicated ha-mcp-sse entry point — not the app / ha-mcp-web.
+    // supported by virtually all current clients; the MCP spec has deprecated HTTP+SSE and
+    // nothing here serves it, so an SSE-style client config gets a 405.
     if (!isLocal) {
       instructions.push(`<div class="instruction-block border-blue-700/50 bg-blue-900/10">
         <h3 class="instruction-title text-blue-300">Transport: use Streamable HTTP, not SSE</h3>
         <p class="text-slate-300 text-sm">The ha-mcp app (and <code class="bg-slate-800 px-1 rounded">ha-mcp-web</code>) serve <strong>Streamable HTTP</strong> — the modern default, supported by virtually all current MCP clients (Claude Code, Claude.ai, ChatGPT, Cursor, GitHub Copilot, and more). The config above already uses it.</p>
-        <p class="text-slate-300 text-sm mt-2"><strong>SSE is legacy.</strong> You only need it for the separate <code class="bg-slate-800 px-1 rounded">ha-mcp-sse</code> entry point (deprecated SSE on port 8087). The app does <strong>not</strong> serve SSE, so an SSE / <code class="bg-slate-800 px-1 rounded">--transport sse</code> config pointed at it returns a <code class="bg-slate-800 px-1 rounded">405</code> and won't connect.</p>
+        <p class="text-slate-300 text-sm mt-2"><strong>SSE is not offered.</strong> The MCP spec has deprecated the HTTP+SSE transport, so an SSE / <code class="bg-slate-800 px-1 rounded">--transport sse</code> config pointed at the app returns a <code class="bg-slate-800 px-1 rounded">405</code> and won't connect — switch any older SSE-style client config over to Streamable HTTP.</p>
       </div>`);
     }
 
@@ -1800,7 +1800,7 @@ ingress:
       instructions.push(`<div class="instruction-block border-blue-700/50 bg-blue-900/10">
         <h3 class="instruction-title text-blue-300">Gemini CLI Notes</h3>
         <p class="text-slate-300 text-sm mb-2"><strong>If client logs show <code>405 Method Not Allowed</code> on <code>GET /mcp</code>:</strong> the server is running in Streamable HTTP mode — switch from <code>url</code> to <code>httpUrl</code> in <code>~/.gemini/settings.json</code>. The config below already uses <code>httpUrl</code>.</p>
-        <p class="text-slate-300 text-sm mb-2 mt-3">Entry points: <code>ha-mcp-web</code> (default) serves Streamable HTTP at <code>/mcp</code> on port 8086. The separate <code>ha-mcp-sse</code> entry point serves legacy SSE on port 8087 — pair that with the <code>url</code> key (not <code>httpUrl</code>) if you need SSE specifically.</p>
+        <p class="text-slate-300 text-sm mb-2 mt-3">Entry point: <code>ha-mcp-web</code> (default) serves Streamable HTTP at <code>/mcp</code> on port 8086 — always pair it with the <code>httpUrl</code> key, not <code>url</code>.</p>
         <p class="text-slate-300 text-sm mb-2 mt-3"><strong>A direct browser/curl probe of <code>http://&lt;host&gt;:8086/mcp</code> also returns 405 by design</strong> — that is the <code>register_browser_landing</code> handler in <code>src/ha_mcp/__main__.py</code> confirming the server is up, not a fault. MCP clients use <code>POST</code>; this only shows up if a curl probe or browser hits the URL directly.</p>
         <p class="text-slate-300 text-sm mt-3"><strong>Alternative: HA built-in MCP integration.</strong> If you have the <a href="https://www.home-assistant.io/integrations/mcp_server/" target="_blank" rel="noopener noreferrer" class="text-blue-400 hover:underline">Home Assistant MCP integration</a> enabled, you can skip <code>ha-mcp</code> entirely and point Gemini CLI at HA's <code>/api/mcp</code> endpoint with a long-lived access token in a <code>Bearer</code> header. HA core also serves the legacy SSE endpoint at <code>/mcp_server/sse</code> on the same host/port — same 405-on-GET caveat applies there.</p>
       </div>`);

site/src/pages/setup.astro

@@ -306,28 +306,21 @@ def _setup_standard_mode() -> None:
     _log_startup_version()
 
 
-def _http_run_kwargs(transport: str, host: str, port: int, path: str) -> dict[str, Any]:
-    """Build common run_async kwargs for HTTP-based transports.
-
-    ``stateless_http`` is a Streamable-HTTP concept and is only valid for the
-    ``http``/``streamable-http`` transports. Passing it alongside
-    ``transport="sse"`` makes fastmcp's ``run_async`` raise
-    ``ValueError("SSE transport does not support stateless mode")``. Gating it to
-    non-SSE transports keeps SSE startup working. (Before this fix that raise was
-    also swallowed into a silent exit 0; ``_run_with_shutdown`` now surfaces a
-    self-terminating server task's exception instead.) See #1544.
+def _http_run_kwargs(host: str, port: int, path: str) -> dict[str, Any]:
+    """Build common run_async kwargs for the Streamable HTTP transport.
+
+    Every HTTP entry point (``ha-mcp-web``, OAuth, OIDC) runs Streamable HTTP,
+    so ``stateless_http`` — a Streamable-HTTP-only concept — always applies.
     """
-    kwargs: dict[str, Any] = {
-        "transport": transport,
+    return {
+        "transport": "http",
         "host": host,
         "port": port,
         "path": path,
+        "stateless_http": True,
         "show_banner": _get_show_banner(),
         "uvicorn_config": {"log_config": _get_timestamped_uvicorn_log_config()},
     }
-    if transport != "sse":
-        kwargs["stateless_http"] = True
-    return kwargs
 
 
 def _create_server() -> "HomeAssistantSmartMCPServer":
@@ -458,14 +451,12 @@ class ProbeAccessLogFilter(logging.Filter):
       health check, reverse proxy, or a connector's SSE-style pre-flight) hit a
       POST-only Streamable HTTP endpoint. The raw access line is dropped and the
       landing handler logs one annotated "(NORMAL for most non-SSE connections)"
-      line in its place. Dropped only when ``drop_mcp_405`` is set — SSE callers
-      pass False, since there a GET answers 200 and a GET-405 is a genuine fault.
+      line in its place.
     """
 
-    def __init__(self, mcp_path: str, *, drop_mcp_405: bool = True) -> None:
+    def __init__(self, mcp_path: str) -> None:
         super().__init__()
         self._mcp_path = mcp_path.rstrip("/") or "/"
-        self._drop_mcp_405 = drop_mcp_405
 
     def filter(self, record: logging.LogRecord) -> bool:
         # uvicorn.access records carry structured args: (client, method, path,
@@ -483,12 +474,8 @@ def filter(self, record: logging.LogRecord) -> bool:
             return False  # opt-in liveness probe (register_healthz) — pure noise
         # By-design probe 405 on the MCP path; the handler logs an annotated line
         # instead. This trusts that the landing route is the only GET/HEAD responder
-        # on the MCP path (true today). Kept in SSE mode (drop_mcp_405=False), where
-        # a GET answers 200 and a 405 is a real fault.
-        is_dropped_probe = (
-            status == 405 and path == self._mcp_path and self._drop_mcp_405
-        )
-        return not is_dropped_probe
+        # on the MCP path (true today).
+        return not (status == 405 and path == self._mcp_path)
 
 
 def _setup_logging(log_level_str: str, force: bool = False) -> None:
@@ -967,7 +954,7 @@ def main_dev() -> None:
 
 # HTTP entry point for web clients
 def _get_http_runtime(default_port: int = 8086) -> tuple[str, int, str]:
-    """Return runtime configuration shared by HTTP transports.
+    """Return runtime configuration shared by the HTTP entry points.
 
     Args:
         default_port: Default port to use if MCP_PORT env var is not set.
@@ -1048,12 +1035,12 @@ def _is_running_in_container() -> bool:
 def _warn_if_default_path_exposed(host: str, port: int, path: str) -> None:
     """Warn on a direct run that leaves the default path on a LAN bind.
 
-    Standard-mode HTTP/SSE authenticates by URL-path secrecy (see
+    Standard-mode HTTP authenticates by URL-path secrecy (see
     SECURITY.md → Threat Model). The default ``/mcp`` is not the
     high-entropy secret that model assumes once the bind leaves loopback.
 
-    Fires only for a direct ``ha-mcp-web`` / ``ha-mcp-sse`` start (uvx, pip,
-    source) that uses the default path on a non-loopback host. Operators
+    Fires only for a direct ``ha-mcp-web`` start (uvx, pip, source) that uses
+    the default path on a non-loopback host. Operators
     silence it the same way they harden — bind ``MCP_HOST=127.0.0.1`` or set
     a high-entropy ``MCP_SECRET_PATH``. Containers are skipped: an
     in-container ``0.0.0.0`` bind says nothing about real exposure, which is
@@ -1068,7 +1055,7 @@ def _warn_if_default_path_exposed(host: str, port: int, path: str) -> None:
         return
     logger.warning(
         "ha-mcp listening on %s:%s%s with default MCP_SECRET_PATH. "
-        "Standard-mode HTTP/SSE authenticates by URL-path secrecy and assumes "
+        "Standard-mode HTTP authenticates by URL-path secrecy and assumes "
         "a high-entropy MCP_SECRET_PATH for non-loopback binds "
         "(see SECURITY.md → Threat Model). "
         "Either bind loopback (MCP_HOST=127.0.0.1) or set MCP_SECRET_PATH "
@@ -1080,15 +1067,12 @@ def _warn_if_default_path_exposed(host: str, port: int, path: str) -> None:
 
 
 async def _run_http_with_graceful_shutdown(
-    transport: str,
     host: str,
     port: int,
     path: str,
 ) -> None:
     """Run HTTP server with graceful shutdown support."""
-    await _run_with_shutdown(
-        _get_mcp().run_async(**_http_run_kwargs(transport, host, port, path))
-    )
+    await _run_with_shutdown(_get_mcp().run_async(**_http_run_kwargs(host, port, path)))
 
 
 def _healthz_enabled() -> bool:
@@ -1137,8 +1121,6 @@ def _oidc_allowed_client_redirect_uris() -> list[str] | None:
 def register_browser_landing(
     mcp_instance: "FastMCP | _DeferredMCP",
     path: str,
-    *,
-    quiet_probe_log: bool = True,
 ) -> None:
     """Register the friendly browser landing page and tidy the uvicorn access log.
 
@@ -1152,24 +1134,16 @@ def register_browser_landing(
     Args:
         mcp_instance: The FastMCP server to register the route on.
         path: The MCP endpoint path (e.g. "/mcp" or a secret path).
-        quiet_probe_log: When True (default, for Streamable HTTP), drop the
-            by-design GET/HEAD-405 probe line on the MCP path from the uvicorn
-            access log (the handler logs an annotated replacement). Pass False
-            for SSE, where a GET answers 200 and a 405 is a genuine fault.
     """
     if not _register_landing_route(mcp_instance, path):
         # Already registered for this path — don't double-attach the log filter.
         return
 
-    # Tidy uvicorn's access log: always drop browser favicon 404s, and drop the
-    # raw by-design GET/HEAD-405 probe line on the MCP path (the landing handler
-    # logs an annotated replacement). The 405 drop is skipped for SSE
-    # (quiet_probe_log=False), where a GET answers 200 and a 405 is a real fault.
-    # Attach to uvicorn.access directly — it has propagate=False, so a root-logger
-    # filter would miss it.
-    logging.getLogger("uvicorn.access").addFilter(
-        ProbeAccessLogFilter(path, drop_mcp_405=quiet_probe_log)
-    )
+    # Tidy uvicorn's access log: drop browser favicon 404s and the raw by-design
+    # GET/HEAD-405 probe line on the MCP path (the landing handler logs an
+    # annotated replacement). Attach to uvicorn.access directly — it has
+    # propagate=False, so a root-logger filter would miss it.
+    logging.getLogger("uvicorn.access").addFilter(ProbeAccessLogFilter(path))
 
 
 def _log_settings_url(
@@ -1229,7 +1203,7 @@ def _log_settings_url(
 
 # Truthy / falsy env-var spellings for HA_MCP_DISABLE_SETTINGS_UI, matching the
 # parsing in stdio_settings_sidecar.py so the toggle behaves the same across
-# transports. A value in neither set is unrecognized: fail closed (disable) with
+# entry points. A value in neither set is unrecognized: fail closed (disable) with
 # a warning, since this is a security kill switch and failing open on a typo
 # would leave an unauthenticated surface up.
 _SETTINGS_TRUTHY = {"1", "true", "yes", "on"}
@@ -1239,9 +1213,9 @@ def _log_settings_url(
 def _settings_ui_disabled() -> bool:
     """Return True when ``HA_MCP_DISABLE_SETTINGS_UI`` turns the settings UI off.
 
-    Honored by every long-lived HTTP transport (standard ``ha-mcp-web`` /
-    ``ha-mcp-sse`` as well as OAuth/OIDC) and, with matching semantics, by the
-    stdio sidecar. As a security kill switch it fails **closed**: any value that
+    Honored by every long-lived HTTP transport (standard ``ha-mcp-web`` as well
+    as OAuth/OIDC) and, with matching semantics, by the stdio sidecar. As a
+    security kill switch it fails **closed**: any value that
     is neither a recognized truthy nor falsy spelling disables the UI and warns
     (so the operator learns why it vanished), rather than leaving an
     unauthenticated surface up on a typo. Unset — or an explicit falsy value —
@@ -1373,11 +1347,10 @@ def _register_settings_ui_secret_path(
     )
 
 
-def _run_http_server(transport: str, default_port: int = 8086) -> None:
-    """Common runner for HTTP-based transports.
+def _run_http_server(default_port: int = 8086) -> None:
+    """Common runner for the standard-mode Streamable HTTP server.
 
     Args:
-        transport: Transport type (http or sse).
         default_port: Default port to use if MCP_PORT env var is not set.
     """
     from ha_mcp.settings_ui import register_settings_routes
@@ -1386,9 +1359,7 @@ def _run_http_server(transport: str, default_port: int = 8086) -> None:
     # _get_mcp below, before the app is built) -- see transport_security.
     host, port, path = _get_http_runtime(default_port)
     _warn_if_default_path_exposed(host, port, path)
-    # SSE transport answers GET with 200 (the event stream), so a GET->405 there
-    # would be a real fault, not a benign probe — keep its access log intact.
-    register_browser_landing(_get_mcp(), path, quiet_probe_log=transport != "sse")
+    register_browser_landing(_get_mcp(), path)
     if _healthz_enabled():
         _register_healthz_route(_get_mcp())
     if _settings_ui_disabled():
@@ -1400,7 +1371,7 @@ def _run_http_server(transport: str, default_port: int = 8086) -> None:
         _log_settings_url(host, port, path)
 
     _run_entrypoint(
-        _run_http_with_graceful_shutdown(transport, host, port, path),
+        _run_http_with_graceful_shutdown(host, port, path),
         "HTTP server",
     )
 
@@ -1418,23 +1389,7 @@ def main_web() -> None:
       settings UI at all
     """
     _setup_standard_mode()
-    _run_http_server("http", default_port=8086)
-
-
-def main_sse() -> None:
-    """Run server using Server-Sent Events transport for MCP clients.
-
-    Environment:
-    - HOMEASSISTANT_URL (required)
-    - HOMEASSISTANT_TOKEN (required)
-    - MCP_HOST (optional, default: "0.0.0.0"; set 127.0.0.1 to restrict to loopback)
-    - MCP_PORT (optional, default: 8087)
-    - MCP_SECRET_PATH (optional, default: "/mcp")
-    - HA_MCP_DISABLE_SETTINGS_UI (optional): set truthy to not serve the web
-      settings UI at all
-    """
-    _setup_standard_mode()
-    _run_http_server("sse", default_port=8087)
+    _run_http_server(default_port=8086)
 
 
 def main_oauth() -> None:
@@ -1568,9 +1523,7 @@ async def _run_oauth_server(
         f"Starting OAuth-enabled MCP server with {len(tools)} tools on {base_url}{path}"
     )
 
-    await _run_with_shutdown(
-        mcp.run_async(**_http_run_kwargs("http", host, port, path))
-    )
+    await _run_with_shutdown(mcp.run_async(**_http_run_kwargs(host, port, path)))
 
 
 def main_oidc() -> None:
@@ -1763,7 +1716,7 @@ async def _run_oidc_server(
     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))
+        mcp_instance.run_async(**_http_run_kwargs(host, port, path))
     )
 
 

src/ha_mcp/__main__.py

@@ -150,7 +150,7 @@ def register_healthz(mcp_instance: CustomRouteServer) -> bool:
     """Register a GET ``/healthz`` liveness route answering 200 with JSON.
 
     Lets uptime monitors, blackbox probes, and load balancers confirm the HTTP
-    server is alive without knowing the MCP path. Standard-mode HTTP/SSE
+    server is alive without knowing the MCP path. Standard-mode HTTP
     authenticates by URL-path secrecy (SECURITY.md -> Threat Model), so this
     route is opt-in (``MCP_HEALTHZ`` env var, checked by the caller) and the
     response body deliberately does not echo the MCP path.

src/ha_mcp/browser_landing.py

@@ -166,7 +166,7 @@ async def _get_advanced_settings(
         )
     ]
     # is_stdio: the sidecar-port field only applies when this settings page
-    # is served by the stdio settings-UI sidecar. In HTTP/SSE/OAuth/addon
+    # is served by the stdio settings-UI sidecar. In HTTP/OAuth/addon
     # deployments there is no sidecar, so the UI greys the section.
     return JSONResponse(
         {

src/ha_mcp/settings_ui/_handlers_advanced.py

@@ -3619,7 +3619,7 @@ async function loadAdvancedSettings() {
 
 function applySidecarAvailability(isStdio) {
   // The sidecar-port setting only applies when this settings page is served
-  // by the stdio settings-UI sidecar. In HTTP/SSE/OAuth/addon deployments
+  // by the stdio settings-UI sidecar. In HTTP/OAuth/addon deployments
   // there is no sidecar, so dim + disable the section and explain why, rather
   // than letting a user save a value that does nothing.
   // Remove any note from a prior load first, so the <h2> title is once again