Model Context Protocol (MCP)

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 a conversation starts, OpenHands:

Reads the MCP servers you have configured and enabled.
Connects to any configured SSE and SHTTP servers.
Starts any configured stdio servers.
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:

OpenHands routes the call to the appropriate MCP server.
The server processes the request and returns a response.
OpenHands converts the response to an observation and presents it to the agent.

Servers you add or change apply to new conversations, not to conversations that are already running.

Configuration

Where you configure MCP servers depends on how you run OpenHands:

Agent Canvas (local or connected to OpenHands Cloud): Customize > MCP Servers. See Add a Custom Server.
CLI: openhands mcp add, which writes ~/.openhands/mcp.json. See CLI MCP Servers.
SDK: pass mcp_config to your agent. See the SDK MCP Guide.

Current OpenHands releases don’t read MCP servers from a config.toml [mcp] section (sse_servers, shttp_servers, stdio_servers). That format belongs to legacy OpenHands (V0). If you still have one, add those servers again using one of the options above. The legacy format is kept for reference in the V0 configuration options.

Add a Custom Server

To add a server that isn’t in the Marketplace:

In Agent Canvas, open Customize > MCP Servers.
Click Add custom server.
Choose a Server Type and fill in the fields for that type (see below).
Click Test connection. A working server reports how many tools it provides.
Save the server. New conversations can use its tools.

On a local backend, Agent Canvas saves MCP servers in its settings store (by default ~/.openhands/settings.json) with credentials encrypted. Manage servers from Customize > MCP Servers rather than editing that file. There is no per-project MCP configuration file.

Server Fields

SHTTP
SSE
STDIO

Streamable HTTP is the recommended transport for remote servers.

Server name: A name for the server.
URL (required): The server’s endpoint, starting with http:// or https://.
Authentication: How OpenHands authenticates to the server.
- None: No credentials.
- Bearer token: Enter the token in API Key. OpenHands sends Authorization: Bearer <token>.
- Header: Enter custom headers in Headers, one NAME=value per line (for example, X-API-Key=value).
- OAuth: See OAuth Authentication.
Timeout (seconds) (optional): How long to wait for the server before timing out. Use a longer timeout for servers whose tools run heavy operations such as large file processing.

Server-Sent Events is an older transport for remote servers. Use it only if the server doesn’t support SHTTP.

Server name: A name for the server.
URL (required): The server’s SSE endpoint.
Authentication: The same options as SHTTP.

While stdio servers are supported, we recommend using MCP proxies for better reliability and performance.

Name (required): A unique name for the server. Accepted characters are letters, digits, underscores (_), and hyphens (-). For example, integrations-hub is a valid name.
Command (required): The command to run the server, such as npx or uvx.
Command Arguments (optional): One argument per line, passed to the command in order.
Environment Variables (optional): One KEY=value per line, 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

Proxy Servers (SSE/HTTP) - Recommended
Direct Stdio Servers

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 add each proxy with Add custom server:

Field	Filesystem proxy	Fetch proxy
`Server Type`	`SSE`	`SSE`
`Server name`	`filesystem`	`fetch`
`URL`	`http://localhost:8080/sse`	`http://localhost:8081/sse`
`Authentication`	`None`	`None`

localhost works when the agent server runs on the same machine as the proxy. If your conversations run in Docker or a remote sandbox, use an address that environment can reach.

This setup is not recommended for production.

Add the server with Add custom server:

Field	Value
`Server Type`	`STDIO`
`Name`	`fetch`
`Command`	`uvx`
`Command Arguments`	`mcp-server-fetch`

For production use, we recommend using proxy tools like SuperGateway.

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.

Documenting an Integration for OpenHands

If you maintain an MCP server and want to publish setup steps for OpenHands users:

For Agent Canvas, give the Add custom server values: Server Type, URL, and Authentication.
For the CLI, give the openhands mcp add command. See CLI MCP Servers.
Don’t write a config.toml [mcp] section. Current OpenHands releases ignore it.
To give the agent standing instructions (for example, when to call your tools), add them to the repository’s AGENTS.md. OpenHands loads it into the agent’s context. See Repository Skills.

Manage Installed Servers

In Agent Canvas, open Customize > MCP Servers to manage installed MCP servers. Use the control on an installed server card to disable it without deleting its configuration or saved credentials. Disabled servers are unavailable to new conversations until you enable them again. Adding, editing, renaming, or deleting one server does not remove saved credentials for your other servers. Use the editor’s delete action only when you want to remove that server configuration. Editing a disabled server does not enable it.

OAuth Authentication

Some MCP servers (like Notion MCP) require OAuth authentication instead of API keys. OpenHands supports OAuth-based MCP servers through the FastMCP library.

How OAuth Works

When you configure an OAuth-enabled MCP server:

First connection: When the agent first attempts to use tools from an OAuth-protected MCP server, OpenHands initiates the OAuth flow
Browser authentication: A browser window opens automatically for you to authorize access
Token storage: After authorization, tokens are securely stored locally in ~/.fastmcp/oauth-mcp-client-cache/
Automatic refresh: FastMCP automatically refreshes tokens as needed

On OpenHands Cloud, saving MCP settings keeps the OAuth credential and its token state instead of flattening it into a request header, so installed servers keep their authorization across saves. When a server already holds working tokens, OpenHands probes them and skips the consent prompt; the browser window only opens when authorization is actually required.

Configuration

Agent Canvas
CLI
SDK

Servers in the Marketplace that use OAuth, such as Notion, start the authorization flow when you install them.For a custom server, click Add custom server, choose SHTTP or SSE, and set Authentication to OAuth. Fill in OAuth client ID, OAuth client secret, and OAuth scopes if the server requires them.

Use the --auth oauth flag when adding an MCP server:

openhands mcp add notion --transport http \
  --auth oauth \
  https://mcp.notion.com/mcp

This creates a configuration in ~/.openhands/mcp.json:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "transport": "http",
      "auth": "oauth"
    }
  }
}

Configure OAuth in your mcp_config:

mcp_config = {
    "mcpServers": {
        "notion": {
            "url": "https://mcp.notion.com/mcp",
            "auth": "oauth"
        }
    }
}
agent = Agent(llm=llm, tools=tools, mcp_config=mcp_config)

See the SDK MCP Guide for complete examples.

OAuth MCP servers require user interaction for the initial authentication. This means they may not be suitable for fully automated/headless workflows. For automation, consider using API key-based authentication where available.

Get Started

Essential Guidelines

Use Cases

Product Guides

Additional Documentation

Deprecated Projects

OpenHands Community

Model Context Protocol (MCP)

Overview

Supported MCPs

How MCP Works

Configuration

Add a Custom Server

Server Fields

When to Use Direct Stdio

Configuration Examples

Documenting an Integration for OpenHands

Manage Installed Servers

OAuth Authentication

How OAuth Works

Configuration

​Overview

​Supported MCPs

​How MCP Works

​Configuration

​Add a Custom Server

​Server Fields

​When to Use Direct Stdio

​Configuration Examples

​Documenting an Integration for OpenHands

​Manage Installed Servers

​OAuth Authentication

​How OAuth Works

​Configuration

Overview

Supported MCPs

How MCP Works

Configuration

Add a Custom Server

Server Fields

When to Use Direct Stdio

Configuration Examples

Documenting an Integration for OpenHands

Manage Installed Servers

OAuth Authentication

How OAuth Works

Configuration