# 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://<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:

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

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

```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:

```json
{
  "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:

```json
{
  "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:

```bash
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