add streamable http info

taylorwilsdon · taylorwilsdon · commit c3222ef8b947 · 2025-06-02T13:53:24.000-04:00
diff --git a/docs/advanced-usage/available-tools/use-mcp-tool.md b/docs/advanced-usage/available-tools/use-mcp-tool.md
@@ -25,7 +25,7 @@ This tool allows Roo to access specialized functionality provided by external MC
 ## Key Features
 
 - Uses the standardized MCP protocol via the `@modelcontextprotocol/sdk` library
-- Supports multiple transport mechanisms (StdioClientTransport and SSEClientTransport)
+- Supports multiple transport mechanisms (StdioClientTransport, StreamableHTTPClientTransport and SSEClientTransport)
 - Validates arguments using Zod schema validation on both client and server sides
 - Processes multiple response content types: text, image, and resource references
 - Manages server lifecycle with automatic restarts when server code changes
@@ -69,6 +69,7 @@ When the `use_mcp_tool` tool is invoked, it follows this process:
    - The system selects the appropriate transport mechanism:
      - `StdioClientTransport`: For communicating with local processes via standard I/O
      - `SSEClientTransport`: For communicating with HTTP servers via Server-Sent Events
+     - `StreamableHTTPClientTransport`: For communicating with HTTP servers via Streamable HTTP Events
    - A request is sent with validated server name, tool name, and arguments
    - Communication uses the `@modelcontextprotocol/sdk` library for standardized interactions
    - Request execution is tracked with timeout handling to prevent hanging operations
diff --git a/docs/features/mcp/overview.md b/docs/features/mcp/overview.md
@@ -15,7 +15,7 @@ This documentation is organized into several sections:
 
 * [**What is MCP?**](/features/mcp/what-is-mcp) - Clear explanation of the Model Context Protocol, its client-server architecture, and how it enables AI systems to interact with external tools.
 
-* [**STDIO & SSE Transports**](/features/mcp/server-transports) - Detailed comparison of local (STDIO) and remote (SSE) transport mechanisms with deployment considerations for each approach.
+* [**STDIO, Streamable HTTP & SSE Transports**](/features/mcp/server-transports) - Detailed comparison of local (STDIO) and remote (Streamable HTTP & legacy SSE) transport mechanisms with deployment considerations for each approach.
 
 * [**MCP vs API**](/features/mcp/mcp-vs-api) - Analysis of the fundamental distinction between MCP and REST APIs, explaining how they operate at different layers of abstraction for AI systems.
 
diff --git a/docs/features/mcp/server-transports.md b/docs/features/mcp/server-transports.md
@@ -1,11 +1,11 @@
 ---
 title: MCP Server Transports
-sidebar_label: STDIO & SSE Transports
+sidebar_label: STDIO, Streamable HTTP & SSE Transports
 ---
 
-# MCP Server Transports: STDIO & SSE
+# MCP Server Transports: STDIO, Streamable HTTP & SSE
 
-Model Context Protocol (MCP) supports two primary transport mechanisms for communication between Roo Code and MCP servers: Standard Input/Output (STDIO) and Server-Sent Events (SSE). Each has distinct characteristics, advantages, and use cases.
+Model Context Protocol (MCP) supports three primary transport mechanisms for communication between Roo Code and MCP servers: Standard Input/Output (STDIO), Streamable HTTP (the modern standard), and Server-Sent Events (SSE) (for legacy use). Each has distinct characteristics, advantages, and use cases.
 
 ## STDIO Transport
 
@@ -58,10 +58,71 @@ const server = new Server({name: 'local-server', version: '1.0.0'});
 const transport = new StdioServerTransport(server);
 transport.listen();
 ```
+## Streamable HTTP Transport
 
-## SSE Transport
+Streamable HTTP transport is the modern standard for remote MCP server communication, replacing the older HTTP+SSE transport. It operates over HTTP/HTTPS and allows for more flexible server implementations.
 
-Server-Sent Events (SSE) transport runs on a remote server and communicates over HTTP/HTTPS.
+### How Streamable HTTP Transport Works
+
+1. The server provides a single HTTP endpoint (MCP endpoint) that supports both POST and GET methods.
+2. The client (Roo Code) sends requests to this MCP endpoint using HTTP POST.
+3. The server processes the request and sends back a response.
+4. Optionally, the server can use Server-Sent Events (SSE) over the same connection to stream multiple messages or notifications to the client. This allows for basic request-response interactions as well as more advanced streaming and server-initiated communication.
+
+```
+Client                             Server
+  |                                  |
+  |---- HTTP POST /mcp_endpoint ---->| (client request)
+  |                                  | (processes request)
+  |<--- HTTP Response / SSE Stream --| (server response / stream)
+  |                                  |
+```
+
+### Streamable HTTP Characteristics
+
+* **Modern Standard**: Preferred method for new remote MCP server implementations.
+* **Remote Access**: Can be hosted on a different machine from Roo Code.
+* **Scalability**: Can handle multiple client connections concurrently.
+* **Protocol**: Works over standard HTTP/HTTPS.
+* **Flexibility**: Supports simple request-response and advanced streaming.
+* **Single Endpoint**: Uses a single URL path for all MCP communication.
+* **Authentication**: Can use standard HTTP authentication mechanisms.
+* **Backwards Compatibility**: Servers can maintain compatibility with older HTTP+SSE clients.
+
+### When to Use Streamable HTTP
+
+Streamable HTTP transport is ideal for:
+
+* All new remote MCP server developments.
+* Servers requiring robust, scalable, and flexible communication.
+* Integrations that might involve streaming data or server-sent notifications.
+* Public services or centralized tools.
+* Replacing legacy SSE transport implementations.
+
+### Streamable HTTP Implementation Example
+
+Configuration in `settings.json`:
+```json
+"mcp.servers": {
+  "StreamableHTTPMCPName": {
+    "type": "streamable-http",
+    "url": "http://localhost:8080/mcp"
+  }
+}
+```
+
+For server-side implementation, refer to the MCP SDK documentation for `StreamableHTTPClientTransport`.
+
+### Backwards Compatibility with HTTP+SSE
+
+Clients and servers can maintain backwards compatibility with the deprecated HTTP+SSE transport (from protocol version 2024-11-05).
+
+Servers wanting to support older clients should:
+* Continue to host both the SSE (`/events`) and POST (`/message`) endpoints of the old transport, alongside the new “MCP endpoint” defined for the Streamable HTTP transport.
+
+## SSE Transport (Legacy)
+
+Server-Sent Events (SSE) transport is a legacy method for remote server communication over HTTP/HTTPS. For new implementations, **Streamable HTTP transport is recommended.** SSE remains available for compatibility with older MCP servers.
 
 ### How SSE Transport Works
 
@@ -145,9 +206,9 @@ A local file search tool using STDIO would:
 * Not require network configuration
 * Need to be installed alongside Roo Code or via a package manager
 
-### SSE: Hosted Deployment Model
+### Streamable HTTP / SSE (Legacy): Hosted Deployment Model
 
-SSE servers can be deployed to remote servers and accessed over the network:
+Streamable HTTP (recommended) and legacy SSE servers can be deployed to remote servers and accessed over the network:
 
 * **Installation**: Installed once on a server, accessed by many users
 * **Distribution**: Single deployment serves multiple clients
@@ -175,22 +236,23 @@ Some scenarios benefit from a hybrid approach:
 2. **SSE with Local Commands**: A remote SSE server that can trigger operations on the client machine through callbacks
 3. **Gateway Pattern**: STDIO servers for local operations that connect to SSE servers for specialized functions
 
-## Choosing Between STDIO and SSE
-
-| Consideration | STDIO | SSE |
-|---------------|-------|-----|
-| **Location** | Local machine only | Local or remote |
-| **Clients** | Single client | Multiple clients |
-| **Performance** | Lower latency | Higher latency (network overhead) |
-| **Setup Complexity** | Simpler | More complex (requires HTTP server) |
-| **Security** | Inherently secure | Requires explicit security measures |
-| **Network Access** | Not needed | Required |
-| **Scalability** | Limited to local machine | Can distribute across network |
-| **Deployment** | Per-user installation | Centralized installation |
-| **Updates** | Distributed updates | Centralized updates |
-| **Resource Usage** | Uses client resources | Uses server resources |
-| **Dependencies** | Client-side dependencies | Server-side dependencies |
+## Choosing Between Transports
+
+| Consideration | STDIO | Streamable HTTP | SSE (Legacy) |
+|---------------|-------|-----------------|--------------|
+| **Location** | Local machine only | Local or remote | Local or remote |
+| **Clients** | Single client | Multiple clients | Multiple clients |
+| **Performance** | Lower latency | Higher latency (network overhead) | Higher latency (network overhead) |
+| **Setup Complexity** | Simpler | More complex (requires HTTP server) | More complex (requires HTTP server, potentially two endpoints) |
+| **Security** | Inherently secure | Requires explicit security measures | Requires explicit security measures |
+| **Network Access** | Not needed | Required | Required |
+| **Scalability** | Limited to local machine | Can distribute across network | Can distribute across network |
+| **Deployment** | Per-user installation | Centralized installation | Centralized installation |
+| **Updates** | Distributed updates | Centralized updates | Centralized updates |
+| **Resource Usage** | Uses client resources | Uses server resources | Uses server resources |
+| **Dependencies** | Client-side dependencies | Server-side dependencies | Server-side dependencies |
+| **Recommendation** | Ideal for local, secure, single-client tools | **Modern standard for all new remote servers** | Legacy, for existing older servers |
 
 ## Configuring Transports in Roo Code
 
-For detailed information on configuring STDIO and SSE transports in Roo Code, including example configurations, see the [Understanding Transport Types](/features/mcp/using-mcp-in-roo#understanding-transport-types) section in the Using MCP in Roo Code guide.
+For detailed information on configuring STDIO, Streamable HTTP, and SSE (Legacy) transports in Roo Code, including example configurations, see the [Understanding Transport Types](/features/mcp/using-mcp-in-roo#understanding-transport-types) section in the Using MCP in Roo Code guide.
