​
Overview

Model Context Protocol (MCP) is a mechanism that allows OpenHands to communicate with external tool servers. These servers can provide additional functionality to the agent, such as specialized data processing, external API access, or custom tools. MCP is based on the open standard defined at modelcontextprotocol.io.

​
Supported MCPs

OpenHands supports the following MCP transport protocols:

​
How MCP Works

When OpenHands starts, it:
  1. Reads the MCP configuration.
  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.
The agent can then use these tools just like any built-in tool. When the agent calls an MCP tool:
  1. 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.

​
Configuration

MCP configuration can be defined in:
  • The OpenHands UI in the Settings > MCP page.
  • The config.toml file under the [mcp] section if not using the UI.

​
Configuration Options

​
SSE Servers

SSE servers are configured using either a string URL or an object with the following properties:
  • url (required)
    • 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.
  • timeout (optional)
    • Type: int
    • Default: 60
    • Range: 1-3600 seconds (1 hour maximum)
    • Description: Timeout in seconds for tool execution. This prevents tool calls from hanging indefinitely.
    • Use Cases:
      • Short timeout (1-30s): For lightweight operations like status checks or simple queries.
      • Medium timeout (30-300s): For standard processing tasks like data analysis or API calls.
      • Long timeout (300-3600s): For heavy operations like file processing, complex calculations, or batch operations.
    This timeout only applies to individual tool calls, not server connection establishment.

​
Stdio Servers

While stdio servers are supported, we recommend using MCP proxies for better reliability and performance.
Stdio servers are configured using an object with the following properties:
  • name (required)
    • Type: str
    • Description: A unique name for the server.
  • command (required)
    • Type: str
    • Description: The command to run the server.
  • args (optional)
    • Type: list of str
    • Default: []
    • Description: Command-line arguments to pass to the server.
  • env (optional)
    • Type: dict of str to str
    • Default: {}
    • Description: Environment variables to set for the server process.
When to Use Direct Stdio
Direct stdio connections may still be appropriate in these scenarios:
  • Development and testing: Quick prototyping of MCP servers.
  • Simple, single-use tools: Tools that don’t require high reliability or concurrent access.
  • Local-only environments: When you don’t want to manage additional proxy processes.

​
Configuration Examples

​
Recommended: Using Proxy Servers (SSE/HTTP)

For stdio-based MCP servers, we recommend using MCP proxy tools like supergateway instead of direct stdio connections. SuperGateway is a popular MCP proxy that converts stdio MCP servers to HTTP/SSE endpoints. Start the proxy servers separately: 
# Terminal 1: Filesystem server proxy
supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080

# Terminal 2: Fetch server proxy
supergateway --stdio "uvx mcp-server-fetch" --port 8081
Then configure OpenHands to use the HTTP endpoint: 
[mcp]
# SSE Servers - Recommended approach using proxy tools
sse_servers = [
    # Basic SSE server with just a URL
    "http://example.com:8080/mcp",

    # SuperGateway proxy for fetch server
    "http://localhost:8081/sse",

    # External MCP service with authentication
    {url="https://api.example.com/mcp/sse", api_key="your-api-key"}
]

# SHTTP Servers - Modern streamable HTTP transport (recommended)
shttp_servers = [
    # Basic SHTTP server with default 60s timeout
    "https://api.example.com/mcp/shttp",

    # Server with custom timeout for heavy operations
    {
        url = "https://files.example.com/mcp/shttp",
        api_key = "your-api-key",
        timeout = 1800  # 30 minutes for large file processing
    }
]

[mcp]
# Direct stdio servers - use only for development/testing
stdio_servers = [
    # Basic stdio server
    {name="fetch", command="uvx", args=["mcp-server-fetch"]},

    # Stdio server with environment variables
    {
        name="filesystem",
        command="npx",
        args=["@modelcontextprotocol/server-filesystem", "/"],
        env={
            "DEBUG": "true"
        }
    }
]
For production use, we recommend using proxy tools like SuperGateway.

​
Other Proxy Tools

Other options include:
  • Custom FastAPI/Express servers: Build your own HTTP wrapper around stdio MCP servers.
  • Docker-based proxies: Containerized solutions for better isolation.
  • Cloud-hosted MCP services: Third-party services that provide MCP endpoints.