# 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: ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Claude Code (CLI)** ```bash claude mcp add nomos -- npx -y nomos-mcp-bridge ``` **Cursor** Add to your Cursor MCP settings (`.cursor/mcp.json`): ```json { "mcpServers": { "nomos": { "command": "npx", "args": ["-y", "nomos-mcp-bridge"] } } } ``` **Windsurf** Add to your Windsurf MCP config (`~/.codeium/windsurf/mcp_config.json`): ```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: ```json { "mcpServers": { "nomos": { "command": "npx", "args": [ "mcp-remote", "http:///mcp", "--allow-http", "--header", "Authorization: Bearer " ] } } } ``` Replace `` with the IP address or hostname of your nomos system Controller and `` 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: ```bash claude mcp add nomos \ --transport streamable-http \ "http:///mcp" \ --header "Authorization: Bearer " ``` Or configure it manually in `~/.claude/settings.json`: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Cursor** Cursor natively supports Streamable HTTP. Navigate to `Settings > MCP` and add a new server: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` 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: ```json { "mcpServers": { "nomos": { "type": "streamable-http", "url": "http:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` **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:///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: ```bash npx mcp-remote http:///mcp --allow-http --header "Authorization: Bearer " ``` ### 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.nomos-system.com/nomos-system/integrator-en/skills/mcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.