SSE Transport Implementation

The DeployStack Gateway implements Server-Sent Events (SSE) transport to provide VS Code compatibility through a clean dual-endpoint architecture.

Architecture Overview

The Gateway uses a dual-endpoint architecture for SSE-based communication:

• GET /sse: Establishes SSE connection and returns session endpoint
• POST /message: Handles JSON-RPC requests with session context

Core Components

Connection Flow

1. SSE Connection Establishment

GET /sse HTTP/1.1
Accept: text/event-stream

Response:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

event: endpoint
data: /message?session=L8B-xaw3HBZEftyo-JCrHoGWb_iikRZiwGfp9B71-GA

2. Session-Based JSON-RPC

POST /message?session=L8B-xaw3HBZEftyo-JCrHoGWb_iikRZiwGfp9B71-GA
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": {"name": "vscode", "version": "1.0.0"},
    "protocolVersion": "2025-03-26"
  }
}

HTTP Response:

{"status": "accepted", "messageId": 1}

SSE Response:

id: msg-1753710728979-95czkmmq8
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"deploystack-gateway","version":"1.0.0"},"protocolVersion":"2025-03-26","capabilities":{"tools":{"listChanged":false}}}}

Session Management

Session ID Generation

• Algorithm: Cryptographically secure random bytes (32 bytes = 256 bits)
• Encoding: Base64url for URL safety
• Format: L8B-xaw3HBZEftyo-JCrHoGWb_iikRZiwGfp9B71-GA
• Validation: Length and character set validation

Session Lifecycle

1. Creation: Generated on SSE connection establishment
2. Validation: Verified on each JSON-RPC request
3. Activity Tracking: Updated on every message
4. Timeout: 30-minute inactivity timeout
5. Cleanup: Automatic resource cleanup on disconnect

Security Features

• Cryptographic Security: 256-bit entropy prevents session prediction
• Automatic Expiration: Sessions expire after 30 minutes of inactivity
• Connection Validation: Session tied to specific SSE stream
• Resource Cleanup: Automatic cleanup prevents memory leaks

Message Routing

Supported Methods

The SSE transport handles all standard MCP protocol methods:

• initialize: Gateway initialization with capabilities
• notifications/initialized: Client initialization confirmation
• tools/list: Returns available MCP servers as toggleable tools
• tools/call: Executes MCP server management actions
• resources/list: Returns empty resources (handled locally)
• resources/templates/list: Returns empty templates (handled locally)
• prompts/list: Returns empty prompts (handled locally)

Error Handling

Errors are sent via SSE with proper JSON-RPC error format:

id: err-1753710744580-061x9gi8x
event: error
data: {"jsonrpc":"2.0","error":{"code":-32603,"message":"Internal server error","data":"Server not available"},"id":2}

VS Code Integration

Expected Client Behavior

1. Connection: Client connects to http://localhost:9095/sse via SSE
2. Endpoint Discovery: Receives session endpoint via endpoint event
3. Initialization: Sends initialize request to session endpoint
4. Tool Discovery: Calls tools/list to discover available MCP servers
5. Tool Management: Uses tools/call to enable/disable/status MCP servers

Configuration

VS Code MCP client configuration:

{
  "mcpServers": {
    "deploystack": {
      "url": "http://localhost:9095/sse"
    }
  }
}

Performance Considerations

Connection Management

• Keep-Alive: Persistent SSE connections reduce connection overhead
• Heartbeat: Optional heartbeat messages maintain connection health
• Timeout Handling: Automatic cleanup prevents resource exhaustion

Memory Management

• Session Cleanup: Automatic cleanup on disconnect or timeout
• Stream Management: Proper SSE stream lifecycle management
• Error Recovery: Graceful handling of connection failures

Client Detection

The Gateway detects SSE clients based on:

• Accept Header: text/event-stream indicates SSE client
• User-Agent: VS Code, Cursor, or other MCP clients
• Request Method: GET for SSE establishment, POST for session-based messaging

Implementation Details

SSE Event Format

All SSE events follow this structure:

id: <unique-message-id>
event: <event-type>
data: <json-payload>

Event Types

• endpoint: Session endpoint URL
• message: JSON-RPC response
• error: JSON-RPC error response
• notification: Server notifications

Connection Cleanup

Cleanup triggers include:

• Client disconnect (close event)
• Connection error (error event)
• Stream finish (finish event)
• Session timeout (30 minutes)

Security Considerations

Session Security

• Unpredictable IDs: Cryptographically secure generation
• Time-Limited: Automatic expiration prevents indefinite access
• Connection-Bound: Sessions tied to specific SSE connections

Network Security

• Localhost Only: Server binds only to localhost interface
• No External Access: No exposure to external networks
• CORS Configuration: Restricted to authorized origins

The SSE transport implementation provides a robust, secure, and performant foundation for VS Code integration with clean dual-endpoint architecture.