docs(mcp): configure MCP servers in Agent Canvas; move config.toml [mcp] to V0 reference

openhands/usage/settings/mcp-settings.mdx

@@ -10,7 +10,7 @@
 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:
 
@@ -20,9 +20,9 @@
 
 ## 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 @@
 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).
 
-<Tabs>
-  <Tab title="SSE Servers">
-    SSE servers are configured using either a string URL or an object with the following properties:
+<Warning>
+  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).
+</Warning>
+
+### 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.
+
+<Note>
+  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.
+</Note>
+
+### Server Fields
+
+<Tabs>
+  <Tab title="SHTTP">
+    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](#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.
   </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 title="SSE">
+    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.
   </Tab>
-  <Tab title="Stdio Servers">
+  <Tab title="STDIO">
     <Note>
-      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.
     </Note>
 
-    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.
   </Tab>
 </Tabs>
 
@@ -130,58 +128,33 @@
     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
-        }
-    ]
-    ```
+    <Note>
+      `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.
+    </Note>
   </Tab>
   <Tab title="Direct Stdio Servers">
     <Note>
-      This setup is not Recommended for production.
+      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"
-            }
-        }
-    ]
-    ```
+
+    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.
   </Tab>
@@ -193,6 +166,17 @@
 - **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`, 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
+  `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 +201,12 @@
 ### Configuration
 
 <Tabs>
+  <Tab title="Agent Canvas">
+    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.
+  </Tab>
   <Tab title="CLI">
     Use the `--auth oauth` flag when adding an MCP server:
 
@@ -256,16 +246,6 @@
 
     See the [SDK MCP Guide](/sdk/guides/mcp) for complete examples.
   </Tab>
-  <Tab title="Config File">
-    Add the `auth` field to your server configuration:
-
-    ```toml
-    [mcp]
-    shttp_servers = [
-        {url = "https://mcp.notion.com/mcp", auth = "oauth"}
-    ]
-    ```
-  </Tab>
 </Tabs>
 
 <Note>

openhands/usage/v0/advanced/V0_configuration-options.mdx

@@ -259,7 +259,7 @@
 - `retry_multiplier`
   - Type: `float`
   - Default: `2.0`
   - Description: Multiplier for exponential backoff calculation
 
 ### Advanced Options
 - `drop_params`
@@ -338,7 +338,7 @@
   - Default: `true`
   - Description: Whether history should be truncated to continue the session when hitting LLM context length limit
 
 ### Skills (formerly Microagents) Usage
 - `enable_prompt_extensions`
   - Type: `bool`
   - Default: `true`
@@ -440,6 +440,50 @@
   - Default: `""`
   - Description: The security analyzer to use
 
+## MCP Configuration
+
+<Note>
+  Current OpenHands releases don't read this section. To configure MCP servers today, see
+  [Model Context Protocol (MCP)](/openhands/usage/settings/mcp-settings).
+</Note>
+
+In V0, MCP servers are defined in the `[mcp]` section of the `config.toml` file and merged with servers added in the
+Settings UI.
+
+- `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.