Ably MCP Server

Ably

Ably is a real-time data streaming platform for building live applications. It provides pub/sub messaging, presence tracking, push notifications to mobile/web devices, and usage analytics.

Data Model & Hierarchy

• Channel — A named message stream. Channels are created implicitly when first published to or subscribed on. Channel names are case-sensitive strings (e.g. 'chat:room-1', 'events:user-updates'). Namespace prefixes separated by ':' enable rule-based configuration.
• Message — A unit of data published to a channel. Has a name (event type), data (payload), timestamp, unique id, and optional clientId. Messages are ephemeral by default — persistence depends on channel rules.
• Presence — Tracks which clients are currently connected to a channel. Each presence member has a clientId, connectionId, and optional data payload. Presence history records enter/leave/update events over time.
• Push Device Registration — A mobile or web device registered to receive push notifications. Has id, platform (ios/android/browser), formFactor, push.recipient (transport-specific token), clientId, and metadata.
• Push Channel Subscription — Links a registered device (or all devices for a clientId) to a channel for push notification delivery. When a message is published to the channel, subscribed devices receive a push notification.
• Stats — Aggregated usage metrics across the application: messages published/received, connections, channels, API requests, push notifications, and data transferred. Available at minute/hour/day/month granularity.
• Token — A short-lived credential issued from an API key. Tokens can be scoped to specific channels and operations, and optionally bound to a client ID. Used for client-side authentication where exposing the root API key is not acceptable.

Entity Relationships

App ─┬─ Channels (many, named streams) │ ├─ Messages (per channel, time-ordered) │ └─ Presence members (per channel, live set + history) ├─ Push Device Registrations (per app) │ └─ Push Channel Subscriptions (device → channel) └─ Stats (aggregated usage over time)

Key Workflows

1. Channel discovery: List active channels → get metadata for a specific channel (occupancy, status).
2. Messaging: Publish messages to a channel → retrieve message history with time-range filtering.
3. Presence monitoring: Get current members on a channel → query presence history for enter/leave events.
4. Push notification setup: Register a device → subscribe it to channels → send direct push or publish to channel.
5. Push management: List subscriptions → unsubscribe devices → unregister devices.
6. Usage monitoring: Get stats by minute/hour/day/month → analyze message volume, connections, API usage.
7. Token management: Request scoped tokens for client-side apps — limit capabilities, set TTL, bind to client IDs.

Gotchas

• Channel names are IDs: The channel name string IS the identifier used everywhere — messages, presence, subscriptions, metadata lookups. There is no separate numeric ID.
• Namespace prefixes: Channel names use ':' as namespace separators (e.g. 'chat:room-1'). Namespace rules in the dashboard control persistence, encryption, and push behavior per prefix.
• Message persistence: Messages are NOT persisted by default. Only channels with persistence enabled (via channel rules) retain message history. Querying history on non-persisted channels returns empty.
• Presence vs push: Presence tracks who is currently connected via WebSocket/SSE. Push notifications go to registered mobile/web devices even when the user isn't connected. They serve different use cases.
• Push requires device registration: Before subscribing to push channels, the device must be registered via the device registrations endpoint with valid platform-specific transport details (APNs token, FCM token, or web push endpoint).
• Stats aggregation delay: Stats are aggregated asynchronously. Minute-level stats may have a few seconds of delay; hourly and daily stats update at interval boundaries.
• Time is in milliseconds: Both message timestamps and the server time endpoint return Unix epoch in milliseconds, not seconds.