Real-time Events

Klaxon provides two real-time transports:

Transport	Endpoint	Audience	Protocol
SSE	GET /mcp/sse	MCP agents	Server-Sent Events (MCP spec)
WebSocket	GET /api/ws	Web/mobile clients	WebSocket (JSON messages)

Both are powered by Postgres LISTEN/NOTIFY on the klaxon_events channel, so events propagate across server replicas.

WebSocket (Clients)

Connect with a bearer token:

const ws = new WebSocket("ws://localhost:3000/api/ws");
ws.onmessage = msg => {
  const event = JSON.parse(msg.data);
  console.log(event.kind, event.id);
};

Event Kinds

Kind	Description
item.created	New item created
item.updated	Item fields changed
item.answered	Form response submitted
item.dismissed	Item dismissed
item.archived	Item archived
bulk.updated	Multiple items changed
item.viewed	Item marked as viewed

Event Payload

{
  "org_id": "...",
  "kind": "item.created",
  "id": "item-uuid"
}

Events are filtered by org_id — you only receive events for your organization.

SSE (MCP Agents)

Per the MCP spec, agents subscribe via SSE:

curl -N http://localhost:3000/mcp/sse \
  -H "Authorization: Bearer API_KEY"

Events are sent as event: notifications/klaxon with JSON data.

How It Works

1. A mutation (create, update, dismiss, etc.) calls pg_notify('klaxon_events', payload)
2. All server replicas receive the notification via their PgListener
3. SSE and WebSocket handlers filter by org_id and forward to connected clients