SSE Support

Server-Sent Events (SSE) Support

MCP Catie fully supports the MCP Streamable HTTP transport with Server-Sent Events (SSE). This document explains how SSE works in MCP Catie and how to use it effectively.

What are Server-Sent Events?

Server-Sent Events (SSE) is a standard that enables servers to push updates to clients over HTTP. In the context of MCP, SSE allows:

• Models to stream tokens as they're generated
• Clients to receive real-time updates
• Long-lived connections for continuous interaction

MCP Streamable HTTP Transport

The MCP Streamable HTTP transport uses:

• POST requests for client-to-server communication
• GET requests with SSE for server-to-client streaming

MCP Catie implements this transport protocol and proxies both types of requests to backend services.

How SSE Works in MCP Catie

1. Connection Establishment:

   • Client sends a GET request to /mcp with an Accept: text/event-stream header
   • MCP Catie forwards this request to the appropriate backend
   • Backend establishes an SSE stream
   • MCP Catie proxies this stream back to the client

2. Message Streaming:

   • Backend sends SSE messages
   • MCP Catie forwards these messages to the client
   • No transformation or modification of messages occurs

3. Connection Termination:

   • Either party can close the connection
   • MCP Catie handles connection cleanup

SSE Headers

MCP Catie preserves important headers for SSE connections:

• Cache-Control: no-cache
• Connection: keep-alive
• Content-Type: text/event-stream
• Transfer-Encoding: chunked

Session Management with SSE

SSE connections are associated with sessions just like regular requests:

• The Mcp-Session-Id header identifies the session
• All SSE connections for the same session are routed to the same backend
• If a session has an active SSE connection, new connections may be rejected

Handling Connection Drops

Network issues can cause SSE connections to drop. MCP Catie handles this by:

• Detecting connection termination
• Cleaning up resources
• Allowing clients to reconnect with the same session ID

Clients should implement reconnection logic with exponential backoff.

SSE Configuration

You can configure SSE-specific settings:

QQQ sse: max_connections: 1000 heartbeat_interval: 30s read_timeout: 5m write_timeout: 30s QQQ

• max_connections: Maximum number of concurrent SSE connections
• heartbeat_interval: How often to send keepalive messages
• read_timeout: Maximum time to wait for backend response
• write_timeout: Maximum time to wait when writing to client

Monitoring SSE Connections

MCP Catie provides metrics for monitoring SSE connections:

• mcp_router_sse_connections: Current number of active SSE connections
• mcp_router_sse_connections_total: Total number of SSE connections established
• mcp_router_sse_errors_total: Number of SSE connection errors

These metrics are available at the /metrics endpoint.

SSE Performance Considerations

SSE connections are long-lived and consume resources:

1. Each connection uses a socket file descriptor
2. Backends must maintain state for each connection
3. Network infrastructure must support long-lived connections

For high-volume deployments:

• Increase system file descriptor limits
• Configure load balancers for long-lived connections
• Monitor resource usage carefully

Example: SSE Client

Here's an example of a simple JavaScript client that connects to MCP Catie using SSE:

QQQ const sessionId = generateUUID(); const eventSource = new EventSource('/mcp?session_id=' + sessionId, { headers: { 'Mcp-Session-Id': sessionId } });

eventSource.onmessage = (event) => { const data = JSON.parse(event.data); console.log('Received:', data); };

eventSource.onerror = (error) => { console.error('SSE error:', error); eventSource.close(); // Implement reconnection logic here };

// To send a request in the same session: fetch('/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Mcp-Session-Id': sessionId }, body: JSON.stringify({ jsonrpc: '2.0', method: 'sampling/complete', params: { /* ... */ }, id: 1 }) }); QQQ

Best Practices

1. Reconnection Logic: Implement robust reconnection with backoff
2. Resource Management: Close SSE connections when not needed
3. Error Handling: Handle connection errors gracefully
4. Monitoring: Watch SSE connection metrics
5. Load Testing: Test with realistic numbers of concurrent connections