PumpFuse Platform — MCP Integration Guide

Model Context Protocol (MCP) tools and resources available on every PumpFuse product.
These cover device identity, runtime status, relay control, configuration, power monitoring, and telemetry.

For product-specific MCP tools, see the product's own MCP Guide (e.g., Watchdog MCP Guide).

Transport

MCP uses Streamable HTTP transport over a single endpoint:

POST http://<device-ip>/api/v1/mcp
Content-Type: application/json

All requests are JSON-RPC 2.0. No authentication required.

OAuth Compatibility

MCP clients that require OAuth discovery will find stub responses at the standard well-known URIs. These all return "auth_mode": "none":

Both are also mirrored at path-relative variants for clients that prepend the MCP endpoint path:

• /.well-known/oauth-authorization-server/api/v1/mcp
• /api/v1/mcp/.well-known/oauth-authorization-server
• /.well-known/oauth-protected-resource/api/v1/mcp
• /api/v1/mcp/.well-known/oauth-protected-resource

Built-in JSON-RPC Methods

Tools

At a Glance

get_device_info

Returns device identity information.

Input: None

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_device_info"
  }
}

Response content

{
  "product": "pf-watchdog",
  "firmware": "1.0.0",
  "mac": "AA:BB:CC:DD:EE:FF",
  "ip": "192.168.40.114",
  "uptime": 3600
}

get_status

Returns full runtime snapshot.

Input: None

Response content

{
  "product": "pf-watchdog",
  "firmware": "1.0.0",
  "uptime": 3600,
  "ip": "192.168.40.114",
  "wifi_connected": true,
  "mqtt_connected": true,
  "relay": true,
  "power_w_last": 12.345,
  "power_sample_ts_ms": 1739260200000,
  "telemetry_active": true,
  "telemetry_interval_s": 5
}

get_power_reading

Returns the latest power measurement.

Input: None

Response content

{
  "power_w": 12.345,
  "ts_ms": 1739260200000
}

get_relay

Returns current relay state.

Input: None

Response content

{
  "relay": true
}

set_relay

Set the relay state.

Input schema

{
  "type": "object",
  "properties": {
    "relay": {
      "type": "boolean",
      "description": "true = closed/ON, false = open/OFF"
    }
  },
  "required": ["relay"]
}

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_relay",
    "arguments": {
      "relay": false
    }
  }
}

Response content

{
  "relay": false
}

Side effects: Physically toggles the relay. Updates runtime state reflected in status, MQTT, etc.

get_config

Returns current device configuration.

Input: None

Response content

{
  "device_name": "test-board",
  "wifi_ssid": "MyNetwork",
  "mqtt_broker": "192.168.40.164",
  "mqtt_port": 1883,
  "mqtt_topic": "pumpfuse/test-board",
  "mqtt_user": "mqtt",
  "mqtt_pass": "secret123"
}

set_config

Update device configuration. All fields optional — include only what you want to change.

Input schema

{
  "type": "object",
  "properties": {
    "device_name": { "type": "string", "description": "Device display name" },
    "mqtt_broker": { "type": "string", "description": "MQTT broker host" },
    "mqtt_port": { "type": "integer", "description": "MQTT broker port", "minimum": 1, "maximum": 65535 },
    "mqtt_topic": { "type": "string", "description": "MQTT base topic" },
    "mqtt_user": { "type": "string", "description": "MQTT username" },
    "mqtt_pass": { "type": "string", "description": "MQTT password" }
  }
}

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_config",
    "arguments": {
      "device_name": "living-room",
      "mqtt_broker": "10.0.0.5"
    }
  }
}

Response content: Updated config JSON (same schema as get_config).

Validation rules:

• device_name: non-empty, max 32 characters
• mqtt_broker: non-empty, max 128 characters
• mqtt_port: integer, 1–65535
• mqtt_topic: non-empty, max 128 characters
• mqtt_user: max 64 characters (empty string allowed)
• mqtt_pass: max 64 characters (empty string allowed)
• If any MQTT field changes, broker and topic must be non-empty (either already set or provided in this call)

Error: Returns invalid_params with "invalid config payload" if validation fails.

Side effects: NVS persisted. If MQTT save fails after device_name update, device_name is rolled back.

get_telemetry

Returns current telemetry settings.

Input: None

Response content

{
  "active": true,
  "interval_s": 5
}

set_telemetry

Update telemetry settings. Both fields optional.

Input schema

{
  "type": "object",
  "properties": {
    "active": { "type": "boolean", "description": "Enable or disable telemetry" },
    "interval_s": { "type": "integer", "description": "Telemetry interval in seconds", "minimum": 1, "maximum": 60 }
  }
}

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_telemetry",
    "arguments": {
      "active": true,
      "interval_s": 10
    }
  }
}

Response content: Updated telemetry JSON.

Errors:

Resources

MCP resources provide read-only snapshots via the resources/read method.

Example: Read a resource

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "pumpfuse://test-board/status"
  }
}

Example AI Prompts

These prompts work with any MCP-compatible AI client connected to a PumpFuse device:

Notes

MCP server metadata

The MCP server identifies as:

• Server name: PumpFuse MCP
• Server version: 0.1.0

Product tools

Product-specific tools are registered alongside platform tools. tools/list returns both platform and product tools. There is no namespace separation — tool names are globally unique. Product tools follow the convention get_<feature>, set_<feature>, <action> (e.g., get_watchdog_config, trigger_reboot).