OpenHands/docs/usage/settings/mcp-settings.mdx

---
title: Model Context Protocol (MCP)
description: This page outlines how to configure and use the Model Context Protocol (MCP) in OpenHands, allowing you
  to extend the agent's capabilities with custom tools.
---

## 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](https://modelcontextprotocol.io).

## Supported MCPs

OpenHands supports the following MCP transport protocols:

* [Server-Sent Events (SSE)](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse)
* [Streamable HTTP (SHTTP)](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http)
* [Standard Input/Output (stdio)](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)

## 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

<Tabs>
  <Tab title="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.
  </Tab>
  <Tab title="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.
    <Note>
      This timeout only applies to individual tool calls, not server connection establishment.
    </Note>
  </Tab>
  <Tab title="Stdio Servers">
    <Note>
      While stdio servers are supported, [we recommend using MCP proxies](/usage/settings/mcp-settings#configuration-examples) for
      better reliability and performance.
    </Note>

    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.
  </Tab>
</Tabs>

#### 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

<Tabs>
  <Tab title="Proxy Servers (SSE/HTTP) - Recommended">
    For stdio-based MCP servers, we recommend using MCP proxy tools like
    [`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
    [SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to
    HTTP/SSE endpoints.

    Start the proxy servers separately:
    ```bash
    # 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:

    ```toml
    [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
        }
    ]
    ```
  </Tab>
  <Tab title="Direct Stdio Servers">
    <Note>
      This setup is not Recommended for production.
    </Note>
    ```toml
    [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.
  </Tab>
</Tabs>

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.