Streaming events

Last updated Jun 14, 2026

Most Matter mutations return 202 Accepted with a pending resource; terminal outcomes arrive asynchronously. For agents, polling is wasteful — and webhooks require a publicly-reachable HTTP endpoint. The streaming bridge solves both: one call to matter_subscribe_to_events opens a live stream that surfaces events as MCP notifications while the agent does other work.

How it works

sequenceDiagram
  participant Agent
  participant MCP as Matter MCP server
  participant API as Matter API

  Agent->>MCP: matter_subscribe_to_events({entity_id: "ent_..."})
  MCP->>API: GET /v1/events/stream?entity_id=ent_...  (SSE)
  API-->>MCP: event: entity.state_changed
  MCP-->>Agent: MCP notification: { event: ..., data: ... }
  API-->>MCP: event: filing.accepted
  MCP-->>Agent: MCP notification: { event: ..., data: ... }
  Note over Agent,MCP: Agent continues other tool calls while stream is open

Under the hood, the MCP server opens a Server-Sent Events connection to the Matter API. Each event lands as a MCP server-initiated notification on the same Streamable HTTP connection the agent already has open. No separate subscribe channel.

Subscribe

matter_subscribe_to_events({
  "entity_id": "ent_Nq3KcAbc",
  "types": ["entity.state_changed", "filing.*"]
})

Optional parameters:

• entity_id — filter to a single subject resource.
• types — array of event type patterns (exact or prefix.*).

If omitted, the stream delivers every event the token is authorized to see.

Per-entity ordering guarantee

Every event carries a monotonic sequence scoped to its subject. When an agent filters on entity_id, events arrive in strict order. Cross-entity order is best-effort; if you need cross-entity causal order, subscribe to a broader stream and re-order by created. Agents can reason about state transitions without worrying about reordering.

Reconnection

The stream auto-resumes on disconnect. The MCP server tracks Last-Event-ID and replays undelivered events on reconnect. Agents see a continuous stream from their perspective.

Unsubscribe

The Streamable HTTP session carries the subscription for its lifetime; closing the MCP session ends the stream. Agent runtimes expose this as a "cancel subscription" action in their UI.

Example: watch a dissolution complete

matter_subscribe_to_events({
  "entity_id": "ent_Nq3KcAbc",
  "types": ["entity.state_changed", "filing.*"]
})

matter_dissolve_entity({ "entity_id": "ent_Nq3KcAbc", "reason": "strategic_wind_down" })

The agent then receives a sequence of notifications:

entity.state_changed     active → dissolving        sequence=7
filing.submitted         form_966                   sequence=8
filing.submitted         franchise_tax (final)      sequence=9
filing.accepted          form_966                   sequence=10
filing.accepted          franchise_tax (final)      sequence=11
entity.state_changed     dissolving → winding_down  sequence=12
filing.submitted         certificate_of_dissolution sequence=13
filing.accepted          certificate_of_dissolution sequence=14
entity.state_changed     winding_down → tax_cleared sequence=15
entity.state_changed     tax_cleared → dissolved    sequence=16
filing.submitted         boi_update                 sequence=17
filing.accepted          boi_update                 sequence=18

No polling loop. No webhook endpoint. The agent's job is just to react.