MQTT Broker URL Format: mqtt://, mqtts://, ws:// and wss:// Explained

An MQTT broker URL tells a client which transport to use, which host to reach, which port to open and, for WebSockets, which path to request. By the end of this guide you will be able to read and write any MQTT URL, pick the right scheme and port for your environment, and avoid the handful of mistakes that cause most "cannot connect" reports.

Anatomy of an MQTT Broker URL

A full MQTT URL looks like this:

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

• Scheme selects the transport: raw TCP or WebSocket, plain or encrypted.
• Host is the broker's DNS name or IP address.
• Port is where the broker listens for that transport.
• Path only applies to WebSocket schemes; it is the HTTP path the WebSocket upgrade request goes to.

Credentials and client ID are usually not part of the URL. Some libraries accept mqtt://user:pass@host, but passing them as separate options is clearer and avoids leaking passwords into logs.

The Four Schemes

You may also see tcp:// and ssl:// in Java and Eclipse Paho clients; they are equivalent to mqtt:// and mqtts://. Some tools also accept tls:// for the encrypted TCP variant.

The ports 1883 and 8883 are registered with IANA for MQTT. WebSocket ports are not standardized, which is why you must always check the broker's documentation for them. Our MQTT ports guide covers the history in more detail.

Choosing the Right Scheme

• Devices and servers: use mqtts:// on 8883. It is the most efficient encrypted option.
• Browsers: they cannot open raw TCP sockets, so they must use wss://. Pages served over HTTPS will refuse ws:// as mixed content. See MQTT over WebSocket.
• Restrictive corporate networks: if outbound 8883 is blocked, wss:// sometimes gets through proxies that understand WebSockets.
• Local testing: mqtt:// on 1883 is fine on a lab network or against the public test broker, never for credentials over the internet.

The WebSocket Path Matters

The single most common WebSocket mistake is a missing or wrong path. Brokers serve MQTT over WebSocket on a specific HTTP path, and /mqtt is the most widespread convention. ConnectMQ uses /mqtt on both 8083 and 8084. If you connect to wss://broker.connectmq.com:8084 without the path, the upgrade request goes to / and fails, usually with an unhelpful close event.

MQTT Broker URL Examples by Client

Node.js and Browsers with MQTT.js

MQTT.js takes a URL plus an options object. This works in Node.js with mqtts:// and in browsers with 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 with paho-mqtt

Paho does not parse URLs; it takes host, port and transport separately. A small helper converts a URL into those parts.

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()

Command Line

Mosquitto's tools take host and port, not URLs, though newer versions also accept -L with a URL:

# Plain TCP against the public broker
mosquitto_sub -h broker.connectmq.com -p 1883 -i cli-sub-r4t9 -t 'connectmq/demo/r4t9/#' -v

# TLS with credentials, using the URL form
mosquitto_sub -L mqtts://YOUR_USERNAME:YOUR_PASSWORD@broker.connectmq.com:8883/devices/# \
  -i YOUR_CLIENT_ID --capath /etc/ssl/certs -v

With -L, the path segment after the port is the topic, not a WebSocket path.

Arduino and ESP32

Embedded libraries such as PubSubClient also take host and port separately. Whether the connection is encrypted depends on the network client, WiFiClient for 1883 or WiFiClientSecure for 8883, not on a URL scheme. The cloud MQTT broker ESP32 tutorial shows the full TLS setup.

Node-RED

In the mqtt-broker config node, set Server to broker.connectmq.com, Port to 1883 or 8883, and tick "Use TLS" for 8883. For WebSockets, enter the full URL wss://broker.connectmq.com:8084/mqtt in the Server field instead.

Troubleshooting Checklist

When a connection fails, check these in order:

1. Scheme and port agree. mqtts:// on 1883 or mqtt:// on 8883 will fail or hang.
2. WebSocket path is present. /mqtt on broker.connectmq.com.
3. Hostname, not IP, for TLS. The certificate is issued for the hostname; connecting by IP fails validation.
4. No ws:// from HTTPS pages. Browsers block it as mixed content.
5. Firewall allows the port. Corporate networks often block 1883 and 8883 outbound.
6. Client ID is non-empty and unique. Duplicates cause disconnect loops.
7. Credentials are separate from the URL unless the library documents URL credentials, and special characters are URL-encoded if they are.
8. The client's CA store trusts the server certificate. broker.connectmq.com uses a Let's Encrypt certificate, which standard system stores trust.

Storing the Broker URL in Configuration

Hard-coding a URL in source is the fastest way to make environment changes painful. Keep the full URL, plus credentials and client ID, in configuration so the same code can point at the public test area during development, a private broker in staging and a dedicated endpoint in production.

A simple environment-variable layout works for most services:

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"

Then read them at startup, for example mqtt.connect(process.env.MQTT_URL, { clientId: process.env.MQTT_CLIENT_ID, username: process.env.MQTT_USERNAME, password: process.env.MQTT_PASSWORD }) in Node.js, or the client_from_url helper above in Python. A few habits make this robust:

• Validate on startup. Reject an unknown scheme or a WebSocket URL without a path before attempting to connect, and log the scheme, host and port (never the password) so misconfiguration is obvious.
• Keep secrets separate from the URL. Store the password in your secret manager and the URL in ordinary configuration; that way the URL can safely appear in logs and dashboards.
• Use one variable per environment, not per transport. If a browser build needs wss:// while a backend uses mqtts://, give each deployable its own setting rather than deriving one from the other with string replacement.
• Document the expected format. A one-line comment such as scheme://host:port[/path] next to the setting saves the next developer from guessing.

Public vs Private URLs

The hostname is the same for the public test area and for private brokers, which keeps examples simple. On the public MQTT test broker you connect anonymously with any unique client ID and a unique topic prefix such as connectmq/demo/r4t9/...; everything there is world-readable. A private ConnectMQ broker uses the same URL with your generated username, password and client ID, and your traffic stays in your own isolated tenant. For the bigger picture on hosting choices, see the cloud MQTT broker guide and our overview of what an MQTT broker does.

Get Your Own Broker URL on ConnectMQ

Create a free Serverless broker at app.connectmq.com with no credit card. The portal shows your endpoints for all four schemes along with generated credentials, and its in-browser client lets you test a wss:// connection immediately. ConnectMQ supports MQTT 3.1.1 and 5.0 on every endpoint.

Frequently Asked Questions

What is the difference between mqtt:// and mqtts://?

mqtt:// is plain TCP, usually on port 1883. mqtts:// wraps the same protocol in TLS, usually on port 8883, encrypting credentials and payloads.

Why does my wss:// connection fail without an error message?

The most common cause is a missing WebSocket path. Add /mqtt to the URL, and confirm the port is the secure WebSocket port, 8084 on ConnectMQ.

Can I put the username and password in the MQTT URL?

Some libraries support scheme://user:pass@host:port, but separate options are safer and avoid leaking secrets in logs.

Is tcp:// the same as mqtt://?

Yes. Java and Paho clients use tcp:// and ssl://, which correspond to mqtt:// and mqtts://.