Back Home

GitHub Repo

OpenHands 1.22.0 fixes cloud MCP configuration overwrites, adds remote connection checks

The update prevents other saved configurations from being inadvertently removed when a single MCP server is added or edited. Remote connection checks now use the cloud backend, but concurrent writes and end-to-end tool execution still need validation.

Slaunger · CC BY-SA 3.0 · Image source
zh-Hant

OpenHands released version 1.22.0 on September 22, fixing an issue where adding or editing an MCP server in Agent Canvas could remove other configurations when connected to the cloud backend. The release also adds remote MCP connection checks. Both changes directly affect which tools an agent can access after startup. [Release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.22.0)

According to the official documentation, OpenHands reads the configuration, connects to remote servers or launches stdio processes, and then registers tools with the agent. Missing configurations can therefore leave tools unavailable in a conversation, rather than merely remove a card from the management page. [MCP documentation](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)

The overwrite issue stemmed from different frontend and backend interpretations of update payloads. Canvas previously sent only the entry being modified, while the cloud endpoint treated a map without null deletion markers as a replacement for the entire server catalog. It performed a partial merge only when deletion markers were present. As a result, adding server B could also delete an already saved server A. [Fix details](https://github.com/OpenHands/OpenHands/pull/17467)

Before adding or editing an entry, the new version fetches the existing catalog, merges the changes, and sends back the complete configuration, allowing the backend to restore masked credentials for unchanged entries. If the read fails, the write is aborted. When clearing authentication or switching authentication methods, it explicitly sends `auth: null` to prevent old credentials from being restored. This path adds one configuration read request, and simultaneous edits in two tabs still follow last-write-wins behavior. [Fix details](https://github.com/OpenHands/OpenHands/pull/17467)

Connection checks now go through `POST /api/v1/mcp/test` on the cloud application server and can display tool counts or connection, timeout, and credential errors. This feature targets remote servers; stdio services launched inside the sandbox still do not support the same test assessment. Deployments also need a backend implementation of the corresponding endpoint. [Connection test changes](https://github.com/OpenHands/OpenHands/pull/17276)

Connection results in the management interface remain diagnostic signals. The official architecture treats tool discovery, schema conversion, registration, and execution as separate steps. Consequently, being able to list tools does not establish that every operation can complete. Validation should also cover whether returned data can be converted into observations the agent can read. [SDK architecture](https://docs.openhands.dev/sdk/arch/mcp)

The author of the configuration fix reported that 70 tests across seven files passed and verified server-side credential restoration, but explicitly noted that the full cloud workflow had not yet been tested end to end. After upgrading, engineering teams should add two services in sequence, reload the configuration, and start a new conversation to verify that tools from both services can be invoked. Credentials should also be rechecked when changing a service URL, because the existing restoration logic matches credentials by endpoint identity. [Validation records and limitations](https://github.com/OpenHands/OpenHands/pull/17467)

Sources

  1. OpenHands v1.22.0 發行公告
  2. 修補雲端儲存時遺失其他 MCP 伺服器設定
  3. 透過應用伺服器測試雲端後端的遠端 MCP 服務
  4. OpenHands MCP 設定文件
  5. OpenHands SDK MCP 整合架構