저는 로컬 우선(local-first) 네트워크 스캐너인 DeviceShelf를 만들었습니다. Server 에디션은 헤드리스(headless) 방식의 상시 가동 버전이며, 빌드 1.5.3부터는 Model Context Protocol (MCP)를 지원합니다. 이는 Claude Desktop과 같은 어시스턴트가 사용자의 실제 라이브 데이터를 바탕으로 다음과 같은 네트워크 관련 질문에 답할 수 있음을 의미합니다: "지금 온라인 상태인 것은 무엇인가요?", "어제 이후로 새로 나타나거나 오프라인이 된 것이 있나요?", "어떤 장치의 인증서가 곧 만료되나요?", "오늘 밤의 상태는 지난주 스냅샷과 어떻게 다른가요?"

이 포스트는 이것이 어떻게 연결되는지, 그리고 더 중요한 점은 어떻게 격리(fenced in)되는지에 관한 것입니다. 언어 모델(language model)에게 네트워크 인벤토리 읽기 권한을 부여하는 것은 어느 정도의 편집증적 주의가 필요한 일이기 때문입니다. 저는 개발자이므로 저의 열정은 적당히 걸러서 들어주시길 바랍니다. 아래의 설계 선택 사항들이 흥미로운 부분입니다.

엔드포인트(endpoint)가 노출하는 것

총 22개의 도구(14개의 읽기 전용, 8개의 선택적 액션), 3개의 가이드 프롬프트(guided prompts), 4개의 첨부 가능한 리소스(attachable resources), 그리고 변경 사항이 발생할 때 클라이언트로 푸시하는 선택적 라이브 모드로 구성됩니다. MCP는 이들을 연결하는 접착제 역할을 합니다. 즉, 사용자가 대시보드 출력을 채팅창에 복사하여 붙여넣는 대신, 어시스턴트가 해당 도구들을 스스로 발견하고 호출하게 됩니다.

모든 것은 사용자의 LAN 내에 머뭅니다

MCP 엔드포인트는 DeviceShelf Server 내부에서 API와 동일한 포트로 실행되며, 베어러 토큰(bearer token) 뒤에 위치하여 오직 사용자의 LAN에서만 접근 가능합니다. DeviceShelf 클라우드 커넥터나 원격 OAuth는 존재하지 않습니다. 네트워크를 벗어나는 유일한 것은 사용자가 연결하기로 선택한 AI 클라이언트가 전송하기로 결정한 데이터뿐입니다. 모델은 대시보드를 뒷받침하는 것과 동일한 프로세스 내 데이터(in-process data)를 읽으므로, 모델의 관점이 사용자가 직접 눈으로 보는 것과 어긋날 수 없습니다.

읽기 측면 (The read side)

14개의 읽기 도구는 모니터링 영역 전체를 다룹니다. 인벤토리는 단발성 개요를 위한 network_summary, 필터 및 페이지네이션이 포함된 list_devices, 자유 텍스트 검색을 위한 find_device ("프린터", "내 NAS"), 호스트별 상세 정보(열린 포트, OS, SNMP, TLS, 일치하는 CVE, 메모)를 위한 get_device, 그리고 멀티 NIC 수집기를 위한 list_interfaces로 구성됩니다.

Monitoring(모니터링)은 list_changes, list_alarms, list_checks, get_device_history, get_device_uptime(최대 90일간의 기기별 업타임) 및 list_offline_devices를 추가합니다. Security(보안)는 단 한 번의 호출로 해결됩니다: security_overview는 호스트별 조회를 수행하지 않고도 전체 네트워크에 걸쳐 만료 예정 및 만료된 인증서, 자가 서명 인증서, 그리고 심각도별로 그룹화된 알려진 CVE가 있는 호스트를 노출합니다. 또한 list_snapshots / diff_snapshots는 이름이 지정된 두 개의 캡처를 비교하거나, 캡처본을 라이브 스캔과 비교할 수 있어, "5월 감사 이후 무엇이 바뀌었나요?"라는 질문을 단 한 번의 질문으로 해결할 수 있습니다.

쓰기(Write) 기능은 두 단계의 선택 사항(opt-in)입니다

쓰기 기능은 기본적으로 꺼져 있습니다. 두 번째의 별도 스위치(DEVICESHELF_MCP_ALLOW_ACTIONS=true)를 통해 활성화해야 하며, 그제서야 어시스턴트가 실행 도구(action tools)를 갖게 됩니다: 기기 이름 변경 또는 태그 재지정, 알람 확인, 자연어를 사용한 모니터링 체크 생성 또는 삭제, 이름이 지정된 스냅샷 저장, 온디맨드(on-demand) 스캔 또는 TCP 포트 체크 트리거, 또는 테스트 알림 발송 등이 가능합니다. 탐색 동작(scan_now, port_check)은 사용자의 로컬에 연결된 서브넷으로 제한되며 속도 제한(rate-limited)이 적용됩니다.

이조차 너무 느슨하다고 느껴진다면, DEVICESHELF_MCP_CONFIRM_ACTIONS=true를 설정하여 영향력이 큰 동작들이 MCP 유도(elicitation)를 통해 클라이언트에게 먼저 승인을 요청하도록 만들 수 있습니다. 따라서 사용자가 확인을 클릭하지 않고는 스캔이 절대 실행되지 않습니다.

프롬프트(Prompts) 및 리소스(Resources)

도구 이름을 익히고 싶지 않은 사람들을 위해, 서버는 클라이언트의 프롬프트 선택기(prompt picker)에 나타나는 세 가지 가이드 프롬프트를 제공합니다: 보안 감사(security audit), "최근에 무엇이 변경되었나요" 보고서, 그리고 "알 수 없는 장치 식별"입니다. 클릭 한 번으로 유용한 답변을 얻을 수 있습니다. 또한 클라이언트가 도구 호출 없이도 컨텍스트로 첨부할 수 있는 네 가지 읽기 전용 리소스(deviceshelf://network/summary, deviceshelf://devices, deviceshelf://alarms, deviceshelf://security/overview)를 노출합니다.

라이브 모드(Live mode)

보안 표면(Security surface)으로 취급하기

사용자의 인벤토리를 읽는 AI는 다른 모든 클라이언트와 동일한 정밀 조사를 받습니다:

• /mcp는 API와 마찬가지로 인증(auth)이 필요합니다. 토큰이 없으면 응답하지 않습니다.
• 범위가 제한된 토큰(DEVICESHELF_MCP_TOKEN)은 /mcp에 대해서만 허용되며, 관리자 API나 메트릭(metrics)에는 절대 사용할 수 없습니다. 따라서 AI 클라이언트는 관리자 자격 증명(admin credential)을 보유하지 않게 됩니다.
• 모든 도구 호출(tool calls)은 속도 제한(rate-limited, 토큰 버킷 방식, 기본 300/min)이 적용되며, 인자(arguments)가 아닌 도구 이름과 결과에 따라 감사 로그(audit-logged)가 기록됩니다.
• 장치에서 보고하는 문자열(호스트 이름, 배너, 인증서 주체 등)은 신뢰할 수 없는 입력(untrusted input)으로 간주됩니다. 제어 문자 및 텍스트 위조 문자(bidi, zero-width 등)는 모델에 도달하기 전에 제거되고 값은 잘리며(truncated), 모델에는 이를 데이터로 취급하도록 지시합니다.
• Origin 허용 목록(allowlist)이 브라우저로부터의 DNS 리바인딩(DNS rebinding) 공격을 방어합니다.

마지막 그룹의 조치들이 제가 이 시스템을 제 개인 네트워크에서 신뢰할 수 있는 이유입니다. 악의적인 장치가 교묘하게 설정한 호스트 이름을 통한 프롬프트 주입(Prompt-injection)은 실제적인 위험이며, 위조 문자를 제거하고 문자열을 데이터로 표시하는 것이 지루하지만 올바른 정답입니다.

활성화하기

/etc/deviceshelf/server.env (또는 Docker 환경 변수)에서 다음과 같이 설정합니다:

DEVICESHELF_MCP_ENABLE=true

서버를 재시작하세요. 엔드포인트는 베어러 토큰(bearer token)과 함께 http://<your-server>:8088/mcp에서 제공됩니다. Claude Desktop에 연결하려면 mcp-remote를 사용하여 브릿지(bridge)를 연결하세요. --allow-http 옵션을 유지하고(LAN 내에서는 일반 HTTP이므로), 환경 변수를 통해 토큰을 전달하여 Windows의 인자 따옴표 처리 버그(argument-quoting bug)를 우회하세요:

{
  "mcpServers": {
    "deviceshelf": {
...

Streamable HTTP를 지원하는 모든 MCP 클라이언트는 직접 연결할 수 있습니다. 이 기능은 deviceshelf-server 1.5.3 버전(ghcr.io/wealthwallet/deviceshelf-server:1.5.3 Docker 이미지, .deb 또는 그 이후 버전)부터 사용 가능합니다. 기본적으로는 비활성화되어 있으며 완전히 추가적인(additive) 방식이므로, DEVICESHELF_MCP_ENABLE을 설정하기 전까지 기존 서버에는 영향을 주지 않습니다.

현재 상태

MCP는 별도의 구매 항목이 아니라 Server edition의 일부이며, 7일간의 체험판(trial) 기간 동안 작동하므로 평가해 볼 수 있습니다. 라이선스가 없는 체험 기간이 만료되면 엔드포인트는 402를 반환합니다. Server edition 자체는 여전히 퍼블릭 베타(public beta) 단계이므로 초기 단계로 간주해 주시기 바랍니다. 만약 도구가 잘못된 값을 반환하거나 체크 동작이 이상하다면 진심으로 제보를 부탁드립니다. 클라이언트 설정(Cursor, VS Code, Windsurf, Cline, Gemini CLI)을 포함한 전체 상세 내용은 DeviceShelf 블로그에 있으며, 프로젝트는 https://deviceshelf.app에서 확인할 수 있습니다.