MCP voor AI-assistenten

De HAM MCP-server (Model Context Protocol) verbindt een AI-assistent met uw apparaten. De assistent kan de apparatenlijst, de huidige metingen en de geschiedenis zien. Elke aanroep draait met uw account en uw rechten op elk apparaat.

Verbindingsgegevens

Item	Waarde
Adres	https://api.hamsystems.eu/mcp/index.php
Transport	HTTP, JSON-RPC 2.0
Protocolversie	2024-11-05
Authenticatie	Header Authorization: Bearer-API YOUR_API_KEY

U maakt de API-sleutel op de pagina Account. Zie de REST API.

De assistent instellen

1. Maak een API-sleutel.

2. Voeg de server toe aan de MCP-configuratie van uw assistent. Voor Claude Code is het bestand .mcp.json:

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

3. Start de assistent opnieuw.

4. Vraag bijvoorbeeld “Toon mijn apparaten”. De assistent roept de tool list_devices aan.

Opgepast

De assistent heeft dezelfde toegang als u. Hij kan uitgangen bedienen op de apparaten waarop u schrijfrechten hebt. Deel het configuratiebestand niet, want het bevat uw sleutel.

Tools

Tool	Parameters	Resultaat
list_devices	compact (standaard true)	Uw apparaten. Met compact: true: serialno, name, icon, groups, floorplans en count. Met compact: false: alle details, met de instellingen.
get_device_state	serialno (één nummer of een lijst)	De huidige status. Dezelfde indeling als get_device_state.php. Zie de REST API.
get_device_history	serialno, level, bin	De geschiedenisrijen. Dezelfde niveaus en bins als bij historische gegevens downloaden.
get_definitions	family_id (optioneel), include_readings (standaard true)	De familiedefinities: metingen, uitgangen, instellingen
get_docs	geen	Instructies voor de tools
send_command	serialno, command	Stuurt een opdracht naar een apparaat of een groep. De assistent haalt de opdrachten uit get_docs.

Een typische aanroepvolgorde: list_devices, daarna get_definitions voor de familie, daarna get_device_state of get_device_history.

Testen met 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":{}}}'

Het resultaat staat in result.content[0].text, als JSON-tekst:

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

Ondersteunde methoden: initialize, notifications/initialized, tools/list, tools/call.

Fouten

Code	Betekenis
-32000	Authenticatiefout (HTTP 401) of toolfout
-32700	De body is geen geldige JSON
-32600	Ongeldig JSON-RPC-verzoek
-32601	Onbekende methode
-32602	De toolnaam ontbreekt
-32603	Interne fout

Zie ook

• REST API
• Beveiliging