MCP for AI assistants

The HAM MCP (Model Context Protocol) server connects an AI assistant to your devices. The assistant can see the device list, the current readings and the history. Each call runs with your account and your permissions on each device.

Connection details

Item	Value
Address	`https://api.hamsystems.eu/mcp/index.php`
Transport	HTTP, JSON-RPC 2.0
Protocol version	`2024-11-05`
Authentication	Header `Authorization: Bearer-API YOUR_API_KEY`

You create the API key on the Account page. See the REST API.

Set up the assistant

Create an API key.

Add the server to the MCP configuration of your assistant. For Claude Code, the file is .mcp.json:

{
  "mcpServers": {
    "ham": {
      "type": "http",
      "url": "https://api.hamsystems.eu/mcp/index.php",
      "headers": {
        "Authorization": "Bearer-API YOUR_API_KEY"
      }
    }
  }
}

Restart the assistant.
Ask, for example, “Show me my devices”. The assistant calls the list_devices tool.

Tools

Tool	Parameters	Result
`list_devices`	`compact` (default `true`)	Your devices. With `compact: true`: `serialno`, `name`, `icon`, `groups`, `floorplans` and `count`. With `compact: false`: all details, with the settings.
`get_device_state`	`serialno` (one number or a list)	The current state. The same format as `get_device_state.php`. See the REST API.
`get_device_history`	`serialno`, `level`, `bin`	The history rows. The same levels and bins as in download historical data.
`get_definitions`	`family_id` (optional), `include_readings` (default `true`)	The family definitions: readings, outputs, settings
`get_docs`	none	Instructions for the tools
`send_command`	`serialno`, `command`	Sends a command to a device or a group. The assistant gets the commands from `get_docs`.

A typical call order: list_devices, then get_definitions for the family, then get_device_state or get_device_history.

Test with curl

curl -X POST https://api.hamsystems.eu/mcp/index.php \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}'

The result is in result.content[0].text, as JSON text:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"devices\":[{\"serialno\":\"e11:123\",\"name\":\"Fridge 1\",\"icon\":\"\",\"groups\":[],\"floorplans\":[]}],\"count\":1}" }
    ]
  }
}

Supported methods: initialize, notifications/initialized, tools/list, tools/call.

Errors

Code	Meaning
`-32000`	Authentication error (HTTP 401) or tool error
`-32700`	The body is not valid JSON
`-32600`	Invalid JSON-RPC request
`-32601`	Unknown method
`-32602`	The tool name is missing
`-32603`	Internal error