π OpenHands: AI-Driven Development
docs: Add SHTTP transport documentation to MCP usage guide (#9701)
Ryan H. Tran1d04a83e08d1
diff --git a/docs/usage/mcp.mdx b/docs/usage/mcp.mdxindex 846f9de03c..2f0361049e 100644--- a/docs/usage/mcp.mdx+++ b/docs/usage/mcp.mdx@@ -29,6 +29,15 @@ sse_servers = [{url="https://secure-example.com/mcp", api_key="your-api-key"}]+# SHTTP Servers - External servers that communicate via Streamable HTTP+shttp_servers = [+ # Basic SHTTP server with just a URL+ "http://example.com:8080/mcp",++ # SHTTP server with API key authentication+ {url="https://secure-example.com/mcp", api_key="your-api-key"}+]+# Stdio Servers - Local processes that communicate via standard input/outputstdio_servers = [# Basic stdio server@@ -57,6 +66,22 @@ SSE servers are configured using either a string URL or an object with the follo- Type: `str`- Description: The URL of the SSE server+- `api_key` (optional)+ - Type: `str`+ - Description: API key for authentication++### SHTTP Servers++SHTTP (Streamable HTTP) servers are configured using either a string URL or an object with the following properties:++- `url` (required)+ - Type: `str`+ - Description: The URL of the SHTTP server++- `api_key` (optional)+ - Type: `str`+ - Description: API key for authentication+### Stdio ServersStdio servers are configured using an object with the following properties:@@ -84,7 +109,7 @@ Stdio servers are configured using an object with the following properties:When OpenHands starts, it:1. Reads the MCP configuration.-2. Connects to any configured SSE servers.+2. Connects to any configured SSE and SHTTP servers.3. Starts any configured stdio servers.4. Registers the tools provided by these servers with the agent.@@ -93,3 +118,23 @@ The agent can then use these tools just like any built-in tool. When the agent c1. OpenHands routes the call to the appropriate MCP server.2. The server processes the request and returns a response.3. OpenHands converts the response to an observation and presents it to the agent.++## Transport Protocols++OpenHands supports three different MCP transport protocols:++### Server-Sent Events (SSE)+SSE is a legacy HTTP-based transport that uses Server-Sent Events for server-to-client communication and HTTP POST requests for client-to-server communication. This transport is suitable for basic streaming scenarios but has limitations in session management and connection resumability.++### Streamable HTTP (SHTTP)+SHTTP is the modern HTTP-based transport protocol that provides enhanced features over SSE:++- **Improved Session Management**: Supports stateful sessions with session IDs for maintaining context across requests+- **Connection Resumability**: Can resume broken connections and replay missed messages using event IDs+- **Bidirectional Communication**: Uses HTTP POST for client-to-server and optional SSE streams for server-to-client communication+- **Better Error Handling**: Enhanced error reporting and recovery mechanisms++SHTTP is the recommended transport for HTTP-based MCP servers as it provides better reliability and features compared to the legacy SSE transport.++### Standard Input/Output (stdio)+Stdio transport enables communication through standard input and output streams, making it ideal for local integrations and command-line tools. This transport is used for locally executed MCP servers that run as separate processes.