MCP

Der MCP-Endpunkt des Controllers und die nomos MCP Bridge

Der Controller enthält einen Server für das Model Context Protocol (MCP). Darüber lesen und steuern KI-Assistenten wie Claude das System: Geräte, Szenen, Räume, Automationen und vieles mehr.

Den MCP-Skill schalten Sie in der Konfigurationsoberfläche ein, dort legen Sie auch die Tokens an. Wie Sie gängige Clients wie Claude Desktop, Cursor oder Windsurf einrichten, beschreibt MCP im Integratoren-Handbuch. Diese Seite beschreibt den Endpunkt selbst.

Endpunkt

Adresse	http://<controller-ip>/mcp
Transport	Streamable HTTP: POST für JSON-RPC, Antworten als text/event-stream, GET für den Benachrichtigungskanal, DELETE beendet die Sitzung
Anmeldung	Header Authorization: Bearer <token>
Sitzung	Header Mcp-Session-Id aus der Antwort auf initialize
Erreichbar	nur im lokalen Netz

Die Antwortcodes helfen bei der Fehlersuche:

Code	Bedeutung
404	Der MCP-Skill ist ausgeschaltet.
401	Token fehlt (Missing or invalid Authorization header) oder ist unbekannt bzw. gesperrt (Invalid token).
511	Die Anfrage kam über den Fernzugriff. MCP ist nur im lokalen Netz erreichbar.
400	Anfrage ohne gültige Sitzung, die kein initialize ist.

Rechte

Ein Token ist an keinen nomos Benutzer gebunden. Wer es besitzt, arbeitet mit Administratorrechten; Raum- und Szenenrechte gelten nicht. Einige Bereiche bietet der Server bewusst nicht an: Benutzer lassen sich nur lesen, und Wiederherstellen einer Sicherung, Zurücksetzen auf Werkseinstellungen, Portweiterleitungen und Fernzugriff bleiben der Konfigurationsoberfläche vorbehalten.

Behandeln Sie Tokens deshalb wie Kennwörter: ein eigenes Token je Client, nicht mehr benötigte Tokens löschen. Per API verwalten Administratoren sie mit addMCPToken, getMCPTokens, setMCPToken und removeMCPToken.

Was der Server anbietet

• Tools für Komponenten, Szenen, Räume, Bereiche, Automationen, Skills und Systemfunktionen. Lesende Tools tragen den Hinweis readOnlyHint.
• Ressourcen wie nomos://components/all, nomos://scenes/all oder nomos://rooms/all.
• Prompts für häufige Aufgaben, etwa einen Statusbericht oder eine geführte Szenenerstellung.
• Anweisungen in der Antwort auf initialize, die dem Modell das Datenmodell erklären.

Die aktuelle Liste liefert der Server selbst über tools/list, resources/list und prompts/list. Ändert sie sich, meldet er das den verbundenen Clients.

Mit curl ausprobieren

So sieht der Ablauf ohne MCP-Client aus. Antworten kommen als Server-Sent Events, also als Zeilen event: message und data: {…}.

TOKEN='<token>'
curl -si http://<controller-ip>/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

HTTP/1.1 200 OK
content-type: text/event-stream
mcp-session-id: 6f0c…

event: message
data: {"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true},"resources":{"listChanged":true},"completions":{},"prompts":{"listChanged":true}},"serverInfo":{"name":"nomos-mcp",…

Mit der Sitzungs-ID aus dem Header geht es weiter: erst die Bestätigung, dann ein Tool-Aufruf, am Ende die Sitzung schließen.

SESSION='<mcp-session-id>'
H=(-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json'
   -H 'Accept: application/json, text/event-stream'
   -H "Mcp-Session-Id: $SESSION" -H 'MCP-Protocol-Version: 2025-06-18')

curl -s http://<controller-ip>/mcp "${H[@]}" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -s http://<controller-ip>/mcp "${H[@]}" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"component_get_by_id","arguments":{"cid":"C5"}}}'
curl -s -X DELETE http://<controller-ip>/mcp "${H[@]}"

event: message
data: {"result":{"content":[{"type":"text","text":"{\n  \"name\": \"Switch\",\n  \"cid\": \"C5\",…

Clients einrichten

Claude Code spricht Streamable HTTP selbst und verbindet sich direkt:

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

nomos MCP Bridge: Wer mehrere Controller ansprechen will, nimmt die nomos MCP Bridge. Sie läuft als lokaler stdio-Server (Node.js ab Version 18), leitet Tools, Ressourcen und Prompts des gewählten Controllers durch und wechselt auf Zuruf zwischen den Controllern.

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

Die Controller trägt die Bridge in ~/.config/nomos-mcp/controllers.json ein, mit Adresse (http://<controller-ip>/mcp) und Token. Die Tokens stehen dort im Klartext; schützen Sie die Datei entsprechend. Zum Eintragen öffnet die Bridge eine Einrichtungsseite auf http://localhost:18900 (ist der Port belegt, auf dem nächsten freien), die nur vom eigenen Rechner aus erreichbar ist.

Für Claude Desktop, Cursor, Windsurf und andere Clients steht die passende Konfiguration im Integratoren-Handbuch.

HTTP oder HTTPS

Der Endpunkt ist auch über https://<controller-ip>/mcp erreichbar. Das Zertifikat des Controllers ist jedoch selbstsigniert und nennt die Adresse des Controllers nicht. Clients auf Basis von Node.js, darunter die Bridge, lehnen es deshalb ab. Die README der Bridge schlägt dafür NODE_TLS_REJECT_UNAUTHORIZED=0 vor; damit prüft der ganze Prozess gar kein Zertifikat mehr, auch nicht bei anderen Servern. Wir empfehlen das nicht.

Im lokalen Netz verwenden Sie deshalb http://. Das Token geht dabei unverschlüsselt über das Netz; nutzen Sie MCP nur in einem Netz, dem Sie vertrauen. Wie Sie dem Zertifikat in eigenen Programmen gezielt vertrauen, steht unter HTTPS und Zertifikat.