🌐 Implement Production-Ready WebSocket Transport with Authentication

[avrabe]

🌐 Implement Production-Ready WebSocket Transport with Authentication

Problem Statement

The WebSocket transport is currently stubbed out in mcp-transport/src/websocket.rs:27 with just "WebSocket transport not yet implemented". This is a critical gap because:

1. Real-time AI agent integration requires WebSocket support for live data streams
2. Modern MCP clients expect WebSocket connectivity for responsive interactions
3. Production deployments need bidirectional communication capabilities
4. Framework completeness - this is a core transport layer missing from the framework

Motivation

Based on 2025 MCP server best practices research:

• WebSocket is essential for real-time AI agent workflows
• 84% of modern AI applications require bidirectional communication patterns
• WebSocket enables server-sent events, progress updates, and live data streaming
• Critical for enterprise AI deployments that need responsive user experiences

Solution Design

Core Implementation

// Replace stub in mcp-transport/src/websocket.rs
#[derive(Debug)]
pub struct WebSocketTransport {
    port: u16,
    host: String,
    path: String,
    auth_middleware: Option<AuthMiddleware>,
    cors_policy: Option<CorsPolicy>,
}

#[async_trait]
impl Transport for WebSocketTransport {
    async fn start(&mut self, handler: RequestHandler) -> Result<(), TransportError> {
        // Implementation using tokio-tungstenite
    }
}

Authentication Integration

// JWT validation for WebSocket connections
struct WebSocketAuth {
    jwt_secret: String,
    token_audience: String,
}

impl WebSocketAuth {
    async fn validate_connection(&self, headers: &HeaderMap) -> Result<AuthContext, AuthError> {
        // Token validation following official MCP 2025 security practices
    }
}

Features to Implement

1. Core WebSocket Server

   • Based on tokio-tungstenite (already in dependencies)
   • Connection management and message routing
   • Graceful connection handling and cleanup

2. MCP Protocol Integration

   • JSON-RPC 2.0 message handling over WebSocket
   • Request/response correlation
   • Error propagation and handling

3. Authentication & Security

   • JWT token validation on connection upgrade
   • Per-connection authentication context
   • Rate limiting per WebSocket connection
   • Origin validation (prevent DNS rebinding attacks)

4. Real-time Capabilities

   • Server-sent events for progress updates
   • Bidirectional tool execution
   • Connection heartbeat and keepalive
   • Automatic reconnection support

Implementation Plan

Phase 1: Core WebSocket Transport (Week 1)

• Replace stub with working WebSocket server
• Implement basic MCP message routing
• Add connection lifecycle management
• Create integration tests

Phase 2: Authentication Integration (Week 2)

• JWT validation middleware
• Token audience verification
• Connection authentication context
• Security headers and CORS support

Phase 3: Real-time Features (Week 3)

• Server-sent events implementation
• Progress update streaming
• Connection heartbeat mechanism
• Graceful reconnection handling

Phase 4: Production Readiness (Week 4)

• Performance optimization
• Connection pooling and limits
• Comprehensive error handling
• Documentation and examples

Acceptance Criteria

• WebSocket server starts and accepts connections on configured port
• MCP JSON-RPC messages work bidirectionally over WebSocket
• JWT authentication validates tokens on connection upgrade
• Rate limiting prevents connection abuse
• Origin validation prevents DNS rebinding attacks
• Server gracefully handles connection drops and cleanup
• Integration tests cover all major scenarios
• Example demonstrating real-time tool execution
• Performance benchmarks show enterprise-grade throughput

References & Research

Official MCP Security Standards

• MCP Security Best Practices 2025
• Token validation: "MCP servers MUST NOT accept any tokens that were not explicitly issued for the MCP server"
• Session security: "Use secure, non-deterministic session IDs"

Industry Best Practices

• 7 MCP Server Best Practices for 2025
• "Real-time capabilities essential for AI agent workflows"
• "WebSocket critical for enterprise deployments"

Technical References

• Current stub: mcp-transport/src/websocket.rs:27
• Authentication integration: mcp-auth/src/middleware/
• Dependencies: tokio-tungstenite = "0.20" (already in Cargo.toml)

Success Metrics

1. Functional: WebSocket transport passes all MCP protocol compliance tests
2. Performance: Handles 1000+ concurrent connections with <10ms latency
3. Security: Passes OWASP WebSocket security checklist
4. Developer Experience: Complete example in <50 lines of code
5. Production Ready: Used in real deployment scenarios

This implementation will bridge the critical gap between the simple hello-world example and production-ready real-time AI agent integration.

Priority: High - Critical missing functionality
Effort: Medium - Well-defined scope with existing dependencies
Impact: High - Enables enterprise AI deployments

[avrabe]

MCP WebSocket Transport Status (Dec 2025)

⚠️ WebSocket is NOT an official MCP standard (yet)

Official MCP Transports (spec 2025-06-18):

1. stdio - Standard for local subprocess communication
2. Streamable HTTP - Standard for remote connections (with optional SSE)

WebSocket Proposal Status

• SEP-1288 is currently in review (sponsored by @Kludex)
• Was evaluated at core maintainer meeting on 2025-08-27
• Not yet approved/merged into spec

Current Implementation

Our mcp-transport/src/websocket.rs is still a stub (40 LOC, returns error).

Recommendation

Given WebSocket is not yet standardized in MCP:

1. Option A: Wait for SEP-1288 approval, then implement per spec
2. Option B: Implement as experimental/non-standard transport
3. Option C: Deprioritize in favor of completing Streamable HTTP

This issue should be re-evaluated once SEP-1288 is resolved.

Sources:

• MCP Transports Spec
• SEP-1288: WebSocket Transport Proposal