Model Context Protocol (MCP)

​

Overview

​

Supported MCPs

• Server-Sent Events (SSE)
• Streamable HTTP (SHTTP)
• Standard Input/Output (stdio)

​

How MCP Works

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.

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

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

​

Configuration Options

​

When to Use Direct Stdio

• 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

# 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

[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
    }
]

• 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.