MCP Tools Reference

mcmqtt provides a comprehensive set of MCP (Model Context Protocol) tools for MQTT operations, broker management, and agent coordination. This reference documents all available tools with their parameters and usage examples.

Connection Management

mqtt_connect

Establish connection to an MQTT broker.

Parameters:

Parameter	Type	Required	Default	Description
`host`	string	Yes	-	Broker hostname or IP address
`port`	integer	No	1883	Broker port number
`client_id`	string	No	auto-generated	Unique client identifier
`username`	string	No	-	Authentication username
`password`	string	No	-	Authentication password
`keepalive`	integer	No	60	Keep-alive interval in seconds
`clean_session`	boolean	No	true	Start with clean session
`tls`	object	No	-	TLS configuration

Example:

mqtt_connect({
  "host": "mqtt.example.com",
  "port": 8883,
  "client_id": "my-client",
  "username": "user123",
  "password": "secret",
  "keepalive": 30,
  "tls": {
    "ca_cert": "/path/to/ca.pem",
    "cert_file": "/path/to/client.pem",
    "key_file": "/path/to/client.key",
    "verify_hostname": true
  }
})

mqtt_disconnect

Disconnect from the current MQTT broker.

Parameters:

Parameter	Type	Required	Default	Description
`reason_code`	integer	No	0	Disconnect reason code
`reason_string`	string	No	-	Human-readable disconnect reason

Example:

mqtt_disconnect({
  "reason_code": 0,
  "reason_string": "Normal disconnect"
})

mqtt_get_status

Get current connection status and statistics.

Parameters: None

Example:

mqtt_get_status()

# Returns:
{
  "connected": true,
  "broker": "mqtt.example.com:1883",
  "client_id": "my-client",
  "uptime": "01:23:45",
  "messages_sent": 1247,
  "messages_received": 3891,
  "subscriptions": [
    {"topic": "sensors/+/temp", "qos": 1},
    {"topic": "alerts/#", "qos": 2}
  ],
  "last_activity": "2024-01-15T10:30:00Z"
}

Messaging Operations

mqtt_publish

Publish a message to an MQTT topic.

Parameters:

Parameter	Type	Required	Default	Description
`topic`	string	Yes	-	Target topic for the message
`payload`	any	Yes	-	Message payload (string, object, or binary)
`qos`	integer	No	0	Quality of Service level (0, 1, or 2)
`retain`	boolean	No	false	Whether to retain the message
`properties`	object	No	-	MQTT 5.0 properties

Example:

# Simple text message
mqtt_publish({
  "topic": "devices/sensor1/temperature",
  "payload": "23.5",
  "qos": 1,
  "retain": true
})

# JSON payload
mqtt_publish({
  "topic": "events/user-action",
  "payload": {
    "user_id": "user123",
    "action": "login",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "qos": 2
})

# With MQTT 5.0 properties
mqtt_publish({
  "topic": "data/stream",
  "payload": {"value": 42},
  "qos": 1,
  "properties": {
    "message_expiry_interval": 300,
    "content_type": "application/json",
    "user_properties": [
      {"key": "source", "value": "sensor-network"},
      {"key": "priority", "value": "high"}
    ]
  }
})

mqtt_subscribe

Subscribe to one or more MQTT topics.

Parameters:

Parameter	Type	Required	Default	Description
`topic`	string	Yes	-	Topic pattern to subscribe to
`qos`	integer	No	0	Quality of Service level
`no_local`	boolean	No	false	Don’t receive own messages (MQTT 5.0)
`retain_as_published`	boolean	No	false	Keep original retain flag
`retain_handling`	integer	No	0	Retain handling option (0, 1, or 2)

Example:

# Simple subscription
mqtt_subscribe({
  "topic": "sensors/temperature",
  "qos": 1
})

# Wildcard subscriptions
mqtt_subscribe({
  "topic": "devices/+/status",  # + matches one level
  "qos": 2
})

mqtt_subscribe({
  "topic": "events/#",  # # matches multiple levels
  "qos": 0
})

# MQTT 5.0 options
mqtt_subscribe({
  "topic": "commands/device123",
  "qos": 1,
  "no_local": true,
  "retain_handling": 1
})

mqtt_unsubscribe

Unsubscribe from MQTT topics.

Parameters:

Parameter	Type	Required	Default	Description
`topic`	string or array	Yes	-	Topic(s) to unsubscribe from

Example:

# Unsubscribe from single topic
mqtt_unsubscribe({
  "topic": "sensors/temperature"
})

# Unsubscribe from multiple topics
mqtt_unsubscribe({
  "topic": ["sensors/+/temp", "alerts/#", "commands/device123"]
})

Broker Management

spawn_mqtt_broker

Create and start a new MQTT broker instance.

Parameters:

Parameter	Type	Required	Default	Description
`port`	integer	No	1883	Port for the broker to listen on
`host`	string	No	”localhost”	Host interface to bind to
`config`	object	No	{}	Broker configuration options
`persistence`	boolean	No	false	Enable message persistence
`auth`	object	No	-	Authentication configuration

Example:

# Basic broker
spawn_mqtt_broker({
  "port": 1884,
  "config": {
    "allow_anonymous": true,
    "max_connections": 100
  }
})

# Advanced configuration
spawn_mqtt_broker({
  "port": 8883,
  "host": "0.0.0.0",
  "config": {
    "allow_anonymous": false,
    "max_connections": 1000,
    "max_inflight_messages": 20,
    "message_size_limit": "1MB",
    "keepalive_timeout": 60,
    "session_expiry_interval": 3600
  },
  "persistence": true,
  "auth": {
    "username_password": {
      "admin": "secure_password",
      "client1": "client_password"
    },
    "acl": [
      {"username": "admin", "topic": "#", "access": "readwrite"},
      {"username": "client1", "topic": "devices/+", "access": "read"}
    ]
  }
})

list_mqtt_brokers

List all managed MQTT broker instances.

Parameters: None

Example:

list_mqtt_brokers()

# Returns:
[
  {
    "id": "broker_001",
    "host": "localhost",
    "port": 1883,
    "status": "running",
    "uptime": "2h 34m 18s",
    "connections": 23,
    "messages_per_second": 145,
    "memory_usage": "45MB"
  },
  {
    "id": "broker_002",
    "host": "0.0.0.0",
    "port": 8883,
    "status": "running",
    "uptime": "5d 12h 7m",
    "connections": 387,
    "messages_per_second": 2847,
    "memory_usage": "234MB"
  }
]

stop_mqtt_broker

Stop a managed MQTT broker instance.

Parameters:

Parameter	Type	Required	Default	Description
`broker_id`	string	Yes	-	ID of the broker to stop
`graceful`	boolean	No	true	Whether to stop gracefully
`timeout`	integer	No	30	Timeout for graceful shutdown

Example:

stop_mqtt_broker({
  "broker_id": "broker_001",
  "graceful": true,
  "timeout": 10
})

Agent Coordination

swarm_deploy

Deploy a swarm of coordinated agents.

Parameters:

Parameter	Type	Required	Default	Description
`name`	string	Yes	-	Unique swarm identifier
`agent_type`	string	Yes	-	Type of agents to deploy
`count`	integer	Yes	-	Number of agents in the swarm
`config`	object	No	{}	Agent configuration
`resources`	object	No	{}	Resource limits per agent
`coordination`	object	No	{}	Coordination settings

Example:

swarm_deploy({
  "name": "browser-test-swarm",
  "agent_type": "browser-test",
  "count": 10,
  "config": {
    "target": "https://my-app.com",
    "browser": "chrome",
    "headless": true,
    "scenarios": ["login", "purchase", "search"]
  },
  "resources": {
    "memory": "512MB",
    "cpu": "0.5",
    "disk": "1GB"
  },
  "coordination": {
    "pattern": "worker-pool",
    "load_balancing": "round-robin",
    "health_check_interval": 30
  }
})

swarm_status

Get status information for a deployed swarm.

Parameters:

Parameter	Type	Required	Default	Description
`swarm_name`	string	Yes	-	Name of the swarm to check

Example:

swarm_status({
  "swarm_name": "browser-test-swarm"
})

# Returns:
{
  "name": "browser-test-swarm",
  "status": "running",
  "agents": {
    "total": 10,
    "healthy": 9,
    "unhealthy": 1,
    "starting": 0
  },
  "tasks": {
    "completed": 1247,
    "in_progress": 15,
    "failed": 23,
    "queued": 8
  },
  "performance": {
    "average_response_time": "245ms",
    "success_rate": "98.2%",
    "throughput": "42 tasks/min"
  },
  "resources": {
    "memory_usage": "4.2GB/5.0GB",
    "cpu_usage": "67%",
    "network_io": "15MB/s"
  }
}

swarm_scale

Scale a swarm up or down.

Parameters:

Parameter	Type	Required	Default	Description
`swarm_name`	string	Yes	-	Name of the swarm to scale
`count`	integer	Yes	-	New agent count
`strategy`	string	No	”gradual”	Scaling strategy (“gradual” or “immediate”)

Example:

# Scale up gradually
swarm_scale({
  "swarm_name": "browser-test-swarm",
  "count": 15,
  "strategy": "gradual"
})

# Scale down immediately
swarm_scale({
  "swarm_name": "api-test-swarm",
  "count": 5,
  "strategy": "immediate"
})

swarm_stop

Stop and remove a swarm.

Parameters:

Parameter	Type	Required	Default	Description
`swarm_name`	string	Yes	-	Name of the swarm to stop
`graceful`	boolean	No	true	Whether to stop gracefully
`timeout`	integer	No	60	Timeout for graceful shutdown

Example:

swarm_stop({
  "swarm_name": "browser-test-swarm",
  "graceful": true,
  "timeout": 30
})

Monitoring and Diagnostics

mqtt_monitor_topics

Monitor activity on specific topics.

Parameters:

Parameter	Type	Required	Default	Description
`topics`	array	Yes	-	Topics to monitor
`duration`	integer	No	60	Monitoring duration in seconds
`sample_rate`	number	No	1.0	Sampling rate (0.0 - 1.0)

Example:

mqtt_monitor_topics({
  "topics": ["sensors/+/temp", "alerts/#"],
  "duration": 300,
  "sample_rate": 0.1  # Monitor 10% of messages
})

mqtt_get_metrics

Get detailed MQTT performance metrics.

Parameters:

Parameter	Type	Required	Default	Description
`time_range`	string	No	”1h”	Time range for metrics
`granularity`	string	No	”1m”	Data point granularity

Example:

mqtt_get_metrics({
  "time_range": "24h",
  "granularity": "1h"
})

# Returns detailed performance metrics
{
  "time_range": "24h",
  "metrics": {
    "messages_per_second": [...],
    "connection_count": [...],
    "latency_p95": [...],
    "error_rate": [...]
  }
}

Error Handling

All MCP tools return standardized error responses:

# Error response format
{
  "error": {
    "code": "MQTT_CONNECTION_FAILED",
    "message": "Failed to connect to broker at mqtt.example.com:1883",
    "details": {
      "host": "mqtt.example.com",
      "port": 1883,
      "reason": "Connection refused"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Common error codes:

MQTT_CONNECTION_FAILED - Broker connection issues
MQTT_AUTHENTICATION_FAILED - Invalid credentials
MQTT_SUBSCRIPTION_FAILED - Topic subscription issues
MQTT_PUBLISH_FAILED - Message publishing issues
BROKER_SPAWN_FAILED - Broker creation issues
SWARM_DEPLOYMENT_FAILED - Agent swarm deployment issues
INVALID_PARAMETERS - Invalid tool parameters

This reference covers all mcmqtt MCP tools. For more examples and advanced usage patterns, see the How-to Guides and Tutorials.