docs: update Gateway documentation to reflect support for Streamable HTTP transport and enhance session management details

Author: Lasim

docs/development/gateway/index.mdx

@@ -14,21 +14,22 @@ The DeployStack Gateway is the local secure proxy that connects developers to th
 
 ## Architecture Overview
 
-The Gateway implements a sophisticated Control Plane / Data Plane architecture with dual transport support:
+The Gateway implements a sophisticated Control Plane / Data Plane architecture with comprehensive transport support:
 
 - **Control Plane**: Authenticates with `cloud.deploystack.io` to download team configurations and access policies
-- **Data Plane**: Manages local MCP server processes with both stdio and SSE transport protocols
+- **Data Plane**: Manages local MCP server processes with stdio, SSE, and Streamable HTTP transport protocols
 - **Security Layer**: Injects credentials securely into process environments without exposing them to developers
 - **Session Management**: Handles secure SSE connections with cryptographic session IDs for VS Code compatibility
+- **Transport Layer**: Supports both legacy SSE transport and modern Streamable HTTP transport for maximum client compatibility
 
 ## Core Features
 
 <Cards>
   <Card 
     icon={<Terminal />} 
-    title="Dual Transport Support"
+    title="Triple Transport Support"
   >
-    Supports both stdio transport for CLI tools and SSE transport for VS Code compatibility
+    Supports stdio transport for CLI tools, SSE transport for VS Code compatibility, and Streamable HTTP for modern MCP clients
   </Card>
 
   <Card 
@@ -118,9 +119,11 @@ Manages the lifecycle of MCP server processes, including:
 - Environment variable injection
 
 ### HTTP Proxy Server
-Exposes dual endpoints for different client types:
-- **GET /sse**: SSE connection establishment for VS Code
+Exposes multiple endpoints for different client types:
+- **GET /sse**: SSE connection establishment for VS Code and legacy clients
 - **POST /message**: Session-based JSON-RPC for SSE clients
+- **POST /mcp**: Streamable HTTP endpoint for modern MCP clients
+- **GET /health**: Health check endpoint for monitoring
 
 ### Session Manager
 Handles secure SSE connections with:
@@ -163,11 +166,16 @@ The Gateway works with MCP server configurations in this format:
 1. **Authentication**: Gateway authenticates with cloud control plane
 2. **Config Download**: Downloads team's MCP server configurations
 3. **Persistent Process Startup**: Starts all configured MCP servers as background processes when gateway launches
-4. **HTTP Server**: Starts local HTTP server with SSE endpoints immediately available (default: `localhost:9095/sse`)
-5. **Request Handling**: Receives MCP requests from development tools and routes to already-running processes
+4. **HTTP Server**: Starts local HTTP server with multiple endpoints immediately available:
+   - SSE endpoint: `localhost:9095/sse` (for VS Code and legacy clients)
+   - Messages endpoint: `localhost:9095/message` (for session-based JSON-RPC)
+   - MCP endpoint: `localhost:9095/mcp` (for modern Streamable HTTP clients)
+   - Health endpoint: `localhost:9095/health` (for monitoring)
+5. **Request Handling**: Receives MCP requests from development tools and intelligently routes to appropriate transport
 6. **Process Management**: Maintains persistent background processes as described in [Gateway Process Management](/development/gateway/process-management).
 7. **Credential Injection**: Securely injects environment variables into running processes at startup
 8. **Tool Routing**: Routes namespaced tool calls to persistent MCP servers via stdio transport
+9. **Transport Selection**: Automatically detects client capabilities and uses appropriate transport (SSE or Streamable HTTP)
 
 For detailed information about the caching system, see [Gateway Caching System](/development/gateway/caching-system).
 
@@ -207,10 +215,3 @@ The Gateway is actively under development. Key areas for contribution:
 - **Performance**: Optimizing stdio communication
 - **Platform Support**: Adding Windows/Linux compatibility
 - **Error Handling**: Robust error recovery
-
-## Roadmap
-
-- **Phase 2**: Enhanced process lifecycle management
-- **Phase 3**: Support for remote MCP servers (HTTP transport)
-- **Phase 4**: Advanced monitoring and analytics
-- **Future**: Plugin system for custom MCP server types

docs/development/gateway/session-management.mdx

@@ -1,6 +1,6 @@
 ---
 title: Session Management
-description: Cryptographically secure session lifecycle management for SSE connections
+description: Cryptographically secure session lifecycle management for SSE and Streamable HTTP connections
 sidebar: Session Management
 icon: Key
 ---
@@ -10,14 +10,16 @@ import { Key, Clock, Shield, Trash2 } from 'lucide-react';
 
 # Session Management
 
-The DeployStack Gateway implements a robust session management system that provides cryptographically secure session handling for persistent SSE connections while ensuring automatic cleanup and resource management.
+The DeployStack Gateway implements a robust session management system that provides cryptographically secure session handling for both persistent SSE connections and optional Streamable HTTP sessions while ensuring automatic cleanup and resource management.
 
 ## Architecture Overview
 
-The session management system consists of two primary components working together to provide secure, persistent connections:
+The session management system consists of multiple components working together to provide secure connections across different transport protocols:
 
 - **SessionManager**: Handles session lifecycle, validation, and SSE stream management
 - **SSEHandler**: Manages Server-Sent Events connections and message routing
+- **StreamableHTTPHandler**: Manages Streamable HTTP connections with optional session support
+- **Transport Layer**: Intelligent routing between SSE and Streamable HTTP based on client capabilities
 
 ## Core Components
 
@@ -78,14 +80,16 @@ private validateSessionId(sessionId: string): boolean {
 ## Session Lifecycle
 
 ### 1. Creation Phase
-**Trigger**: SSE connection establishment via `GET /sse`
+**Triggers**: 
+- SSE connection establishment via `GET /sse`
+- Optional session creation for Streamable HTTP via `POST /mcp` with session headers
 
 **Process:**
 1. Generate cryptographically secure session ID
 2. Create session object with metadata
-3. Associate with SSE stream
+3. Associate with SSE stream (for SSE transport) or track session state (for Streamable HTTP)
 4. Schedule automatic cleanup timer
-5. Send endpoint event to client
+5. Send endpoint event to client (SSE) or return session headers (Streamable HTTP)
 
 **Session Object:**
 ```typescript
@@ -219,6 +223,24 @@ getStatus() {
 - **Cleanup Events**: Cleanup reasons and timing logged
 - **Error Conditions**: Detailed error logging for troubleshooting
 
+## Transport-Specific Session Handling
+
+### SSE Transport Sessions
+SSE transport requires persistent sessions for connection management:
+
+- **Mandatory Sessions**: All SSE connections must have associated sessions
+- **Stream Binding**: Sessions are bound to specific SSE streams
+- **Real-time Communication**: Messages sent via SSE events in real-time
+- **Connection Lifecycle**: Session lifecycle tied to SSE connection state
+
+### Streamable HTTP Transport Sessions
+Streamable HTTP transport supports optional sessions for enhanced functionality:
+
+- **Optional Sessions**: Sessions can be used but are not required
+- **Stateless Operation**: Supports both stateless and session-based operation
+- **Header-Based**: Session IDs passed via `Mcp-Session-Id` header
+- **Flexible Lifecycle**: Sessions can span multiple HTTP requests
+
 ## Integration Points
 
 ### SSE Handler Integration
@@ -235,21 +257,44 @@ this.sseHandler.sendMessage(sessionId, response);
 this.sseHandler.sendError(sessionId, errorResponse);
 ```
 
-### HTTP Proxy Integration
-Session validation in the HTTP proxy:
+### Streamable HTTP Handler Integration
+The session manager provides optional session support for Streamable HTTP:
 
 ```typescript
-// Session validation on each request
-const session = this.sessionManager.getSession(sessionId);
-if (!session) {
-  // Handle invalid session
+// Optional session validation for Streamable HTTP
+const sessionId = request.headers['mcp-session-id'];
+if (sessionId) {
+  const session = this.sessionManager.getSession(sessionId);
+  if (session) {
+    this.sessionManager.updateActivity(sessionId);
+  }
 }
 
-// Activity tracking
-this.sessionManager.updateActivity(sessionId);
+// Stateless operation when no session provided
+if (!sessionId) {
+  // Handle request without session context
+}
+```
+
+### HTTP Proxy Integration
+Session validation across both transports in the HTTP proxy:
 
-// Error counting
-this.sessionManager.incrementErrorCount(sessionId);
+```typescript
+// Transport-aware session handling
+if (isSSETransport) {
+  // SSE requires session validation
+  const session = this.sessionManager.getSession(sessionId);
+  if (!session) {
+    throw new Error('Invalid session for SSE transport');
+  }
+  this.sessionManager.updateActivity(sessionId);
+} else if (isStreamableHTTP && sessionId) {
+  // Streamable HTTP optional session support
+  const session = this.sessionManager.getSession(sessionId);
+  if (session) {
+    this.sessionManager.updateActivity(sessionId);
+  }
+}
 ```
 
 ## Best Practices