Install Mosquitto on the server (apt install mosquitto on Debian/Ubuntu or equivalent); stop the default service before editing the configuration
Generate a CA key and self-signed certificate, then generate a server key and certificate signing request (CSR) and sign it with the CA; place the three files (ca.crt, server.crt, server.key) in a directory readable by the mosquitto user
Edit mosquitto.conf to add a TLS listener: set listener 8883, cafile, certfile, keyfile, and require_certificate true (for mutual TLS) or false (for server-only TLS); set allow_anonymous false and configure a password file
Restart Mosquitto and test with mosquitto_pub and mosquitto_sub using --cafile ca.crt (and --cert / --key for mutual TLS); verify that connecting without certificates is rejected
For production, replace self-signed certificates with certificates from a trusted CA or Let's Encrypt; configure certificate auto-renewal and a systemd timer to send SIGHUP to Mosquitto after renewal
Enable persistence (persistence true, persistence_location /var/lib/mosquitto/) and configure logging to a file for audit trails; set max_keepalive and restrict retained message size if memory is limited
Known gotchas
The server certificate's CN or Subject Alternative Name must match the hostname clients use to connect; a mismatch causes TLS verification failure even though the CA is trusted
require_certificate true enforces mutual TLS and rejects clients without a valid certificate; if some clients cannot present certificates, use two separate listeners on different ports with different require_certificate settings
Mosquitto does not hot-reload ACL file changes; a reload signal (SIGHUP) or full restart is required — plan maintenance windows or use a dynamic auth plugin for large deployments
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp