From 1f930c8875122996c37ca7a2545e3202f4f01040 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Sat, 26 Sep 2026 16:30:41 -0500 Subject: [PATCH 1/2] docs(mcp): configure MCP servers in Agent Canvas; move config.toml [mcp] to V0 reference The MCP settings page still said MCP servers can be defined in config.toml [mcp] (sse_servers/shttp_servers/stdio_servers) and used TOML for all examples. Current OpenHands no longer reads that section (removed in OpenHands/OpenHands#14241), and third-party integrations have followed the stale instructions (e.g. hindsight-openhands writes ./config.toml). - Document Customize > MCP Servers > Add custom server with the actual Agent Canvas form fields (Server Type, URL, Authentication, Timeout, Command Arguments, Environment Variables) and Test connection - Point CLI users to ~/.openhands/mcp.json and SDK users to mcp_config - Warn that config.toml [mcp] is ignored; add guidance for tool authors - Replace the OAuth 'Config File' tab with an Agent Canvas tab - Preserve the legacy TOML reference in V0 configuration options Co-authored-by: openhands --- openhands/usage/settings/mcp-settings.mdx | 209 ++++++++---------- .../v0/advanced/V0_configuration-options.mdx | 44 ++++ 2 files changed, 138 insertions(+), 115 deletions(-) diff --git a/openhands/usage/settings/mcp-settings.mdx b/openhands/usage/settings/mcp-settings.mdx index 98f75ba50..69469fc44 100644 --- a/openhands/usage/settings/mcp-settings.mdx +++ b/openhands/usage/settings/mcp-settings.mdx @@ -20,9 +20,9 @@ OpenHands supports the following MCP transport protocols: ## How MCP Works -When OpenHands starts, it: +When a conversation starts, OpenHands: -1. Reads the MCP configuration. +1. Reads the MCP servers you have configured and enabled. 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. @@ -33,75 +33,73 @@ The agent can then use these tools just like any built-in tool. When the agent c 2. The server processes the request and returns a response. 3. 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 -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. +Where you configure MCP servers depends on how you run OpenHands: -### Configuration Options +- **Agent Canvas** (local or connected to OpenHands Cloud): `Customize > MCP Servers`. See [Add a Custom Server](#add-a-custom-server). +- **CLI**: `openhands mcp add`, which writes `~/.openhands/mcp.json`. See [CLI MCP Servers](/openhands/usage/cli/mcp-servers). +- **SDK**: pass `mcp_config` to your agent. See the [SDK MCP Guide](/sdk/guides/mcp). - - - SSE servers are configured using either a string URL or an object with the following properties: + + 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](/openhands/usage/v0/advanced/V0_configuration-options#mcp-configuration). + + +### Add a Custom Server - - `url` (required) - - Type: `str` - - Description: The URL of the SSE server. +To add a server that isn't in the `Marketplace`: - - `api_key` (optional) - - Type: `str` - - Description: API key for authentication. +1. In Agent Canvas, open `Customize > MCP Servers`. +2. Click `Add custom server`. +3. Choose a `Server Type` and fill in the fields for that type (see below). +4. Click `Test connection`. A working server reports how many tools it provides. +5. 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 + + + + 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 `. + - `Header`: Enter custom headers in `Headers`, one `NAME=value` per line (for example, `X-API-Key=value`). + - `OAuth`: See [OAuth Authentication](#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. - - 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. - + + 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](/openhands/usage/settings/mcp-settings#configuration-examples) for + While stdio servers are supported, [we recommend using MCP proxies](#configuration-examples) 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. Accepted characters are letters, digits, underscores (`_`), and hyphens (`-`). For example, `integrations-hub` is a valid name. - - - `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. + - `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. @@ -130,58 +128,33 @@ Direct stdio connections may still be appropriate in these scenarios: 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", + Then add each proxy with `Add custom server`: - # External MCP service with authentication - {url="https://api.example.com/mcp/sse", api_key="your-api-key"} - ] + | 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` | - # 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 - } - ] - ``` + + `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. + This setup is 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" - } - } - ] - ``` + + 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. @@ -193,6 +166,16 @@ Other options include: - **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](/openhands/usage/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](/overview/skills/repo). + ## 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. @@ -217,6 +200,12 @@ On OpenHands Cloud, saving MCP settings keeps the OAuth credential and its token ### Configuration + + 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: @@ -256,16 +245,6 @@ On OpenHands Cloud, saving MCP settings keeps the OAuth credential and its token See the [SDK MCP Guide](/sdk/guides/mcp) for complete examples. - - Add the `auth` field to your server configuration: - - ```toml - [mcp] - shttp_servers = [ - {url = "https://mcp.notion.com/mcp", auth = "oauth"} - ] - ``` - diff --git a/openhands/usage/v0/advanced/V0_configuration-options.mdx b/openhands/usage/v0/advanced/V0_configuration-options.mdx index 3a1eedcb5..6ff0da179 100644 --- a/openhands/usage/v0/advanced/V0_configuration-options.mdx +++ b/openhands/usage/v0/advanced/V0_configuration-options.mdx @@ -440,6 +440,50 @@ All security configuration options can be set as environment variables by prefix - Default: `""` - Description: The security analyzer to use +## MCP Configuration + + + Current OpenHands releases don't read this section. To configure MCP servers today, see + [Model Context Protocol (MCP)](/openhands/usage/settings/mcp-settings). + + +In V0, MCP servers are defined in the `[mcp]` section of the `config.toml` file and merged with servers added in the +Settings UI (`config.toml` takes priority). + +- `sse_servers` + - Type: `list` + - Default: `[]` + - Description: SSE servers, each a URL string or `{url, api_key}`. + +- `shttp_servers` + - Type: `list` + - Default: `[]` + - Description: Streamable HTTP servers, each a URL string or `{url, api_key, timeout}`. `timeout` is in seconds + (default `60`, maximum `3600`) and applies to individual tool calls. + +- `stdio_servers` + - Type: `list` + - Default: `[]` + - Description: Stdio servers, each `{name, command, args, env}`. + +```toml +[mcp] +sse_servers = [ + "http://localhost:8081/sse", + {url="https://api.example.com/mcp/sse", api_key="your-api-key"} +] + +shttp_servers = [ + "https://api.example.com/mcp/shttp", + {url = "https://files.example.com/mcp/shttp", api_key = "your-api-key", timeout = 1800} +] + +stdio_servers = [ + {name="fetch", command="uvx", args=["mcp-server-fetch"]}, + {name="filesystem", command="npx", args=["@modelcontextprotocol/server-filesystem", "/"], env={"DEBUG": "true"}} +] +``` + --- > **Note**: Adjust configurations carefully, especially for memory, security, and network-related settings to ensure optimal performance and security. From 9301ffb12b69cb9dc07aff7e0a445925a0a9ab53 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Sun, 27 Sep 2026 08:55:26 -0500 Subject: [PATCH 2/2] =?UTF-8?q?docs(mcp):=20address=20review=20=E2=80=94?= =?UTF-8?q?=20drop=20V0=20priority=20claim,=20cover=20STDIO=20fields=20for?= =?UTF-8?q?=20integration=20authors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: openhands --- openhands/usage/settings/mcp-settings.mdx | 3 ++- openhands/usage/v0/advanced/V0_configuration-options.mdx | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/openhands/usage/settings/mcp-settings.mdx b/openhands/usage/settings/mcp-settings.mdx index 69469fc44..768795a70 100644 --- a/openhands/usage/settings/mcp-settings.mdx +++ b/openhands/usage/settings/mcp-settings.mdx @@ -170,7 +170,8 @@ Other options include: 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 Agent Canvas, give the `Add custom server` values: `Server Type`, then `URL` and `Authentication` (SSE/SHTTP) + or `Name`, `Command`, `Command Arguments`, and `Environment Variables` (STDIO). - For the CLI, give the `openhands mcp add` command. See [CLI MCP Servers](/openhands/usage/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 diff --git a/openhands/usage/v0/advanced/V0_configuration-options.mdx b/openhands/usage/v0/advanced/V0_configuration-options.mdx index 6ff0da179..c0fb95027 100644 --- a/openhands/usage/v0/advanced/V0_configuration-options.mdx +++ b/openhands/usage/v0/advanced/V0_configuration-options.mdx @@ -448,7 +448,7 @@ All security configuration options can be set as environment variables by prefix In V0, MCP servers are defined in the `[mcp]` section of the `config.toml` file and merged with servers added in the -Settings UI (`config.toml` takes priority). +Settings UI. - `sse_servers` - Type: `list`