MCP para asistentes de IA

El servidor MCP (Model Context Protocol) de HAM conecta un asistente de IA a sus dispositivos. El asistente puede ver la lista de dispositivos, las lecturas actuales y el historial. Cada llamada se ejecuta con su cuenta y sus permisos en cada dispositivo.

Datos de conexión

Elemento	Valor
Dirección	https://api.hamsystems.eu/mcp/index.php
Transporte	HTTP, JSON-RPC 2.0
Versión del protocolo	2024-11-05
Autenticación	Encabezado Authorization: Bearer-API YOUR_API_KEY

Usted crea la clave API en la página Cuenta. Consulte la API REST.

Configurar el asistente

1. Cree una clave API.

2. Añada el servidor a la configuración MCP de su asistente. Para Claude Code, el archivo es .mcp.json:

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

3. Reinicie el asistente.

4. Pregunte, por ejemplo, “Muéstrame mis dispositivos”. El asistente llama a la herramienta list_devices.

Precaución

El asistente tiene el mismo acceso que usted. Puede controlar salidas en los dispositivos donde usted tiene permiso de escritura. No comparta el archivo de configuración, porque contiene su clave.

Herramientas

Herramienta	Parámetros	Resultado
list_devices	compact (predeterminado true)	Sus dispositivos. Con compact: true: serialno, name, icon, groups, floorplans y count. Con compact: false: todos los detalles, con los ajustes.
get_device_state	serialno (un número o una lista)	El estado actual. El mismo formato que get_device_state.php. Consulte la API REST.
get_device_history	serialno, level, bin	Las filas del historial. Los mismos niveles y bins que en descargar datos históricos.
get_definitions	family_id (opcional), include_readings (predeterminado true)	Las definiciones de familia: lecturas, salidas, ajustes
get_docs	ninguno	Instrucciones para las herramientas
send_command	serialno, command	Envía un comando a un dispositivo o a un grupo. El asistente obtiene los comandos de get_docs.

Un orden de llamadas típico: list_devices, después get_definitions para la familia, después get_device_state o get_device_history.

Prueba con 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":{}}}'

El resultado está en result.content[0].text, como texto JSON:

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

Métodos compatibles: initialize, notifications/initialized, tools/list, tools/call.

Errores

Código	Significado
-32000	Error de autenticación (HTTP 401) o error de la herramienta
-32700	El cuerpo no es JSON válido
-32600	Solicitud JSON-RPC no válida
-32601	Método desconocido
-32602	Falta el nombre de la herramienta
-32603	Error interno

Véase también

• API REST
• Seguridad