MACP Transport Guide

Status: Non-normative (explanatory). In case of conflict, the referenced RFC is authoritative. Reference: RFC-MACP-0006 | registries/transports.md | core.proto

MACP supports multiple transport layers depending on deployment architecture.

gRPC (Recommended)

Best for:

• high throughput coordination
• persistent streaming sessions
• microservice environments

Advantages:

• efficient binary transport
• streaming support
• strong typing via protobuf

The gRPC binding defines three categories of RPCs:

Send (Unary)

The authoritative per-message request/ack surface. Use SendResponse.ack for standard acceptance or rejection signaling.

StreamSession (Bidirectional)

An optional interactive envelope stream, advertised by sessions.stream = true. The stream carries canonical MACP Envelopes only — implementations MUST NOT invent ad-hoc pseudo-envelopes for acks or errors. Once bound to a session_id, all subsequent session-scoped envelopes on that stream MUST use the same session_id.

StreamSession is not a replacement for unary Send acknowledgements. Clients that need per-message negative acknowledgements SHOULD use Send. Session-scoped Signal envelopes are invalid as an attach mechanism. For zero-mutation observation of an existing session, use the passive session subscription form defined in RFC-MACP-0006 §3.2: send a StreamSessionRequest with only subscribe_session_id (and optional after_sequence) set, and the runtime replays accepted session history and then switches seamlessly to live broadcast on the same stream. A single request MUST NOT set both envelope and subscribe_session_id; the caller MUST be an authenticated declared participant or an observer identity admitted by deployment policy.

WatchModeRegistry / WatchRoots (Server Streaming)

Optional discovery hint streams. A runtime MUST advertise the corresponding capability (mode_registry.list_changed or roots.list_changed) before these can be assumed interoperable. After receiving a change notification, clients SHOULD re-query the full surface (ListModes or ListRoots). Minimal implementations may send an initial change hint immediately after stream establishment and then stay idle until a later change occurs. Note that ListModes returns only standards-track modes; extension mode discovery is implementation-defined.

WatchSignals (Server Streaming)

An optional server-streaming RPC that broadcasts Ambient Signal Envelopes to all subscribers. Signals are non-binding messages on the ambient plane — they carry empty session_id and empty mode in the Envelope. A SignalPayload MAY include a correlation_session_id to relate the signal to a session without making it session-scoped. Signals are ephemeral and are not available for replay. See RFC-MACP-0006 §3.4.

GetSession (Unary)

Returns a SessionMetadata snapshot for a given session, including the session's identity, state, timing, bound version fields, the current participant list, and per-participant activity summaries (ParticipantActivity with participant_id, last_message_at_unix_ms, message_count).

ListSessions / WatchSessions (Session Observation)

Programmatic session lifecycle observation. ListSessions returns SessionMetadata for all known sessions (advertised by sessions.list_sessions); WatchSessions is a server-streaming RPC emitting SessionLifecycleEvent notifications (CREATED, RESOLVED, EXPIRED) in real time (advertised by sessions.watch_sessions). Control-planes and UIs typically call ListSessions at startup for a snapshot, then subscribe to WatchSessions for incremental updates. Events are ephemeral and not replayed. See docs/lifecycle.md.

HTTP

Best for:

• simple integrations
• environments where gRPC is restricted

WebSockets

Best for:

• interactive coordination
• browser environments

Message Buses

Best for:

• large distributed systems
• asynchronous coordination
• event-driven architectures

Examples: Kafka, NATS, RabbitMQ

Transport Identifiers

Each transport binding has a registered identifier:

• macp.transport.grpc.v1
• macp.transport.http.v1
• macp.transport.websocket.v1
• macp.transport.messagebus.v1

These identifiers are used in agent manifest transport_endpoints to declare how an agent can be reached. See registries/transports.md.