1. Substrate

This section defines the common ground that both the A2A profile and the MCP profile build on: the MQTT version assumed, the identity model, topic conventions, QoS expectations, and how presence is established and torn down.

1.1 MQTT version

Implementations MUST support MQTT 5.0. MQTT 5 features used normatively in this specification are:

• User Properties on PUBLISH packets (A2A, request/response correlation, MCP, MQTT 5 properties on calls and responses)
• Response Topic and Correlation Data on PUBLISH packets (A2A, request/response correlation, MCP, MQTT 5 properties on calls and responses)
• Content Type on PUBLISH packets (A2A, agent cards and discovery, MCP, discovery)
• Will Properties, in particular Will Delay Interval (see Session and presence below, A2A, presence)
• Session Expiry Interval (see Session and presence below)
• Shared Subscriptions (MCP, replicas and load balancing)

Implementations MAY also operate over MQTT 3.1.1 in degraded modes, for example by carrying correlation identifiers inside the JSON payload when the broker does not advertise MQTT 5. Such degraded modes are out of scope for v0.1 conformance; an implementation that claims conformance MUST do so against MQTT 5.

1.2 Identity claims

Connecting clients MUST authenticate to the broker. The transport for credentials is broker-specific, typically a JWT carried in the MQTT CONNECT username/password fields, but this specification does not constrain the credential format. What matters at the protocol layer is that each connected client is associated with a stable set of named claims.

The following claim names are RESERVED by this specification:

Implementations MAY define additional claims for application-specific use; the names listed above MUST NOT be redefined to mean something different. Brokers that wish to enforce identity binding (see Security considerations on the spec landing page) are expected to match these claim values against topic segments at PUBLISH/SUBSCRIBE time, but the binding mechanism itself is out of scope.

1.3 Topic conventions

All topics defined in this specification live underneath a configurable namespace prefix. The default namespace is the literal string a2a/v1. Deployments MAY use an application-specific namespace (for example, myapp, factory/floor-3) to scope agents on a shared broker. The namespace MUST be a valid MQTT topic prefix and MUST NOT contain the wildcards + or #.

Identifier segments (those carrying an agent_id, tool_id, or server_id value) SHOULD match the regular expression [a-z0-9][a-z0-9-]{0,63}. Implementations MUST reject identifiers containing /, +, or #, since these collide with MQTT topic syntax. Identifiers SHOULD be lowercase ASCII; implementations MAY accept mixed case but MUST treat identifiers case-sensitively when matching.

Reserved second-level segments (interpreted relative to the namespace prefix):

Implementations MAY introduce additional second-level segments for application-specific traffic (logs, telemetry, etc.); the segments listed above MUST NOT be repurposed.

Throughout this document, placeholder syntax {name} denotes a topic segment that is replaced at runtime with a concrete identifier; for example, {ns}/agents/{agent_id}/card with ns=myapp and agent_id=agent-a resolves to myapp/agents/agent-a/card. Placeholder substitution is performed by the publisher and the subscriber independently. The broker sees fully resolved topic strings.

1.4 QoS conventions

Unless a specific section states otherwise:

• Notifications that drive state transitions (task delivery, tool calls, tool responses) MUST use QoS 1.
• Retained presence and discovery messages (agent cards, tool cards, server cards) MUST be published with QoS 1 and the RETAIN flag set.
• Streaming partials (MCP, streaming partials) MAY use QoS 0 for low-latency best-effort delivery.
• Implementations MAY use QoS 2 for messages that require exactly-once semantics, but no message defined in this specification REQUIRES QoS 2.

Because QoS 1 permits redelivery, handlers for A2A task notifications and MCP tool calls SHOULD be idempotent at the application layer. Implementations SHOULD use the task_id (defined in A2A, request/response correlation) or call_id (defined in MCP, MQTT 5 properties on calls and responses) as the idempotency key, checking the persisted task or call status before re-executing.

1.5 Session and presence

Clients participating in this specification SHOULD connect with Clean Start set to 0 (i.e., persistent sessions) and a non-zero Session Expiry Interval. This allows in-flight QoS 1 messages to survive brief disconnects.

Clients that publish a retained presence document (an agent card in A2A, agent cards and discovery or a server/tool card in MCP, discovery) MUST register an MQTT 5 Will that re-publishes a corresponding "offline" document to the same topic on unclean disconnect, with the RETAIN flag set so the offline state persists for new subscribers. Will Delay Interval MAY be used to suppress brief network blips: a delay of 5 to 30 seconds is RECOMMENDED. On graceful shutdown, clients MUST publish the offline document themselves before disconnecting and SHOULD then disconnect normally so the broker discards the will.

Discussion (non-normative): The combination of (retained presence + will) gives the broker a deterministic record of who is currently reachable; subscribers reading the retained topic see either the current online document or the most recent offline document, never a stale online document after a crash.

1.6 Wildcards and discovery

Several discovery operations defined later in this document depend on subscribing with the single-level wildcard + (for example, {ns}/agents/+/card). Brokers that enforce identity-bound ACL (see Security considerations on the spec landing page) sometimes silently filter wildcard subscriptions: the SUBACK is granted but no retained messages are delivered. Implementations SHOULD detect this case and report a clear warning to the caller; SHOULD NOT silently return an empty result without that warning. An implementation that cannot use wildcards MUST still support exact-topic lookups (for example, {ns}/agents/{agent_id}/card for a known peer name).

1.7 Cards

Both A2A and MCP define retained presence documents called cards - agent cards in A2A, tool and server cards in MCP. The schema for each card type is defined on its respective profile page; this section defines the fields and trust model that all card types share.

Common card fields

Every card published under this specification SHOULD include the following field at the top level:

Cards that omit mqtt_agent_version MUST be treated as conforming to version "0.1" for the duration of the v0.x window. Once v1.0 ships, cards without this field MUST be treated as non-conforming and ignored.

Profile-specific card schemas defined on A2A and MCP MAY add further fields; the mqtt_agent_version field is reserved by this specification and MUST NOT be redefined.

Card content trust

Cards are written by their owner. A connected agent publishes its own card; a tool server publishes its own card. The broker does not validate card contents; consumers MUST NOT assume that fields advertised on a card are accurate or authorized.

Consumers SHOULD treat card contents as advisory and verify capability claims through the broker's authorization policy at PUBLISH or SUBSCRIBE time, not by reading the card. Specifically, an agent MUST NOT be granted the ability to call a tool solely because the tool's card advertises that capability - the broker's ACL is the authoritative source of what each connection may do.