Formato de la URL de un broker MQTT: mqtt://, mqtts://, ws:// y wss:// explicados

La URL de un broker MQTT indica a un cliente qué transporte usar, a qué host llegar, qué puerto abrir y, en el caso de WebSocket, qué ruta solicitar. Al terminar esta guía sabrás leer y escribir cualquier URL MQTT, elegir el esquema y el puerto adecuados para tu entorno y evitar el puñado de errores que provocan la mayoría de los "no puedo conectarme".

Anatomía de la URL de un broker MQTT

Una URL MQTT completa tiene este aspecto:

wss://broker.connectmq.com:8084/mqtt
\_/   \__________________/ \__/\___/
 |            |              |    |
scheme       host           port path

• Esquema: selecciona el transporte, TCP crudo o WebSocket, sin cifrar o cifrado.
• Host: es el nombre DNS o la dirección IP del broker.
• Puerto: es donde el broker escucha para ese transporte.
• Ruta: solo se aplica a los esquemas WebSocket; es la ruta HTTP a la que va la petición de upgrade de WebSocket.

Las credenciales y el client ID normalmente no forman parte de la URL. Algunas bibliotecas aceptan mqtt://user:pass@host, pero pasarlos como opciones separadas es más claro y evita que las contraseñas acaben en los logs.

Los cuatro esquemas

También puedes ver tcp:// y ssl:// en clientes Java y Eclipse Paho; equivalen a mqtt:// y mqtts://. Algunas herramientas aceptan además tls:// para la variante TCP cifrada.

Los puertos 1883 y 8883 están registrados en la IANA para MQTT. Los puertos WebSocket no están estandarizados, por eso siempre debes consultarlos en la documentación del broker. Nuestra guía de puertos MQTT cubre la historia con más detalle.

Elegir el esquema adecuado

• Dispositivos y servidores: usa mqtts:// en el 8883. Es la opción cifrada más eficiente.
• Navegadores: no pueden abrir sockets TCP crudos, así que deben usar wss://. Las páginas servidas por HTTPS rechazarán ws:// como contenido mixto. Consulta MQTT sobre WebSocket.
• Redes corporativas restrictivas: si el 8883 saliente está bloqueado, wss:// a veces atraviesa proxies que entienden WebSocket.
• Pruebas locales: mqtt:// en el 1883 sirve en una red de laboratorio o con el servidor MQTT público gratuito, nunca para enviar credenciales por internet.

La ruta de WebSocket importa

El error de WebSocket más común con diferencia es una ruta ausente o incorrecta. Los brokers sirven MQTT sobre WebSocket en una ruta HTTP concreta, y /mqtt es la convención más extendida. ConnectMQ usa /mqtt tanto en el 8083 como en el 8084. Si te conectas a wss://broker.connectmq.com:8084 sin la ruta, la petición de upgrade va a / y falla, normalmente con un evento de cierre poco útil.

Ejemplos de URL de broker MQTT por cliente

Node.js y navegadores con MQTT.js

MQTT.js recibe una URL más un objeto de opciones. Esto funciona en Node.js con mqtts:// y en navegadores con wss://.

import mqtt from "mqtt";

const isBrowser = typeof window !== "undefined";
const url = isBrowser
  ? "wss://broker.connectmq.com:8084/mqtt"
  : "mqtts://broker.connectmq.com:8883";

const client = mqtt.connect(url, {
  clientId: "YOUR_CLIENT_ID",
  username: "YOUR_USERNAME",
  password: "YOUR_PASSWORD",
  protocolVersion: 5,
  keepalive: 60,
  reconnectPeriod: 2000,
});

client.on("connect", () => {
  console.log("Connected to", url);
  client.subscribe("demo/#", { qos: 1 });
  client.publish("demo/hello", "hi from MQTT.js", { qos: 1 });
});

client.on("message", (topic, payload) => {
  console.log(topic, payload.toString());
});

client.on("error", (err) => console.error("MQTT error:", err.message));

Python con paho-mqtt

Paho no analiza URLs; recibe host, puerto y transporte por separado. Un pequeño helper convierte una URL en esas partes.

import ssl
from urllib.parse import urlparse

import paho.mqtt.client as mqtt

DEFAULT_PORTS = {"mqtt": 1883, "mqtts": 8883, "ws": 8083, "wss": 8084}


def client_from_url(url: str, client_id: str, username=None, password=None):
    u = urlparse(url)
    scheme = u.scheme.lower()
    transport = "websockets" if scheme in ("ws", "wss") else "tcp"
    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=client_id,
                         transport=transport, protocol=mqtt.MQTTv5)
    if transport == "websockets":
        client.ws_set_options(path=u.path or "/mqtt")
    if scheme in ("mqtts", "wss"):
        client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
    if username:
        client.username_pw_set(username, password)
    port = u.port or DEFAULT_PORTS[scheme]
    return client, u.hostname, port


def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)


client, host, port = client_from_url(
    "wss://broker.connectmq.com:8084/mqtt",
    client_id="YOUR_CLIENT_ID",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.on_connect = on_connect
client.connect(host, port, keepalive=60)
client.loop_forever()

Línea de comandos

Las herramientas de Mosquitto reciben host y puerto, no URLs, aunque las versiones más recientes también aceptan -L con una URL:

# TCP sin cifrar contra el broker público
mosquitto_sub -h broker.connectmq.com -p 1883 -i cli-sub-r4t9 -t 'connectmq/demo/r4t9/#' -v

# TLS con credenciales, usando la forma de URL
mosquitto_sub -L mqtts://YOUR_USERNAME:YOUR_PASSWORD@broker.connectmq.com:8883/devices/# \
  -i YOUR_CLIENT_ID --capath /etc/ssl/certs -v

Con -L, el segmento de ruta después del puerto es el topic, no una ruta de WebSocket.

Arduino y ESP32

Las bibliotecas embebidas como PubSubClient también reciben host y puerto por separado. Que la conexión esté cifrada depende del cliente de red, WiFiClient para el 1883 o WiFiClientSecure para el 8883, no de un esquema de URL. El tutorial de ESP32 y broker MQTT en la nube muestra la configuración TLS completa.

Node-RED

En el nodo de configuración mqtt-broker, pon en Server broker.connectmq.com, en Port 1883 u 8883 y marca "Use TLS" para el 8883. Para WebSocket, introduce en su lugar la URL completa wss://broker.connectmq.com:8084/mqtt en el campo Server.

Checklist de solución de problemas

Cuando falle una conexión, comprueba esto en orden:

1. El esquema y el puerto coinciden. mqtts:// en el 1883 o mqtt:// en el 8883 fallarán o se quedarán colgados.
2. La ruta de WebSocket está presente. /mqtt en broker.connectmq.com.
3. Nombre de host, no IP, para TLS. El certificado se emite para el nombre de host; conectarse por IP hace fallar la validación.
4. Nada de ws:// desde páginas HTTPS. Los navegadores lo bloquean como contenido mixto.
5. El firewall permite el puerto. Las redes corporativas suelen bloquear el 1883 y el 8883 salientes.
6. El client ID no está vacío y es único. Los duplicados provocan bucles de desconexión.
7. Las credenciales van separadas de la URL, salvo que la biblioteca documente credenciales en la URL, y en ese caso los caracteres especiales van codificados para URL.
8. El almacén de CA del cliente confía en el certificado del servidor. broker.connectmq.com usa un certificado de Let's Encrypt, en el que confían los almacenes estándar del sistema.

Guardar la URL del broker en la configuración

Codificar a mano una URL en el código fuente es la forma más rápida de hacer dolorosos los cambios de entorno. Guarda la URL completa, junto con las credenciales y el client ID, en la configuración, para que el mismo código pueda apuntar al área pública de pruebas durante el desarrollo, a un broker privado en staging y a un endpoint dedicado en producción.

Una distribución sencilla con variables de entorno funciona para la mayoría de los servicios:

export MQTT_URL="mqtts://broker.connectmq.com:8883"
export MQTT_USERNAME="YOUR_USERNAME"
export MQTT_PASSWORD="YOUR_PASSWORD"
export MQTT_CLIENT_ID="YOUR_CLIENT_ID"

Después léelas al arrancar, por ejemplo con mqtt.connect(process.env.MQTT_URL, { clientId: process.env.MQTT_CLIENT_ID, username: process.env.MQTT_USERNAME, password: process.env.MQTT_PASSWORD }) en Node.js, o con el helper client_from_url anterior en Python. Algunos hábitos lo hacen robusto:

• Valida al arrancar. Rechaza un esquema desconocido o una URL de WebSocket sin ruta antes de intentar conectar, y registra el esquema, el host y el puerto (nunca la contraseña) para que una mala configuración sea evidente.
• Mantén los secretos separados de la URL. Guarda la contraseña en tu gestor de secretos y la URL en la configuración normal; así la URL puede aparecer sin riesgo en logs y paneles.
• Usa una variable por entorno, no por transporte. Si una build para navegador necesita wss:// mientras un backend usa mqtts://, da a cada desplegable su propio ajuste en lugar de derivar uno del otro con reemplazos de texto.
• Documenta el formato esperado. Un comentario de una línea como scheme://host:port[/path] junto al ajuste evita que el siguiente desarrollador tenga que adivinar.

URL públicas frente a privadas

El nombre de host es el mismo para el área pública de pruebas y para los brokers privados, lo que simplifica los ejemplos. En el servidor MQTT público gratuito, pensado para pruebas y no para datos de producción, te conectas de forma anónima con cualquier client ID único y un prefijo de topic único como connectmq/demo/r4t9/...; todo lo que hay allí puede leerlo cualquiera. Un broker MQTT gestionado privado de ConnectMQ usa la misma URL con tu usuario, contraseña y client ID generados, y tu tráfico permanece en tu propio espacio aislado. Para una visión más amplia de las opciones de hosting, consulta la guía de broker MQTT en la nube y nuestra introducción a qué hace un broker MQTT.

Consigue tu propia URL de broker en ConnectMQ

Crea un broker Serverless gratuito en app.connectmq.com sin tarjeta de crédito. El portal muestra tus endpoints para los cuatro esquemas junto con las credenciales generadas, y su cliente del navegador te permite probar una conexión wss:// de inmediato. ConnectMQ admite MQTT 3.1.1 y 5.0 en todos los endpoints.

Preguntas frecuentes

¿Qué diferencia hay entre mqtt:// y mqtts://?

mqtt:// es TCP sin cifrar, normalmente en el puerto 1883. mqtts:// envuelve el mismo protocolo en TLS, normalmente en el puerto 8883, y cifra credenciales y payloads.

¿Por qué mi conexión wss:// falla sin ningún mensaje de error?

La causa más habitual es que falta la ruta de WebSocket. Añade /mqtt a la URL y confirma que el puerto es el de WebSocket seguro, el 8084 en ConnectMQ.

¿Puedo poner el usuario y la contraseña en la URL MQTT?

Algunas bibliotecas admiten scheme://user:pass@host:port, pero las opciones separadas son más seguras y evitan filtrar secretos en los logs.

¿tcp:// es lo mismo que mqtt://?

Sí. Los clientes Java y Paho usan tcp:// y ssl://, que corresponden a mqtt:// y mqtts://.