OpenHands/docs/usage/mcp.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).


<Note>
MCP is currently not available on OpenHands Cloud. This feature is only available when running OpenHands locally.
</Note>

### 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 through the Settings under the `MCP` tab.
* The `config.toml` file under the `[mcp]` section if not using the UI.

### Configuration Examples

#### Recommended: Using Proxy Servers (SSE/HTTP)

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"}
]
```



#### Alternative: Direct Stdio Servers (Not Recommended for Production)

```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"
        }
    }
]
```

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

### Stdio Servers

**Note**: While stdio servers are supported, we recommend using MCP proxies (see above) 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

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

### Troubleshooting MCP Connections

#### Common Issues with Stdio Servers
- **Process crashes**: Stdio processes may crash without proper error handling
- **Deadlocks**: Stdio communication can deadlock under high load
- **Resource leaks**: Zombie processes if not properly managed
- **Debugging difficulty**: Hard to inspect stdio communication

#### Benefits of Using Proxies
- **HTTP status codes**: Clear error reporting via standard HTTP responses
- **Request logging**: Easy to log and monitor HTTP requests
- **Load balancing**: Can distribute requests across multiple server instances
- **Health checks**: HTTP endpoints can provide health status
- **CORS support**: Better integration with web-based tools

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