한 줄 요약: homeassistant-ai/ha-mcp는 Claude·ChatGPT·Gemini 같은 AI 클라이언트가 Home Assistant(HA)를 제어하는 수준을 넘어 설정·구축·디버깅까지 하게 해 주는 MCP(Model Context Protocol) 서버입니다. MIT 라이선스, 최신 안정판 v9.1.2(2026-11-09 KST), master에는 하루에도 여러 번 9.2.0.devN 빌드가 올라옵니다. 오늘(2026-11-11) GitHub Trending 일간 전체 7위·Python 3위(하루 +790★), 누적 약 6,700★·430 fork. 이 글은 내장 MCP Server와의 차이, 배치·인증 설계, 77개 도구 카탈로그와 tool search, 쓰기 안전장치를 코드·문서 기준으로 정리하고, 박스에서 PyPI 패키지를 설치해 카탈로그 모드별 tools/list 크기와 차단 동작을 직접 재 본 결과를 담았습니다.
1. 왜 지금 트렌딩인가: HA 2026.11 Marketplace와 v9 보안 재설계
타이밍이 겹쳤습니다. Home Assistant 2026.11부터 HACS가 Settings → Marketplace로 기본 탑재되면서, ha-mcp가 기본 카탈로그에 들어가 GitHub 연결이나 커스텀 저장소 추가 없이 설치·업데이트됩니다. 동시에 10월 28일 v9.0.0에서 In-process 서버의 보안 모델이 크게 바뀌었습니다(관리자 본인 토큰으로 실행, OAuth 콜백 allowlist, 컴포넌트 릴리스가 서버 버전을 고정·자동 셀프업데이트 중단, 신규 엔트리의 잠금 기본값, 로그에 비밀값 미기록). 11월 4일 v9.1.0은 URL별 카탈로그 고정(/catalog/full, /catalog/search), 자동화 도구를 HA Core 자체 검증·저장 경로로 옮기는 변경, IPv6 로컬 네트워크 지원을 넣었고, v9.1.2는 HACS 중복 리스팅 정리와 자동화·스크립트·씬 참조 검사를 Core 쪽으로 넘겼습니다.
요컨대 “LLM에게 집 전체 관리자 권한을 주는” 도구가, 설치 장벽은 낮아지고 권한 경계는 오히려 더 단단해지는 쪽으로 동시에 움직인 주간입니다.
| 항목 | 값 (2026-11-11 12:00 KST 기준) |
|---|---|
| 저장소 | homeassistant-ai/ha-mcp (기본 브랜치 master, 2025-09 생성) |
| 라이선스 | MIT |
| 안정판 | v9.1.2 (2026-11-09 00:45 KST) · v9.1.0 (11-04) · v9.0.0 (10-29) |
| 개발판 | 9.2.0.dev3471 (2026-11-11 09:26 KST), master 푸시마다 .devN 발행 |
| 런타임 | Python >=3.13,<3.15 (HA Core 2026.7이 3.14를 쓰기 때문에 상한을 넓힘) |
| 프레임워크 | FastMCP · MCP SDK · websockets를 _vendor로 벤더링 (HA Core의 mcp 1.x 핀과 충돌 방지) |
| 도구 수 | README 배지 87개(베타 포함) · 박스 실측 기본 노출 77개 |
| Trending | 일간 전체 7위, Python 3위, 하루 +790★ |
2. 내장 MCP Server와 무엇이 다른가
HA에는 이미 공식 mcp_server 통합이 있습니다. 그런데 그쪽은 Assist 파이프라인 위에 지어져 있어서, Assist에 노출(expose)한 엔티티를 읽고 Assist가 이해하는 인텐트를 실행하는 것이 범위입니다. 음성 비서처럼 “거실 불 꺼”에는 충분하지만, “어젯밤 모션 자동화가 왜 안 돌았는지 trace를 보고 고쳐 줘”는 못 합니다. ha-mcp는 반대로 구성(configuration) 표면 전체를 도구로 노출합니다.
| 능력 | HA 내장 MCP Server | ha-mcp |
|---|---|---|
| 노출 기기 제어 · 상태 조회 | 예 | 예 |
| 엔티티 범위 | Assist에 노출된 엔티티만 | HA 전체 |
| 자동화 · 스크립트 · 씬 생성/수정 | 아니오 | 예 |
| 대시보드(Lovelace) 편집 | 아니오 | 예 (search/replace 패치 포함) |
| trace · 히스토리 · 로그 기반 디버깅 | 아니오 | 예 |
| 헬퍼 · 구역 · 존 · 라벨 · 그룹 | 아니오 | 예 |
| 백업 · 앱 · HACS · 기기/엔티티 레지스트리 | 아니오 | 예 |
| 권한 모델 | Assist 노출 설정 | 서버가 쥔 관리자 토큰 + 자체 Read Only/정책 |
실무적으로는 둘을 경쟁 관계로 볼 필요가 없습니다. 음성·일상 제어는 내장 통합, “집을 만드는” 작업은 ha-mcp라는 README의 권고가 합리적입니다. 다만 ha-mcp 쪽 권한 상한이 사실상 관리자 토큰 전체라는 점이 이후 모든 설계 판단의 전제가 됩니다.
3. 저장소 구조: 서버 하나, 배포 표면 여럿
트리를 보면 이 프로젝트가 “MCP 서버 코드”보다 “배포 표면과 안전장치”에 더 많은 코드를 쓴다는 게 보입니다.
| 경로 | 역할 | 실무 포인트 |
|---|---|---|
src/ha_mcp/ |
서버 본체: server.py, tool_catalog.py, tool_dispatch.py, http_transport.py |
REST·WebSocket 클라이언트(client/), 요청 큐(ha_request_queue.py) |
src/ha_mcp/tools/ |
도구 구현 약 150개 모듈 | best-practice 검사기, config entry flow walker, 백업 스냅샷/복원 |
src/ha_mcp/policy/ |
도구별 승인 정책 (evaluator, approval_queue, persistence) | Predicate DSL: eq/neq/in/not_in/regex/contains/exists/gt/lt |
src/ha_mcp/read_only.py |
카탈로그 필터 + 호출 시점 차단 | readOnlyHint가 True가 아니면 쓰기로 간주(fail-closed) |
src/ha_mcp/transforms/, visibility/ |
tool search, 엔티티 가시성 | FastMCP BM25 검색 transform 기반 |
custom_components/ha_mcp_tools/ |
HA 통합(In-process 서버 + File & YAML 엔트리) | OAuth DCR, 웹훅, 리다이렉트 allowlist, 사이드바 패널 |
homeassistant-addon*/ |
HA 앱(add-on) 본판·dev판, Webhook Proxy 앱 | Nabu Casa 경유 원격 접속 |
rules/, scripts/*_ratchet.py |
ast-grep 규칙, 모듈 크기·중복 코드 ratchet | “가짜 Core 객체 금지” 등 테스트 위생을 CI로 강제 |
.claude/skills/, .github/slash-agent/ |
이슈 분석·PR 리뷰용 에이전트 스킬, Codex 리뷰 워크플로 | 유지보수 자체를 에이전트로 돌리는 저장소 |
눈여겨볼 결정은 FastMCP·MCP SDK 벤더링입니다. In-process 모드에서는 ha-mcp가 HA Core의 파이썬 인터프리터 안에서 import되는데, Core가 자체적으로 mcp 1.x를 핀하고 있어 그대로 의존하면 해결 불가능한 버전 충돌이 납니다. 그래서 scripts/vendor_fastmcp.py로 통째로 들여와 ha_mcp._vendor.* 이름공간에 격리했습니다. 대가로 패키지가 커집니다(박스 실측 site-packages 26MB). 서버 기동 시 FastMCP 배너가 “fastmcp 4.1.8 업데이트 가능”을 띄우는데, 벤더링된 사본이라 pip install --upgrade fastmcp는 의미가 없다는 점도 알아 두면 헷갈리지 않습니다.
4. 배치 선택: “하나만” 고르라는 경고의 이유
v9 기준 권장 경로는 In-process 통합입니다. HACS/Marketplace로 ha_mcp_tools 컴포넌트를 깔면, 컴포넌트 릴리스가 고정한 ha-mcp 서버 빌드를 HA가 통합 요구사항으로 설치하고, HA 안에서 별도 스레드로 서버를 돌립니다(느린 도구 호출이 HA 이벤트 루프를 막지 않도록). HA 자신의 리스너에 관리자 장기 토큰으로 붙고, HA 웹훅을 등록해 MCP 트래픽을 전달합니다. 덕분에 Nabu Casa나 기존 리버스 프록시가 있으면 별도 터널·포트포워딩 없이 원격 URL이 생깁니다.
| 방식 | 대상 설치형 | 연결 URL | 장점 | 주의 |
|---|---|---|---|---|
| In-process 통합 (권장) | HAOS·Supervised·Container·Core 전부 | /api/webhook/<id>, 로컬 :9584/private_<random> |
기능 동등, 웹훅으로 원격, 사이드바 설정 패널 | HA 2026.8.0+ (Core 2026.7 미만은 로드 불가) |
| HA 앱(add-on) | HAOS·Supervised | 앱 로그에 표시되는 URL | 토큰 관리 불필요 | 원격은 Webhook Proxy 앱 필요 |
| Docker / uvx HTTP | Container·Core·별도 호스트 | 비밀 경로 URL 또는 OIDC | HA 밖에서 격리 운영 | 장기 토큰 직접 관리 |
| 로컬 stdio | 개발자 PC | – | 데모 스크립트 한 줄 | 전송 이슈(#1713), 실사용 비권장 |
README가 굵게 경고하는 운영 함정은 한 클라이언트에 같은 서버의 두 설치를 동시에 붙이는 것입니다(예: 로컬 uvx ha-mcp@latest 엔트리와 앱 URL을 함께 등록). 연결 hang의 알려진 원인이고, In-process 서버는 앱·Docker·stdio를 “대체”하므로 병행 운영하지 말라고 못 박습니다. 또 v9.0.0부터 컴포넌트가 서버를 스스로 업데이트하지 않고 컴포넌트 릴리스가 핀한 버전만 돌리므로, 서버 업데이트는 곧 컴포넌트 업데이트 + HA 재시작이라는 점을 운영 절차에 반영해야 합니다.
5. 인증 세 가지(+OIDC)와 각자의 위협 모델
문서가 가장 공들인 부분입니다. 핵심 전제는 “서버는 언제나 관리자 토큰으로 HA를 호출한다”이고, 인증 모드는 누가 그 서버에 말을 걸 수 있는가만 결정합니다.
| 모드 | 자격 증명 | 강점 | 트레이드오프 |
|---|---|---|---|
none |
고엔트로피 웹훅 ID가 든 URL 자체 | 가장 단순, 대부분 클라이언트 호환 | URL 유출 = 관리자 권한 유출. claude.ai처럼 OAuth를 강제하는 클라이언트용 “무로그인 승인”은 콜백 allowlist에 있는 주소로만 리다이렉트 |
ha_auth |
HA 관리자 계정 로그인 (Core가 OAuth AS 역할) | 별도 비밀 없음, 인터넷 노출 시 권장 | 비관리자 로그인은 거부 (조용히 관리자급 권한을 주지 않기 위해) |
legacy |
정적 Client ID/Secret (자체 OAuth 2.1 서버, 1h access / 30d refresh) | 붙여넣을 자격 증명이 필요한 클라이언트용 | Secret이 곧 관리자급 자격. 회전 후에도 HA 재시작 전까지 기존 토큰 유효 |
| OIDC (외부 서버 배치) | Authentik·Keycloak·Auth0 등 | 기존 IdP로 게이트 | 인증된 모든 사용자가 서버의 HA 자격 증명을 공유 |
두 가지 세부가 실무적으로 중요합니다. 첫째, Allowed OAuth callback URLs. v9 이전에는 아무 콜백이나 받았기 때문에, 기본 목록(claude.ai/claude.com, Claude Code, ChatGPT, Gemini Enterprise)에 없는 클라이언트는 업그레이드 후 콜백을 직접 추가해야 합니다. “Allow any OAuth callback URL”을 켜면 편하지만, 문서 표현 그대로 내 HA 주소가 임의 사이트로 로그인 링크를 전달하는 피싱 발판이 될 수 있습니다. 둘째, 토큰 검증은 서버 시작 시점에만 일어납니다. 실행 중 토큰을 폐기하면 요청이 실패하기 시작하지만, 관리자 권한을 잃은 계정은 다음 재시작까지 줄어든 권한으로 계속 서비스됩니다. 권한 회수 절차에 “재시작”을 반드시 포함시키세요.
토큰 주체도 고민거리입니다. README는 본인 계정의 장기 토큰(유출 시 어디서든 동작, 변경 이력이 본인 이름으로 남음)보다 HA-MCP 전용 계정(Allow login + Local access only + Administrator)을 만들어 그 로그인으로 토큰을 생성하는 쪽을 더 안전하다고 권합니다. 감사 로그에서 AI가 바꾼 것과 사람이 바꾼 것을 구분할 수 있다는 부수 효과도 큽니다.
6. 77개 도구 카탈로그와 BM25 tool search
도구는 Areas & Floors, Automations, Blueprints, Calendar, Dashboards, Device/Entity Registry, Energy, Groups, HACS, Helpers, History & Statistics, Integrations, Labels & Categories, Matter/Z-Wave(ha_manage_radio), Scenes, Scripts, Search, Service & Device Control, System, Todo, Zones 등으로 나뉩니다. 이름 규칙이 일관적입니다: ha_config_get_* / ha_config_set_* / ha_config_remove_*, 여러 동작을 묶은 ha_manage_*. 파일·YAML 편집(ha_read_file, ha_write_file, ha_config_set_yaml 등)은 베타 플래그 + File & YAML 엔트리가 있어야만 켜집니다.
문제는 컨텍스트 비용입니다. 지연(deferred) 도구 로딩을 지원하는 클라이언트(claude.ai, Claude Desktop, Claude Code)는 상관없지만, 모든 스키마를 프롬프트에 인라인하는 클라이언트(GitHub Copilot CLI 등)나 소형·로컬 모델에는 수백 KB의 스키마가 그대로 부담이 됩니다. 그래서 ENABLE_TOOL_SEARCH=true를 켜면 전체 카탈로그 대신 검색 진입점 + 프록시 3개 + pinned 도구만 노출합니다.
| 카탈로그 모드 (박스 실측) | 노출 도구 | readOnlyHint | tools/list JSON | 용도 |
|---|---|---|---|---|
| 기본 (full) | 77 | 32 | 305,103 B | 지연 로딩 클라이언트 |
READ_ONLY_MODE=true |
40 | 32 | 159,021 B | 관찰·분석 전용 에이전트 |
ENABLE_TOOL_SEARCH=true |
11 | 7 | 50,680 B | 소형 모델, 도구 수 상한(100개 등) 있는 클라이언트 |
| Search + Read Only | 8 | 7 | 38,088 B | 자동화 파이프라인의 읽기 전용 감시자 |
측정 조건: ha-mcp 9.1.2(PyPI), Python 3.13.5, stdio, HA 미연결(더미 토큰), 2026-11-11 11:57 KST, MCP 클라이언트가 받은 Tool 객체를 JSON 직렬화한 바이트. 토큰으로 대략 환산하면(4바이트≈1토큰 가정) 기본 약 7.6만, search 모드 약 1.3만 토큰으로 약 1/6입니다. 흥미로운 점은 ENABLE_BETA_FEATURES=true만 켜서는 카탈로그가 77개 그대로였다는 것인데, 파일/YAML 도구는 마스터 베타 플래그에 더해 하위 플래그와 컴포넌트 엔트리가 함께 있어야 열리기 때문입니다.
search 모드에서 실제로 노출된 11개는 ha_search_tools, ha_call_read_tool, ha_call_write_tool, ha_call_delete_tool에 pinned 도구 ha_report_issue, ha_config_get_automation, ha_config_set_automation, ha_get_overview, ha_search, ha_manage_backup, ha_get_skill_guide였습니다. ha_search_tools("automation trace debug")를 호출하면 숨은 도구를 이름·한 줄 설명·한 줄 params·실행 프록시로 압축해 돌려주고(1단계), tools=[...]로 다시 물으면 전체 스키마를 줍니다(2단계). 즉 모델은 “검색 → 정의 조회 → 프록시 호출”의 2홉을 거치는 대신 컨텍스트를 아낍니다. 이미 클라이언트 자체 tool search가 있는 환경에서는 이중 검색이 되므로 끄라는 게 문서의 권고입니다.
v9.1의 URL별 카탈로그는 여러 클라이언트가 한 서버를 공유할 때 유용합니다. 같은 비밀 URL 뒤에 /catalog/full, /catalog/search, /readonly/catalog/search를 붙이면 연결 단위로 카탈로그가 고정되어, Claude Code에는 전체 목록을, 로컬 Ollama 에이전트에는 읽기 전용 검색 카탈로그를 주는 식의 분리가 서버 하나로 됩니다.
7. 쓰기 안전장치: 다섯 겹의 관문
LLM이 집 전체 관리자 권한으로 쓰기를 한다는 사실을 어떻게 다루는지가 이 프로젝트의 진짜 설계 포인트입니다.
| 관문 | 구현 | 동작 | 한계 |
|---|---|---|---|
| 연결 URL | /readonly, /catalog/* 접미사 |
연결 수명 동안 모드 고정, 웹훅 URL에도 적용 | 같은 자격 증명으로 일반 엔드포인트도 접근 가능 (권한이 아닌 연결 모드) |
| 카탈로그 필터 | ReadOnlyToolsTransform |
readOnlyHint가 True가 아닌 도구는 목록에서 숨김 (fail-closed) | 클라이언트 캐시 목록에는 남아 있을 수 있음 |
| 호출 시점 차단 | ReadOnlyMiddleware |
캐시된 도구·검색 프록시 경유 호출도 READ_ONLY_MODE 에러로 차단 |
혼합 도구(ha_manage_*)는 인자 수준 판정으로 읽기만 허용 |
| 도구별 보안 정책 | policy/ (Predicate DSL) |
args.domain in ["lock","alarm_control_panel"] 같은 조건에 require_approval 또는 allow |
정책 파일 스키마 v2 (조건별 OR 의미). 잘못된 값은 저장 단계에서 거부 |
| 자동 편집 백업 | tools/backup_*, 스냅샷 복원 |
편집 전 스냅샷, HA 자체 백업 위치에 저장, 복원 시 새 안전 백업·검증 요구 | 엔티티/기기 레지스트리 기타 설정은 복원 대상 아님 |
박스에서 Search + Read Only 모드로 띄운 뒤 ha_call_write_tool(name="ha_config_set_automation")을 호출하자, HA에 닿기도 전에 {"success": false, "error": {"code": "READ_ONLY_MODE", ...}}가 돌아왔고 “no changes were made”와 함께 설정 UI에서 끄는 방법을 제안으로 담았습니다. 에러가 문자열이 아니라 code·message·suggestions 구조라는 점은 에이전트 루프에서 재시도/포기 판단을 코드로 분기하기 좋게 만듭니다. HA가 없는 상태에서 ha_get_overview를 부르면 마찬가지로 CONNECTION_FAILED와 점검 순서를 구조화해 돌려줍니다.
프록시 3분할(read/write/delete)도 같은 맥락입니다. 클라이언트가 도구 docstring을 파싱하지 않고도 “읽기는 자동 승인, 쓰기는 확인, 삭제는 재확인” 같은 정책을 걸 수 있습니다. 다만 프록시 이름만 보고 안전하다고 단정하면 안 됩니다. ha_manage_*처럼 묶인 도구는 write/delete 프록시에서는 전체가, read 프록시에서는 Read Only가 승인한 읽기 동작만 실행된다는 규칙을 이해해야 정책이 의도대로 걸립니다.
8. 설치·실행 레시피 (실무자용)
A. 외부 호스트에서 HTTP 서버로 (Container/Core 설치, 격리 선호)
# 1) HA 전용 관리자 계정(로컬 접속만 허용)으로 장기 토큰 발급
# 2) PyPI 패키지로 실행 (Python 3.13+)
uv venv -p 3.13 .venv && . .venv/bin/activate
uv pip install ha-mcp==9.1.2
ha-mcp-smoke-test # 의존성·도구 발견 자가 점검
export HOMEASSISTANT_URL=http://homeassistant.local:8123
export HOMEASSISTANT_TOKEN=*** # 비밀 관리자로 주입
export READ_ONLY_MODE=true # 첫 주는 읽기 전용으로 관찰
export ENABLE_TOOL_SEARCH=true # 소형/로컬 모델이면
export MCP_HOST=127.0.0.1 # 기본값 0.0.0.0 — 리버스 프록시 뒤라면 루프백으로 좁히기
export MCP_PORT=8086 # 기본값
export MCP_SECRET_PATH=/private_$(openssl rand -hex 16) # 기본값 /mcp — 반드시 바꿀 것
ha-mcp-web # Streamable HTTP 진입점 (main_web)ha-mcp-web의 기본 바인딩이 0.0.0.0:8086, 기본 경로가 /mcp라는 점은 꼭 기억하세요. 비밀 경로를 바꾸지 않은 채 LAN에 띄우면 같은 네트워크의 누구나 관리자 권한 MCP에 접근할 수 있습니다. 공식 Docker 이미지(ghcr.io/homeassistant-ai/ha-mcp)나 OAuth(ha-mcp-oauth)·OIDC(ha-mcp-oidc) 진입점도 같은 패키지에 들어 있습니다.
B. HA 안에서 (권장): HA 2026.11+ Settings → Marketplace에서 HA-MCP 설치 → 재시작 → Devices & Services → Add Integration → HA-MCP Server → 토큰 또는 전용 계정 로그인 → 원격(Secret URL 또는 HA sign-in)/로컬 네트워크 선택 → Configure 화면의 연결 URL을 클라이언트에 등록. 둘 다 기본 비활성이라 다른 기기의 클라이언트는 하나를 반드시 켜야 합니다.
C. 평가(eval) 방법 제안: 저장소에는 HAOS 이미지를 띄우는 E2E·성능 워크플로가 있지만, 자기 환경에서는 다음 순서가 현실적입니다. (1) Read Only + search 카탈로그로 “지난 24시간 자동화 실패 trace 요약” 같은 읽기 과제 10개를 돌려 도구 선택 정확도를 봅니다. (2) 스테이징 HA(컨테이너)에서 쓰기를 켜고 자동화 생성·수정 과제를 돌린 뒤 자동 백업으로 롤백이 되는지 확인합니다. (3) 마지막으로 보안 정책에 lock, alarm_control_panel, cover(차고문) 도메인 승인 규칙을 넣고 운영 HA에 붙입니다.
9. 비교: HA를 AI에 붙이는 다른 선택지
| 선택지 | 범위 | 강점 | 약점 | 추천 상황 |
|---|---|---|---|---|
| HA 내장 MCP Server | Assist 노출 엔티티 제어 | 공식, 노출 범위가 곧 권한 | 구성·디버깅 불가 | 음성·일상 제어 |
| HA 내장 LLM 대화 에이전트 (Assist + LLM API) | HA 안에서 대화형 제어 | 별도 서버 없음 | 외부 코딩 에이전트와 연동 아님 | 집 안 음성 비서 |
| ha-mcp | HA 구성 전체 (77~87 도구) | 자동화·대시보드·trace·백업, 다층 안전장치 | 관리자 토큰 위임, 큰 스키마 (search로 완화) | AI로 HA를 구축·유지보수 |
| 범용 REST/OpenAPI 브리지 MCP | HA REST API 그대로 | 간단, 의존성 적음 | WebSocket 전용 기능·검증·백업 없음, 모델이 API를 알아야 함 | 단순 상태 조회 스크립트 |
| Node-RED + LLM 노드 | 플로 기반 자동화 | 시각적 플로, 이벤트 처리 | HA 구성 편집 도구 아님, 노출 시 보안 위험 | 이벤트 파이프라인 |
함께 쓰면 좋은 것으로 homeassistant-ai/skills가 있습니다. MCP 서버는 “무엇을 할 수 있는가”를 주지만 “어떻게 구조화해야 하는가”에는 의견이 없어서, 에이전트가 Jinja 템플릿에 과의존하거나 헬퍼 타입을 잘못 고르는 일이 생깁니다. ha-mcp는 이 스킬을 번들해 skill:// MCP 리소스로 제공하고(박스 실측 리소스 17개), 리소스를 지원하지 않는 클라이언트를 위해 끌 수 없는 필수 도구 ha_get_skill_guide를 둡니다.
10. 도입 전 체크리스트와 주의점
| 체크 항목 | 권장 | 이유 |
|---|---|---|
| 토큰 주체 | HA-MCP 전용 관리자 계정, Local access only | 유출 범위 축소, 감사 로그 분리 |
| 인터넷 노출 | ha_auth 우선, none URL은 비공개 유지 |
URL이 곧 관리자 자격 |
| OAuth 콜백 | “Allow any” 끄고 필요한 콜백만 추가 | 피싱 리다이렉트 발판 방지 |
| 초기 운영 | /readonly 연결로 1~2주 관찰 |
도구 선택 품질 확인 후 쓰기 개방 |
| 고위험 도메인 | 잠금·경보·차고문에 require_approval |
물리적 안전과 직결 |
| 설치 중복 | 클라이언트당 설치 1개만 등록 | 연결 hang의 알려진 원인 |
| 설정 변경 후 | 클라이언트에서 도구 목록 새로고침 | 캐시된 목록 때문에 Unknown tool·RO 에러 발생 |
| 권한 회수 | 토큰 폐기 + 서버(HA) 재시작 | 권한 검증이 시작 시점에만 이뤄짐 |
| 업데이트 | 안정판 채널 유지, dev 채널은 스테이징에서 | master 푸시마다 .devN 발행 |
마지막으로 범위의 한계를 분명히 해 두겠습니다. 이번 박스 테스트는 실제 HA 인스턴스 없이 설치·도구 발견·카탈로그 모드·차단 동작까지만 확인했습니다. 실제 기기 제어, 자동화 생성 품질, 백업 복원은 실 HA(최소한 컨테이너 스테이징)가 있어야 평가할 수 있습니다. 또 프라이버시 문서는 현재 텔레메트리가 없고, 향후 익명 사용 통계가 들어오면 HA 분석 설정을 따르며 최소 한 달 전에 공지하겠다고 밝히고 있으니, 업데이트 노트를 확인하는 습관을 들이는 편이 좋습니다.
정리하면 ha-mcp는 “AI에게 집 열쇠를 주는 도구”를 꽤 진지하게 만든 사례입니다. 기능 목록보다 배울 만한 건 fail-closed 읽기 판정, 연결 단위 카탈로그, 프록시 3분할, 편집 전 백업이라는 설계 패턴이고, 이는 HA가 아닌 다른 관리 대상(NAS, 라우터, 사내 운영 도구)에 MCP를 붙일 때도 그대로 가져다 쓸 수 있습니다.