MCP

What is the nomos MCP Skill?

The nomos MCP Skill allows AI assistants like Claude to communicate directly with the nomos system Controller. Using the standardized Model Context Protocol (MCP), the AI can control devices, execute scenes, manage rooms, create automations, and much more – all through natural language.

Prerequisites

• An MCP-compatible client (e.g. Claude Desktop, Claude Code, Cursor, Windsurf)

• Node.js (version 18 or higher) installed on your machine

• Network access to the nomos system Controller (local only, no external access possible)

Setup

Step 1: Enable the MCP Module in nomos

The MCP module must be enabled in the nomos configuration interface. Navigate to Skills and make sure the MCP module is turned on.

Step 2: Create a Token

In the nomos configuration interface, navigate to the MCP section and create a new token. This token is used to authenticate the AI client with the nomos system Controller. Take note of the token – you will need it for the client configuration.

• Each token can be given a custom name (e.g. "Claude Desktop Office")

• Tokens can be disabled or deleted at any time

• Multiple tokens can be created for different clients

Step 3: Configure the Client

There are two ways to connect your MCP client to the nomos system Controller:

• Option A: nomos MCP Bridge (recommended) – a dedicated proxy that manages controller connections via a setup page. Simplest setup, supports multiple controllers, works with all MCP clients.

• Option B: Direct Connection – configure the controller URL and token directly in the client configuration. Requires manual token handling.

---

Option A: nomos MCP Bridge (Recommended)

The nomos MCP Bridge is a lightweight local proxy that manages connections to one or more nomos system controllers. Instead of configuring URLs and tokens directly, you register controllers via a web-based setup page. The bridge works with any MCP client that supports stdio-based servers.

Claude Desktop

Open the Claude Desktop settings and navigate to the "MCP Servers" section. Add a new server with the following configuration:

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

Claude Code (CLI)

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

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

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

Windsurf

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

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

Other MCP-Compatible Clients

Any client supporting stdio-based MCP servers can use the bridge. The command is:

npx -y nomos-mcp-bridge

Managing Controllers

After configuring the bridge in your MCP client, you can manage your controllers using the following AI commands:

Command	Description
open_setup	Opens the web-based setup page in your browser where you can enter the controller name, URL and MCP token
add_controller	Adds a new controller directly via AI — provide the name, URL and token
list_controllers	Lists all registered controllers and shows which one is currently selected
select_controller	Connects to a registered controller by name
remove_controller	Removes a registered controller

---

Option B: Direct Connection

If you prefer to configure the controller URL and token directly without using the bridge, you can use the following configurations.

Claude Desktop

Claude Desktop does not natively support the Streamable HTTP transport protocol. The connection is established via the mcp-remote package, which acts as a bridge.

Open the Claude Desktop settings and navigate to the "MCP Servers" section. Add a new server with the following configuration:

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

Replace <nomos-ip> with the IP address or hostname of your nomos system Controller and <your-token> with the token created in Step 2.

Note: The --allow-http parameter is required because the nomos system Controller is accessible locally via HTTP (not HTTPS).

Claude Code (CLI)

Claude Code natively supports Streamable HTTP. Add the server via the command line:

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

Or configure it manually in ~/.claude/settings.json:

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

Cursor

Cursor natively supports Streamable HTTP. Navigate to Settings > MCP and add a new server:

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

If the connection cannot be established, you can alternatively use the mcp-remote variant as described for Claude Desktop.

Windsurf

Windsurf natively supports Streamable HTTP. Open the MCP configuration and add:

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

Other MCP-Compatible Clients

The nomos MCP server uses the Streamable HTTP transport protocol. Clients that natively support this standard can be configured directly:

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

• Authentication: Bearer token in the Authorization header

• Transport type: Streamable HTTP

For clients that only support stdio-based MCP servers (like Claude Desktop), mcp-remote can be used as a bridge:

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

Feature Overview

Resources

The AI has access to real-time data from your nomos system Controller:

• All components, scenes, rooms, floors, timers, and automations as overview lists

• Individual entities with detailed information (e.g. a specific device with all its properties)

• Live updates: Changes in the system are automatically reported to the AI

Built-in Prompts

Status & Overview

Prompt	Description
home_status	Comprehensive overview of the current state of the entire system — all rooms, components, and their values
room_status	Current status of all components in a specific room (room name or room ID as parameter)
system_health	Comprehensive health check of the system — connectivity, unreachable devices, cloud status, remote access, critical notifications

Domain-Specific Reports

Prompt	Description
climate_report	Summary of temperature, humidity, and climate control across all rooms
energy_report	Summary of energy consumption and power-related data from all components
security_status	Summary of all security-related sensors — door/window contacts, motion detectors, locks, alarms
notifications_summary	Summary of all current notifications, grouped by severity and type
automation_overview	Overview of all automations and timers — their status, triggers, and actions

Guided Creation Workflows

Prompt	Description
create_scene	Guided workflow to create a new scene based on a description of the desired state
create_automation	Guided workflow to create a new automation based on a description of the desired behavior
create_timer	Guided workflow to create a new timer-based automation

Examples

Controlling Devices

"Turn on the light in the living room."

"Dim the ceiling lamp in the bedroom to 50%."

"Set the heating in the bathroom to 22 degrees."

Querying Status

"Which windows are currently open?"

"Show me the status of all devices in the living room."

"What is the current temperature in the kitchen?"

Managing Scenes

"Create a scene called 'Movie Night' that dims the living room lights and closes the blinds."

"Execute the 'Good Morning' scene."

Creating Automations

"Create an automation that turns on the outdoor lights at sunset."

"Show me all active timers."

KNX Configuration

"Which KNX group addresses are available in the project?"

"Import the KNX project from the file."

Important Notes and Known Limitations

Local Access Only

The MCP endpoint is only accessible via the local network. Access from outside (e.g. via the internet) is blocked by the system. The MCP client must be on the same network as the nomos system Controller.

Claude Desktop: Restart on Connection Loss

Important: If the connection between Claude Desktop and the nomos MCP server is interrupted (e.g. due to a nomos system Controller restart or network issues), Claude Desktop must be fully restarted. Simply closing and reopening the chat window is not sufficient – the application must be completely quit and restarted in order to re-establish the MCP connection.

Token Security

• Treat MCP tokens like passwords

• Create separate tokens for different clients

• Disable or delete tokens that are no longer needed

• Tokens grant full access to all MCP functions – there is no fine-grained permission management

General MCP Notes

• Session management: Each client receives its own session. Multiple clients can be connected simultaneously.

• Automatic notifications: Changes in the system (e.g. device status) are automatically reported to all connected clients. There may be a short delay with many simultaneous changes (debouncing of 100ms).

• Error handling: If a tool returns an error, the AI will typically recognize this and display a helpful error message.

Usage Tips

• Be as specific as possible in your instructions (room names, device names)

• The AI can combine multiple actions in a single request

• Use the built-in prompts for common tasks

• For complex automations, it is recommended to build them step by step with the AI