feat: add canonical MCP settings operations

[neubig]

As part of this stack of 3 PRs, I have verified that adding two consecutive MCPs works:

1. software-agent-sdk #4294 — Add MCP settings CRUD endpoints
2. typescript-client OpenHands/typescript-client#302 — Add canonical MCP settings operations
3. OpenHands #16144 — Preserve MCP credentials during Canvas mutations

• A human has tested these changes.

---

Why

MCP settings callers currently have to reconstruct and resend the full catalog.
That makes a redacted settings response a dangerous mutation base: editing one
server can overwrite or remove an untouched sibling's credential.

Fixes OpenHands/software-agent-sdk#4753
Linear: OSS-6123

Depends on OpenHands/software-agent-sdk#4294.

Summary

• Export generated-contract-derived, name-keyed MCPConfig and strongly typed
  MCP transport, auth, OAuth, test, tool-call, response, and sparse patch types.
• Add createMcpServer(), patchMcpServer(), and deleteMcpServer() helpers
  over the dedicated Agent Server POST, PATCH, and DELETE
/api/settings/mcp/{settings_key} endpoints.
• Send only the named server or sparse patch body. Each operation issues one
  request and never reconstructs the stored MCP catalog.
• Keep the checked-in generated schema pinned to the released Agent Server
  version. After SDK #4294 is released, the normal pinned generator update will
  add these three operation definitions so their aliases can be checked
  directly before this PR leaves draft.

Issue Number

OpenHands/software-agent-sdk#4753 / OSS-6123

How to Test

• npm run build
• npm run lint — 0 errors; 17 pre-existing warnings
• npm run format:check
• env -u AGENT_SERVER_URL -u OPENHANDS_AGENT_SERVER_URL npm run test:coverage
  — 18 suites and 301 tests passed.

The stateful client test verifies create collision handling, missing-key patch
and delete handling, sparse update, auth replacement, explicit auth clearing,
and sibling preservation. It asserts the exact endpoint, method, direct body,
and one request per operation.

The exact packed client was installed into Agent Canvas and tested with the
SDK #4294 checkout in a full isolated stack. The browser regression passed:
a stored GitHub credential survived creating, editing, and deleting a sibling
MCP, with exactly one POST, PATCH, and DELETE request. HOME, XDG directories,
Canvas state, OpenHands settings, uv/npm caches, temp files, runtime files,
workspace, and service ports were isolated under one temporary directory. The
real ~/.openhands settings, secrets, and Canvas key files were unchanged.

Video/Screenshots

Not applicable: this is a client contract and mutation API change with no UI
change.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

This branch is based directly on main, including the v1.38 generated Agent
Server contract from #307. It deliberately does not generate against a moving
branch or PR image: normal client CI remains pinned to the exact released
Agent Server version.

[github-actions]

Endpoint audit

⚠️ 7 actionable Agent Server contract divergence(s) · report-only

Contract: pinned release artifact

Category	Count
Actionable client-only calls	0
Actionable server-only operations	7
Documented non-divergences	12
Agent Server contract operations	114
Audited handwritten client endpoints	115

Actionable client-only calls (0)

none

Actionable server-only operations (7)

• GET /api/conversations/{}/events
• GET /api/file/archive
• GET /api/git/commits
• GET /api/git/commits/{}/changes
• GET /api/init
• POST /api/conversations/{}/load_plugin
• POST /api/init

Documented non-divergences (12)

Client calls intentionally absent from the filtered contract (10)

• GET /
• GET /alive
• GET /health
• GET /ready
• GET /server_info

Reason: Operational Agent Server endpoints intentionally excluded from the filtered public release artifact.
Owner: OpenHands runtime maintainers

• DELETE /api/meta-profiles/{}
• GET /api/meta-profiles
• GET /api/meta-profiles/{}
• POST /api/meta-profiles/{}
• POST /api/meta-profiles/{}/activate

Reason: Client-ahead API stacked on the pending Agent Server meta-profiles implementation.
Owner: OpenHands SDK maintainers
Tracking: OpenHands/software-agent-sdk#3744

Server operations covered by an exposed browser URL (2)

• GET /api/conversations/{}/workspace
• GET /api/conversations/{}/workspace/{}

Reason: RemoteWorkspace.startWorkspaceSession exposes these authenticated URLs for browser iframe and file requests; they are not HttpClient method calls.
Owner: OpenHands TypeScript client maintainers

[neubig]

Closing this PR in favor of implementing the operations at the Agent Server boundary first. OpenHands/software-agent-sdk#4294 adds explicit create, sparse update, and delete MCP settings operations to the authoritative OpenAPI contract, including atomic collision/not-found handling under the settings-store lock.

Once that change is merged and released, the normal pinned Agent Server bump will generate the exact TypeScript operation types. The follow-up client change can then be limited to thin runtime wrappers over those generated operations; it will not recreate MCP models or construct the generic PATCH /api/settings payload. Tracking remains in OpenHands/software-agent-sdk#4753.

[openhands-release-bot]

🚀 Released in v1.36.0.