diff --git a/docs/advanced-usage/available-tools/use-mcp-tool.md b/docs/advanced-usage/available-tools/use-mcp-tool.md index a8224b6d..d194e4fb 100644 --- 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 index 7a9af8c2..3934a9a2 100644 --- 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 index 4190c92c..7e322c52 100644 --- 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/features/mcp/using-mcp-in-roo.mdx b/docs/features/mcp/using-mcp-in-roo.mdx index caab164b..827f6185 100644 --- a/docs/features/mcp/using-mcp-in-roo.mdx +++ b/docs/features/mcp/using-mcp-in-roo.mdx @@ -73,23 +73,23 @@ Both files use a JSON format with a `mcpServers` object containing named server } ``` *Example of MCP Server config in Roo Code (STDIO Transport)* - + ### Understanding Transport Types - - MCP supports two transport types for server communication: - + + MCP supports three transport types for server communication: STDIO for local servers, Streamable HTTP (recommended for new remote servers), and SSE (for legacy remote servers). + #### STDIO Transport - + Used for local servers running on your machine: - + * Communicates via standard input/output streams * Lower latency (no network overhead) * Better security (no network exposure) * Simpler setup (no HTTP server needed) * Runs as a child process on your machine - + For more in-depth information about how STDIO transport works, see [STDIO Transport](/features/mcp/server-transports#stdio-transport). - + STDIO configuration parameters: * `command` (required): The executable to run (e.g., `node`, `python`, `npx`, or an absolute path). @@ -116,48 +116,87 @@ Both files use a JSON format with a `mcpServers` object containing named server } } ``` - - #### SSE Transport - - Used for remote servers accessed over HTTP/HTTPS: - - * Communicates via Server-Sent Events protocol +#### Streamable HTTP Transport + +This is the **modern standard** for remote servers accessed over HTTP/HTTPS, offering more flexibility and replacing the legacy SSE transport for new implementations. + +* Communicates via HTTP POST/GET to a single MCP endpoint +* Optionally uses Server-Sent Events (SSE) for streaming +* Can be hosted on a different machine +* Supports multiple client connections +* Requires network access +* Allows centralized deployment and management + +For more in-depth information about how Streamable HTTP transport works, see [Streamable HTTP Transport](/features/mcp/server-transports#streamable-http-transport). + +Streamable HTTP configuration parameters: + +* `type` (required): Must be set to `"streamable-http"`. +* `url` (required): The full URL of the remote MCP server's single endpoint (e.g., `https://your-server.com/mcp`). +* `headers` (optional): An object containing custom HTTP headers to send with requests (e.g., for authentication tokens). +* `alwaysAllow` (optional): An array of tool names from this server to automatically approve. +* `disabled` (optional): Set to `true` to disable this server configuration. + +Streamable HTTP configuration example: +```json +{ + "mcpServers": { + "modern-remote-server": { + "type": "streamable-http", + "url": "https://your-modern-server.com/api/mcp-endpoint", + "headers": { + "X-API-Key": "your-secure-api-key" + }, + "alwaysAllow": ["newToolA", "newToolB"], + "disabled": false + } + } +} +``` + + #### SSE Transport (Legacy) + + Used for older remote servers accessed over HTTP/HTTPS. **For new remote server implementations, [Streamable HTTP Transport](#streamable-http-transport) is recommended.** + + * Communicates via Server-Sent Events protocol (typically requires separate endpoints for client-to-server and server-to-client communication) * Can be hosted on a different machine * Supports multiple client connections * Requires network access * Allows centralized deployment and management - - For more in-depth information about how SSE transport works, see [SSE Transport](/features/mcp/server-transports#sse-transport). - - SSE configuration parameters: - * `url` (required): The full URL endpoint of the remote MCP server (e.g., `https://your-server.com/mcp`). + For more in-depth information about how legacy SSE transport works, see [SSE Transport (Legacy)](/features/mcp/server-transports#sse-transport-legacy). + + SSE (Legacy) configuration parameters: + + * `type` (optional, but recommended for clarity): Should be set to `"sse"` if providing a `url` for an SSE server, to distinguish from Streamable HTTP. If `url` is present and `type` is omitted, Roo Code might try to infer, but explicit declaration is safer. + * `url` (required): The base URL for the remote MCP server. For legacy SSE, this usually implies separate paths like `/events` (for SSE stream) and `/message` (for POST requests) will be derived or expected by the server. * `headers` (optional): An object containing custom HTTP headers to send with requests (e.g., for authentication tokens). * `alwaysAllow` (optional): An array of tool names from this server to automatically approve. * `disabled` (optional): Set to `true` to disable this server configuration. - SSE configuration example: + SSE (Legacy) configuration example: ```json { "mcpServers": { - "remote-server": { - "url": "https://your-server-url.com/mcp", + "legacy-remote-server": { + "type": "sse", // Explicitly define as SSE + "url": "https://your-legacy-server-url.com/mcp-base", // Base URL "headers": { - "Authorization": "Bearer your-token" // Example: Authentication header + "Authorization": "Bearer your-legacy-token" }, - "alwaysAllow": ["tool3"], + "alwaysAllow": ["oldToolX"], "disabled": false } } } ``` - + ## Enabling or Disabling MCP Servers Disabling your MCP Servers here will remove all MCP related logic and definitions from your system prompt, reducing your token usage. This will prevent Roo Code from connecting to any MCP servers, and the `use_mcp_tool` and `access_mcp_resource` tools will not be available. Check this off if you don't intend to use MCP Servers. This is on by default. 1. Click the icon in the top navigation of the Roo Code pane -2. Check/Uncheck `Enable MCP Servers` +2. Check/Uncheck `Enable MCP Servers` Enable MCP Servers toggle @@ -166,7 +205,7 @@ Disabling your MCP Servers here will remove all MCP related logic and definition Disabling your MCP Server Creation here will just remove the instructions from your system prompt that Roo Code uses to write MCP servers while not removing the context related to operating them. This reduces token usage. This is on by default. 1. Click the icon in the top navigation of the Roo Code pane -2. Check/Uncheck `Enable MCP Server Creation` +2. Check/Uncheck `Enable MCP Server Creation` Enable MCP Server Creation toggle diff --git a/docs/features/mcp/what-is-mcp.md b/docs/features/mcp/what-is-mcp.md index e293b6c7..0584f257 100644 --- a/docs/features/mcp/what-is-mcp.md +++ b/docs/features/mcp/what-is-mcp.md @@ -46,4 +46,4 @@ Ready to dig deeper? Check out these guides: - [MCP Overview](/features/mcp/overview) - A quick glance at the MCP documentation structure - [Using MCP in Roo Code](/features/mcp/using-mcp-in-roo) - Get started with MCP in Roo, including creating simple servers - [MCP vs API](/features/mcp/mcp-vs-api) - Technical advantages compared to traditional APIs -- [STDIO & SSE Transports](/features/mcp/server-transports) - Local vs. hosted deployment models \ No newline at end of file +- [STDIO & Streamable HTTP & SSE Transports](/features/mcp/server-transports) - Local vs. hosted deployment models \ No newline at end of file