SSE Event Types in MCP-Cloud

MCP-Cloud uses a structured event system for Server-Sent Events (SSE) to provide real-time updates to clients. This document outlines the various event types used throughout the platform.

Event Structure

All SSE events in MCP-Cloud follow a consistent format:

event: EVENT_TYPE
data: {
  "timestamp": "2025-05-09T12:34:56.789Z",
  "source": "server/component",
  "serverId": "server-123",
  ...event-specific properties...
}

Each event includes:

• timestamp: ISO 8601 timestamp of when the event occurred
• source: Component or service that generated the event
• serverId: Unique identifier of the related MCP server (when applicable)
• Additional event-specific properties

Core Event Types

Deployment Events

Event Type	Description	Key Properties
deployment:started	Server deployment process initiated	userId, templateId, config
deployment:building	Server container is being built	progress, stage
deployment:provisioning	Cloud resources are being provisioned	resourceType, region
deployment:ready	Server is successfully deployed	url, connectionDetails
deployment:failed	Deployment process failed	error, stage, logs

Server Status Events

Event Type	Description	Key Properties
server:starting	Server is initializing	startTime
server:online	Server is online and ready	uptime, url, version
server:idle	Server has no active connections	idleSince, autoShutdownTime
server:busy	Server is processing requests	connectionCount, load
server:offline	Server is offline	reason, shutdownTime
server:error	Server encountered an error	errorCode, message, critical

Log Events

Event Type	Description	Key Properties
logs:app	Application-level log messages	level, message, context
logs:system	System-level log messages	level, message, component
logs:request	API request log	method, path, statusCode, responseTime
logs:error	Error log with details	stack, context, userId

Metrics Events

Event Type	Description	Key Properties
metrics:cpu	CPU utilization metrics	usage, cores, processes
metrics:memory	Memory utilization metrics	used, available, swapUsed
metrics:network	Network utilization metrics	bytesIn, bytesOut, connections
metrics:requests	Request metrics	count, avgResponseTime, errorRate
metrics:tokens	Token usage metrics	inputTokens, outputTokens, totalCost

Alert Events

Event Type	Description	Key Properties
alert:high_usage	Resource usage exceeds threshold	resource, threshold, currentValue
alert:slow_response	Response times are degraded	avgResponseTime, threshold
alert:error_rate	Error rate exceeds threshold	errorRate, threshold, period
alert:quota	Approaching or exceeding quota	quota, used, limit, projectedDepletion

User Session Events

Event Type	Description	Key Properties
user:connected	User connected to server	userId, connectionId, clientInfo
user:disconnected	User disconnected from server	userId, connectionId, duration

Custom Event Types

MCP servers can emit custom event types for application-specific needs. Custom events should follow the naming convention:

custom:CATEGORY:NAME

For example:

• custom:model:loaded
• custom:dataset:processed
• custom:pipeline:completed

Subscribing to Event Types

Clients can subscribe to specific event types by specifying query parameters in the SSE connection URL:

GET /api/servers/:id/events?types=metrics:cpu,metrics:memory,alert:*

The following patterns are supported:

• Exact match: metrics:cpu
• Wildcard category: metrics:*
• Wildcard all: * (subscribes to all events)

Event Handling Best Practices

When handling events in client applications:

1. Validate event data before processing
2. Handle reconnection scenarios properly
3. Process events asynchronously to avoid blocking the main thread
4. Implement event buffering for high-frequency events
5. Group related events for efficient UI updates

See Best Practices for more detailed guidance on implementing event handlers.

Event Delivery Guarantees

Events in MCP-Cloud are delivered with an at-least-once guarantee. In rare cases of network issues, the same event may be delivered multiple times. Client implementations should be idempotent (able to safely process the same event multiple times).

Event order is preserved within each event type, but not guaranteed across different event types.