MCP

Cos'e la competenza nomos MCP?

La competenza nomos MCP permette agli assistenti AI come Claude di comunicare direttamente con il nomos system Controller. Utilizzando il protocollo standardizzato Model Context Protocol (MCP), l'AI puo controllare dispositivi, eseguire scene, gestire stanze, creare automazioni e molto altro - il tutto tramite linguaggio naturale.

Prerequisiti

• Un client compatibile con MCP (ad es. Claude Desktop, Claude Code, Cursor, Windsurf)

• Node.js (versione 18 o superiore) installato sulla Sua macchina

• Accesso di rete al nomos system Controller (solo locale, nessun accesso esterno possibile)

Configurazione

Passaggio 1: Abilitare il modulo MCP in nomos

Il modulo MCP deve essere abilitato nell'interfaccia di configurazione nomos. Navighi su Competenze e si assicuri che il modulo MCP sia attivato.

Passaggio 2: Creare un token

Nell'interfaccia di configurazione nomos, naviga alla sezione MCP e crea un nuovo token. Questo token viene utilizzato per autenticare il client AI con il nomos system Controller. Prenda nota del token - Le servira per la configurazione del client.

• A ogni token puo essere assegnato un nome personalizzato (ad es. "Claude Desktop Ufficio")

• I token possono essere disabilitati o eliminati in qualsiasi momento

• Possono essere creati piu token per diversi client

Passaggio 3: Configurare il client

Esistono due modi per collegare il client MCP al nomos system Controller:

• Opzione A: nomos MCP Bridge (consigliato) – un proxy dedicato che gestisce le connessioni ai controller tramite una pagina di configurazione. Configurazione piu semplice, supporta piu controller, funziona con tutti i client MCP.

• Opzione B: Connessione diretta – configurare l'URL del controller e il token direttamente nella configurazione del client. Richiede la gestione manuale dei token.

---

Opzione A: nomos MCP Bridge (Consigliato)

La nomos MCP Bridge e un proxy locale leggero che gestisce le connessioni a uno o piu nomos system Controller. Invece di configurare URL e token direttamente, si registrano i controller tramite una pagina di configurazione web. La bridge funziona con qualsiasi client MCP che supporta server basati su stdio.

Claude Desktop

Apra le impostazioni di Claude Desktop e navighi alla sezione "MCP Servers". Aggiunga un nuovo server con la seguente configurazione:

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": ["-y", "nomos-mcp-bridge"]
    }
  }
}

Claude Code (CLI)

claude mcp add nomos -- npx -y nomos-mcp-bridge

Cursor

Aggiunga nelle impostazioni MCP di Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": ["-y", "nomos-mcp-bridge"]
    }
  }
}

Windsurf

Aggiunga nella configurazione MCP di Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": ["-y", "nomos-mcp-bridge"]
    }
  }
}

Altri client compatibili con MCP

Qualsiasi client che supporta server MCP basati su stdio puo utilizzare la bridge. Il comando e:

npx -y nomos-mcp-bridge

Gestione dei controller

Dopo aver configurato la bridge nel client MCP, puo gestire i controller utilizzando i seguenti comandi AI:

Comando	Descrizione
open_setup	Apre la pagina di configurazione web nel browser dove puo inserire il nome del controller, l'URL e il token MCP
add_controller	Aggiunge un nuovo controller direttamente tramite AI — fornire nome, URL e token
list_controllers	Elenca tutti i controller registrati e mostra quale e attualmente selezionato
select_controller	Si connette a un controller registrato per nome
remove_controller	Rimuove un controller registrato

---

Opzione B: Connessione diretta

Se preferisce configurare l'URL del controller e il token direttamente senza utilizzare la bridge, puo utilizzare le seguenti configurazioni.

Claude Desktop

Claude Desktop non supporta nativamente il protocollo di trasporto Streamable HTTP. La connessione viene stabilita tramite il pacchetto mcp-remote, che funge da ponte.

Apra le impostazioni di Claude Desktop e navighi alla sezione "MCP Servers". Aggiunga un nuovo server con la seguente configurazione:

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://<nomos-ip>/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}

Sostituisca <nomos-ip> con l'indirizzo IP o il nome host del Suo nomos system Controller e <your-token> con il token creato nel Passaggio 2.

Nota: Il parametro --allow-http e necessario perche il nomos system Controller e accessibile localmente tramite HTTP (non HTTPS).

Claude Code (CLI)

Claude Code supporta nativamente Streamable HTTP. Aggiunga il server tramite la riga di comando:

claude mcp add nomos \
  --transport streamable-http \
  "http://<nomos-ip>/mcp" \
  --header "Authorization: Bearer <your-token>"

Oppure lo configuri manualmente in ~/.claude/settings.json:

{
  "mcpServers": {
    "nomos": {
      "type": "streamable-http",
      "url": "http://<nomos-ip>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Cursor

Cursor supporta nativamente Streamable HTTP. Navighi su Settings > MCP e aggiunga un nuovo server:

{
  "mcpServers": {
    "nomos": {
      "type": "streamable-http",
      "url": "http://<nomos-ip>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Se la connessione non puo essere stabilita, può utilizzare in alternativa la variante mcp-remote come descritto per Claude Desktop.

Windsurf

Windsurf supporta nativamente Streamable HTTP. Apra la configurazione MCP e aggiunga:

{
  "mcpServers": {
    "nomos": {
      "type": "streamable-http",
      "url": "http://<nomos-ip>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Altri client compatibili con MCP

Il server nomos MCP utilizza il protocollo di trasporto Streamable HTTP. I client che supportano nativamente questo standard possono essere configurati direttamente:

• URL: http://<nomos-ip>/mcp

• Autenticazione: Token Bearer nell'header Authorization

• Tipo di trasporto: Streamable HTTP

Per i client che supportano solo server MCP basati su stdio (come Claude Desktop), mcp-remote puo essere utilizzato come ponte:

npx mcp-remote http://<nomos-ip>/mcp --allow-http --header "Authorization: Bearer <your-token>"

Panoramica delle funzionalita

Risorse

L'AI ha accesso ai dati in tempo reale dal Suo nomos system Controller:

• Tutti i componenti, scene, stanze, piani, timer e automazioni come elenchi panoramici

• Entita individuali con informazioni dettagliate (ad es. un dispositivo specifico con tutte le sue proprieta)

• Aggiornamenti in tempo reale: Le modifiche nel sistema vengono automaticamente segnalate all'AI

Prompt integrati

Stato e panoramica

Prompt	Descrizione
home_status	Panoramica completa dello stato attuale dell'intero sistema — tutte le stanze, i componenti e i loro valori
room_status	Stato attuale di tutti i componenti in una stanza specifica (nome della stanza o ID della stanza come parametro)
system_health	Controllo completo del sistema — connettività, dispositivi non raggiungibili, stato del cloud, accesso remoto, notifiche critiche

Report specifici

Prompt	Descrizione
climate_report	Riepilogo di temperatura, umidità e climatizzazione in tutte le stanze
energy_report	Riepilogo del consumo energetico e dei dati relativi alla potenza di tutti i componenti
security_status	Riepilogo di tutti i sensori di sicurezza — contatti porta/finestra, rilevatori di movimento, serrature, allarmi
notifications_summary	Riepilogo di tutte le notifiche correnti, raggruppate per priorità e tipo
automation_overview	Panoramica di tutte le automazioni e i timer — stato, trigger e azioni

Workflow di creazione guidata

Prompt	Descrizione
create_scene	Workflow guidato per creare una nuova scena basata su una descrizione dello stato desiderato
create_automation	Workflow guidato per creare una nuova automazione basata su una descrizione del comportamento desiderato
create_timer	Workflow guidato per creare una nuova automazione basata su timer

Esempi

Controllo dei dispositivi

"Accendi la luce in soggiorno."

"Regola la lampada del soffitto in camera da letto al 50%."

"Imposta il riscaldamento in bagno a 22 gradi."

Interrogazione dello stato

"Quali finestre sono attualmente aperte?"

"Mostrami lo stato di tutti i dispositivi in soggiorno."

"Qual e la temperatura attuale in cucina?"

Gestione delle scene

"Crea una scena chiamata 'Serata cinema' che abbassa le luci del soggiorno e chiude le tapparelle."

"Esegui la scena 'Buongiorno'."

Creazione di automazioni

"Crea un'automazione che accende le luci esterne al tramonto."

"Mostrami tutti i timer attivi."

Configurazione KNX

"Quali indirizzi di gruppo KNX sono disponibili nel progetto?"

"Importa il progetto KNX dal file."

Note importanti e limitazioni note

Solo accesso locale

L'endpoint MCP e accessibile solo tramite la rete locale. L'accesso dall'esterno (ad es. tramite internet) e bloccato dal sistema. Il client MCP deve trovarsi nella stessa rete del nomos system Controller.

Claude Desktop: Riavvio in caso di perdita di connessione

Importante: Se la connessione tra Claude Desktop e il server nomos MCP viene interrotta (ad es. a causa di un riavvio del nomos system Controller o di problemi di rete), Claude Desktop deve essere completamente riavviato. Chiudere e riaprire semplicemente la finestra della chat non e sufficiente - l'applicazione deve essere completamente chiusa e riavviata per ristabilire la connessione MCP.

Sicurezza dei token

• Tratti i token MCP come password

• Crei token separati per diversi client

• Disabiliti o elimini i token che non sono piu necessari

• I token garantiscono accesso completo a tutte le funzioni MCP - non esiste una gestione granulare dei permessi

Note generali su MCP

• Gestione delle sessioni: Ogni client riceve la propria sessione. Piu client possono essere collegati contemporaneamente.

• Notifiche automatiche: Le modifiche nel sistema (ad es. stato dei dispositivi) vengono automaticamente segnalate a tutti i client collegati. Potrebbe esserci un breve ritardo con molte modifiche simultanee (debouncing di 100ms).

• Gestione degli errori: Se uno strumento restituisce un errore, l'AI generalmente lo riconosce e visualizza un messaggio di errore utile.

Suggerimenti per l'utilizzo

• Sia il piu specifico possibile nelle Sue istruzioni (nomi delle stanze, nomi dei dispositivi)

• L'AI puo combinare piu azioni in una singola richiesta

• Utilizzi i prompt integrati per le attivita comuni

• Per automazioni complesse, si consiglia di costruirle passo dopo passo con l'AI