MCP pour les assistants IA

Le serveur MCP (Model Context Protocol) de HAM connecte un assistant IA à vos appareils. L’assistant peut voir la liste des appareils, les mesures actuelles et l’historique. Chaque appel s’exécute avec votre compte et vos permissions sur chaque appareil.

Détails de connexion

Élément	Valeur
Adresse	https://api.hamsystems.eu/mcp/index.php
Transport	HTTP, JSON-RPC 2.0
Version du protocole	2024-11-05
Authentification	En-tête Authorization: Bearer-API YOUR_API_KEY

Vous créez la clé API sur la page Compte. Voir l’API REST.

Configurer l’assistant

1. Créez une clé API.

2. Ajoutez le serveur à la configuration MCP de votre assistant. Pour Claude Code, le fichier est .mcp.json :

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

3. Redémarrez l’assistant.

4. Demandez, par exemple, « Montre-moi mes appareils ». L’assistant appelle l’outil list_devices.

Attention

L’assistant a le même accès que vous. Il peut commander les sorties des appareils où vous avez la permission d’écriture. Ne partagez pas le fichier de configuration, parce qu’il contient votre clé.

Outils

Outil	Paramètres	Résultat
list_devices	compact (par défaut true)	Vos appareils. Avec compact: true : serialno, name, icon, groups, floorplans et count. Avec compact: false : tous les détails, avec les paramètres.
get_device_state	serialno (un numéro ou une liste)	L’état actuel. Le même format que get_device_state.php. Voir l’API REST.
get_device_history	serialno, level, bin	Les lignes de l’historique. Les mêmes niveaux et bins que dans télécharger les données historiques.
get_definitions	family_id (facultatif), include_readings (par défaut true)	Les définitions de famille : mesures, sorties, paramètres
get_docs	aucun	Les instructions pour les outils
send_command	serialno, command	Envoie une commande à un appareil ou à un groupe. L’assistant obtient les commandes avec get_docs.

Un ordre d’appel typique : list_devices, puis get_definitions pour la famille, puis get_device_state ou get_device_history.

Tester avec 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":{}}}'

Le résultat est dans result.content[0].text, sous forme de texte JSON :

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

Méthodes prises en charge : initialize, notifications/initialized, tools/list, tools/call.

Erreurs

Code	Signification
-32000	Erreur d’authentification (HTTP 401) ou erreur d’outil
-32700	Le corps n’est pas du JSON valide
-32600	Requête JSON-RPC invalide
-32601	Méthode inconnue
-32602	Le nom de l’outil est absent
-32603	Erreur interne

Voir aussi

• API REST
• Sécurité