MQTT.Agent v0.1 Specification

Status: Draft 0.1. Feedback wanted, breaking changes possible during the v0.x window. License: This specification is licensed under CC-BY-4.0. Reference implementations: @cloudsignal/agent (A2A), @cloudsignal/mcp-over-mqtt (MCP).

Abstract

MQTT.Agent is an open protocol bundle for agent-to-agent and agent-to-tool messaging on MQTT 5. It is a sibling-spec to Anthropic's Model Context Protocol (MCP) and Google's Agent2Agent (A2A): same problem domain, different transport. The protocol is derived from implementations of these patterns; this document defines the wire behavior so that any conforming implementation can interoperate with any other.

Conformance keywords

The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

Sections

The normative protocol is split across three pages:

• Substrate: common ground - MQTT version, identity claims, topic conventions, QoS expectations, sessions and presence.
• A2A over MQTT: agent-to-agent messaging - agent cards, presence, delegation modes, request/response correlation.
• MCP over MQTT: Model Context Protocol over MQTT 5 - tool servers as network services, replicas, discovery, streaming partials.

The remaining sections (versioning and compatibility, security considerations, reserved registries, acknowledgments, normative and informative references, and feedback) appear below.

Versioning and compatibility

This specification follows semantic versioning at the major.minor level:

• Major version increments (e.g., 1.x to 2.x) MAY include breaking changes to wire formats, topic shapes, or required claims.
• Minor version increments within the same major (e.g., 1.0 to 1.1) MUST be backward-compatible additions: new optional fields, new topic patterns under reserved segments, new error types, new card fields.
• Patch version increments are reserved for editorial corrections to this document; they MUST NOT change normative behavior.

During the v0.x window (this draft), breaking changes between minor releases are permitted. Production users should pin to an exact specification version in their agent and tool cards. Once v1.0 ships, ordinary semver compatibility applies.

Implementations declare conformance to a specific version via the mqtt_agent_version field on their card; see Substrate, common card fields for the field definition and the v0.x fallback rule.

Reserved segments (see Substrate, topic conventions) and reserved claim names (see Substrate, identity claims) form the long-lived compatibility surface. Adding a new top-level segment is a minor change; redefining an existing one is a major change.

Security considerations

This section is non-normative. The wire protocol defined above does not mandate any specific authentication or authorization model. Those are broker concerns and vary across deployments. Listing them as normative would prevent conforming implementation on Mosquitto, EMQX, HiveMQ, NanoMQ, AWS IoT Core, and other MQTT 5 brokers with different policy engines.

That said, the topic shapes in A2A and MCP are deliberately structured to make claim-based, identity-bound authorization easy when a broker supports it. A broker that matches connecting client claims (see Substrate, identity claims) against topic segments at PUBLISH/SUBSCRIBE time can enforce, for example:

• An agent with agent_id=agent-a may PUBLISH only to {ns}/agents/agent-a/card, {ns}/agents/agent-a/status, {ns}/tasks/+/inbox (delegations), and {ns}/tasks/+/result / {ns}/tasks/+/results (responses). Other agents' cards and statuses are off-limits, so no impersonation.
• A tool server with tool_id=tool-1 may PUBLISH only to {ns}/mcp/tools/tool-1/card and to client response topics. Other tools' card namespaces are off-limits, so no card squatting.
• An agent's allowed callable tools can be expressed as PUBLISH rules on {ns}/mcp/tools/{tool}/call keyed by agent_id. Revocation is a policy update, not a code change.

Operators are encouraged to deploy MQTT.Agent on a broker that supports such policies; the wire protocol works without them, but a meaningful chunk of its security story depends on them.

A separate companion document, Identity-Bound ACL: A Recommended Profile for MQTT.Agent Brokers, is forthcoming (planned for v0.2). It will be non-normative and citable, so broker vendors who implement the profile can claim conformance independently of this specification.

Other security considerations worth flagging, none of which this specification mandates:

• Transport security. Brokers should require TLS for production deployments. The MQTT specification supports TLS via mqtts:// and wss:// schemes.
• Token lifecycle. Credentials carrying the claims in Substrate, identity claims should be short-lived and refreshable. The protocol is agnostic to the token service; implementations are free to choose their refresh mechanism.

Two additional concerns are addressed normatively elsewhere in the specification rather than as advisory items here:

• Idempotency under QoS 1 redelivery is required by Substrate Section 1.4 QoS conventions.
• Card content trust (cards are advisory, capabilities verified via broker ACL) is required by Substrate Section 1.7 Cards.

Reserved registries

This specification reserves the following names and namespaces. Additions and changes follow the versioning policy: adding a new entry is a minor-version change; redefining an existing entry is a major-version change.

The constraints on use are defined on the Substrate page; this section is the authoritative summary of what is reserved.

Reserved claim names

Reserved second-level topic segments

Interpreted relative to the namespace prefix:

Acknowledgments

This specification builds on prior art from:

• Anthropic's Model Context Protocol, the source of MCP semantics, tool/resource concepts, and JSON Schema conventions reused in MCP over MQTT.
• Google's Agent2Agent, concepts and naming around agent-to-agent messaging, agent cards, and capability advertising in A2A over MQTT.
• OASIS MQTT 5.0, the underlying messaging protocol whose features (retained messages, will, response topic, correlation data, shared subscriptions) carry the protocol on the wire.

Sibling work that addresses adjacent problems on MQTT, cited respectfully:

• EMQX MQTT for AI / MQTT.AI, a broader framing of MQTT for AI workloads. MQTT.Agent is narrower and more specific to agent-to-agent and agent-to-tool comms.

Normative references

The references in this section are required to implement this specification.

[MQTT5] OASIS, "MQTT Version 5.0", March 2019. https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. https://www.rfc-editor.org/info/rfc2119

[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017. https://www.rfc-editor.org/info/rfc8174

Informative references

The references in this section provide background and context but are not required to implement this specification.

[MCP] Anthropic, "Model Context Protocol". https://modelcontextprotocol.io

[A2A] Linux Foundation, "Agent2Agent". https://a2aproject.github.io

Feedback

A public spec repository with issue tracker and an RFC process is being prepared. Until it lands, issues, questions, and proposed changes go to efi@cloudsignal.io. Substantive changes to normative sections will be discussed in writing before being merged.