/docs/engineer/brokers-and-connections

MQTT Broker and Connection Setup

Author:: Mqttable
Updated:: Aug 24, 2026

On this page5 sections

Create a Broker Endpoint

Open Connections and select New Broker. Give the endpoint a recognizable name, choose its transport, then enter the Broker host and listener port.

Need a test endpoint? Choose one from the free public MQTT Broker list.

For mqtts, wss, or quic, use the TLS certificate guide to decide whether you need no upload, a CA certificate, or a CA plus client certificate and key.

mqtt:// — TCP · default port 1883

Connects directly to a Broker TCP listener.
Use Host 127.0.0.1 and Port 1883.

Mqttable New Broker form showing mqtt, 127.0.0.1:1883, and successful MQTT 3.1.1 and 5.0 tests — Use mqtt for a plain TCP listener. The green results show that this endpoint accepted test connections.
mqtt selects the TCP transport.
Host and Port identify the Broker listener.
Test Connection checks the endpoint with temporary clients.

mqtts:// — TCP + TLS · default port 8883

Connects MQTT directly over TLS.
Verify server identity checks the Broker certificate. System CA fits public certificates; choose Custom CA for a private CA.
Leave SNI on Auto and ALPN empty unless the Broker specifies values. Enable mTLS only when it requires a client certificate and key.

Mqttable New Broker form showing mqtts, port 8883, server verification, SNI, ALPN, CA trust, and mTLS — mqtts adds certificate verification and optional client authentication to a direct MQTT connection.
mqtts uses the TLS listener, commonly port 8883.
Set verification, CA trust, SNI, and ALPN for the server.
Enable mTLS only when the listener requests a client certificate.

ws:// — WebSocket · default port 8083

Connects MQTT after an HTTP WebSocket upgrade, without TLS.
Requires WebSocket Path. It starts with /; /mqtt is the common default.
Use the path configured by the Broker or reverse proxy. This transport has no TLS settings.

Mqttable New Broker form showing ws, port 8083, and WebSocket Path /mqtt — ws needs both the listener port and the HTTP upgrade path.
ws selects an unencrypted WebSocket listener.
The path is part of the WebSocket URL and must start with /.

wss:// — WebSocket + TLS · default port 8084

Uses a WebSocket Path like ws, then secures the connection with TLS.
Configure the Path, server certificate trust, SNI, and ALPN to match the listener or reverse proxy.
Enable mTLS only when the listener requires a client certificate and key.

Mqttable New Broker form showing wss, port 8084, WebSocket Path /mqtt, TLS verification, CA trust, and mTLS — wss combines the WebSocket path with TLS server verification and optional mTLS.
wss uses the secure WebSocket listener, commonly port 8084.
The WebSocket Path must match the listener or proxy route.
TLS settings apply after the WebSocket upgrade.

quic:// — QUIC · default UDP port 14567

Use this only when the Broker exposes an MQTT-over-QUIC listener.
Requires Host and UDP Port. It has no WebSocket Path.
Configure server verification, CA trust, SNI, ALPN, and optional mTLS to match that listener.

Mqttable New Broker form showing quic, UDP port 14567, TLS verification, CA trust, and mTLS — QUIC uses its own UDP listener and the same certificate controls as other secure transports.
quic uses the Broker QUIC listener and UDP port.
Server verification, CA trust, SNI, and ALPN must match the listener.
mTLS adds a client certificate when required.

Select Test Connection, then Create. A green Connection OK confirms the endpoint accepted the displayed MQTT versions; client authentication and session settings are checked after you create a Connection.

Create an MQTT Connection

After saving the Broker, select New Client.

Name / Client ID: Name is only a display label. Client ID is the identity seen by the Broker and must be unique among connected clients. Keep it stable when resuming a session.
MQTT version: Prefer 5.0 when the Broker supports it, use 3.1.1 for devices that require it, and reserve 3.1 for identified legacy systems.
Authentication: With MQTT 5.0, select the None, Password, JWT, or SCRAM method required by the listener. Follow the authentication guide for credentials, SecretRef, JWT claims, and SCRAM requirements.
Clean Start: Keep it on for a first test. Turning it off requests an existing session; it is not an automatic-retry switch.
Keep Alive: Uses PINGREQ/PINGRESP when idle to check the connection. The default is 300 seconds; 0 disables MQTT Keep Alive.
Session Expiry Interval: In MQTT 5, 0 discards the session after disconnect, a positive value retains it for that many seconds, and 4294967295 means no expiry. Keep 0 for a first test.

Mqttable New Client form showing Client ID, MQTT 5, Clean Start, Keep Alive, and Session Expiry — Begin with a unique Client ID, a supported MQTT version, Clean Start on, Keep Alive 300 seconds, and Session Expiry 0.
Name is local; Client ID is the identity the Broker sees.
MQTT version and authentication must match the listener policy.
Clean Start, Keep Alive, and Session Expiry define session behavior together.

Keep the remaining MQTT 5 options at their defaults unless the application requires them:

Receive Max / Topic Alias Max: Limit unacknowledged QoS 1/2 messages and accepted Topic aliases.
Maximum Packet Size: The largest MQTT packet the client accepts; a value that is too small rejects valid messages.
Request Problem Info / Request Response Info / User Properties: MQTT 5 response requests and application metadata.
Last Will: Configure it only when consumers already agree on the Will Topic, Payload, and QoS.

Connect and verify

Select Start, then check three places:

The client state is Connected, not Connecting or Retrying.
The Session column shows the expected summary, such as Clean and 300s.
Trace shows an outgoing CONNECT, followed by an incoming CONNACK with Connection Accepted.

Mqttable client showing Connected while Trace displays CONNECT and a successful CONNACK — Connected plus CONNECT/CONNACK proves that the current MQTT Session was established.
The state is Connected and the row includes the session summary.
The client sends CONNECT and the Broker returns CONNACK.
Connection Accepted confirms this MQTT connection attempt succeeded.

Connected does not prove Topic permission or message delivery. Use the first MQTT message tutorial to verify subscribe, publish, and Trace.

Quick troubleshooting

A saved Connection cannot connect or drops unexpectedly: Mqttable shows Retrying and retries automatically—after 10 seconds when a connection attempt fails, or after 5 seconds when an active connection drops. It keeps retrying until the client connects or you select Stop.
Test Connection fails: This is a one-off endpoint check and does not enter the automatic reconnect loop. Check Host, Port, DNS, firewall, and whether the listener is running.
TLS or WebSocket fails: Check the CA, server name, client certificate, and WebSocket Path.
CONNACK is rejected: Check the MQTT version, Client ID, and authentication material.
Connected but cannot publish or subscribe: Check the Topic ACL instead of changing the endpoint again.

Create a Broker Endpoint

Create an MQTT Connection

Connect and verify

Quick troubleshooting

Next steps