Struct WebSocketTransport

pub struct WebSocketTransport { /* private fields */ }

WebSocket-based MCP transport

Provides real-time bidirectional communication with MCP servers over WebSocket connections. This transport supports secure connections (WSS), Bearer token authentication, and concurrent request/response handling with proper JSON-RPC 2.0 message correlation.

Features

• Async WebSocket Communication: Built on tokio-tungstenite for high-performance async I/O
• Request/Response Matching: Automatic correlation of responses using atomic request IDs
• Bearer Token Support: Authentication via Authorization header during handshake
• Connection Management: Proper ping/pong and connection lifecycle handling
• Concurrent Operations: Split stream architecture allows simultaneous read/write operations

Architecture

The transport uses a split-stream design where the WebSocket connection is divided into separate read and write halves, each protected by async mutexes. This allows concurrent operations while maintaining thread safety. Request IDs are generated atomically to ensure unique identification of requests and proper response correlation.

Example Usage

use mistralrs_mcp::transport::{WebSocketTransport, McpTransport};
use std::collections::HashMap;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create headers with Bearer token
    let mut headers = HashMap::new();
    headers.insert("Authorization".to_string(), "Bearer your-token".to_string());

    // Connect to WebSocket MCP server
    let transport = WebSocketTransport::new(
        "wss://api.example.com/mcp".to_string(),
        Some(30), // 30 second timeout
        Some(headers)
    ).await?;

    // Use the transport for MCP communication
    let result = transport.send_request("tools/list", serde_json::Value::Null).await?;
    println!("Available tools: {}", result);

    Ok(())
}

Protocol Compliance

This transport implements the Model Context Protocol (MCP) specification over WebSocket, adhering to JSON-RPC 2.0 message format with proper error handling and response correlation.

Implementations

impl WebSocketTransport

pub async fn new( url: String, _timeout_secs: Option<u64>, headers: Option<HashMap<String, String>>, ) -> Result<Self>

Creates a new WebSocket transport connection to an MCP server

Arguments

• url - WebSocket URL (ws:// or wss://)
• _timeout_secs - Connection timeout (currently unused, reserved for future use)
• headers - Optional HTTP headers for WebSocket handshake (e.g., Bearer tokens)

Returns

A configured WebSocketTransport ready for MCP communication

Errors

• Invalid URL format
• WebSocket connection failure
• Header parsing errors
• Network connectivity issues

Example

use mistralrs_mcp::transport::WebSocketTransport;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut headers = HashMap::new();
    headers.insert("Authorization".to_string(), "Bearer token123".to_string());
     
    let transport = WebSocketTransport::new(
        "wss://mcp.example.com/api".to_string(),
        Some(30),
        Some(headers)
    ).await?;
     
    Ok(())
}

Trait Implementations

impl McpTransport for WebSocketTransport

fn send_request<'life0, 'life1, 'async_trait>( &'life0 self, method: &'life1 str, params: Value, ) -> Pin<Box<dyn Future<Output = Result<Value>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Sends an MCP request over WebSocket and waits for the corresponding response

This method implements the JSON-RPC 2.0 protocol over WebSocket, handling:

• Unique request ID generation for response correlation
• Concurrent request processing with proper message ordering
• Error handling for both transport and protocol errors
• Message filtering to match responses with requests

Arguments

• method - The MCP method name (e.g., “tools/list”, “tools/call”)
• params - JSON parameters for the method call

Returns

The result portion of the JSON-RPC response

Errors

• WebSocket connection errors
• JSON serialization/deserialization errors
• MCP server errors (returned in JSON-RPC error field)
• Timeout or connection closure

Example

use mistralrs_mcp::transport::{WebSocketTransport, McpTransport};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let transport = WebSocketTransport::new(
        "wss://api.example.com/mcp".to_string(),
        None,
        None
    ).await?;
     
    // List available tools
    let tools = transport.send_request("tools/list", serde_json::Value::Null).await?;
     
    // Call a specific tool
    let params = json!({"query": "example search"});
    let result = transport.send_request("tools/call", params).await?;
     
    Ok(())
}

fn ping<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Sends a WebSocket ping frame to test connection health

This method sends a ping frame to the server and expects a pong response, which helps verify that the WebSocket connection is still active and responsive.

Returns

Ok(()) if the ping was sent successfully

Errors

• WebSocket send errors
• Connection closure

fn close<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Gracefully closes the WebSocket connection

Sends a close frame to the server to properly terminate the connection according to the WebSocket protocol. The server should respond with its own close frame to complete the closing handshake.

Returns

Ok(()) if the close frame was sent successfully

Errors

• WebSocket send errors
• Connection already closed