feat(mcp): refresh tools for active conversations

[Shimada666]

HUMAN:
We expose backend-owned MCP tools to OpenHands App Server running in E2B. As these tools may change between releases, existing conversations need a lightweight way to refresh their tool definitions without being forked or recreated.

---

AGENT:

Why

notifications/tools/list_changed can reconcile a live MCP connection, but it cannot cross an MCP server deployment that terminates the old process. An active conversation therefore needs an explicit way to reconnect and replace its MCP tool snapshot without rebuilding the conversation or losing its history and workspace.

Other agent runtimes expose an explicit lifecycle action for the same operational need, although their APIs differ:

• Codex App Server provides config/mcpServer/reload, which reloads MCP configuration and queues a refresh for every loaded thread on its next active turn; its implementation preserves the loaded threads while refreshing their MCP runtime.
• OpenCode supports dynamically adding a named MCP server. Adding the same name installs the new client and tool definitions, then closes the previous client; live tools/list_changed notifications also replace its cached tool definitions.

This PR adds the narrow equivalent OpenHands is missing: refresh the MCP runtime owned by an existing conversation while preserving the conversation itself.

Summary

• Add Conversation.refresh_mcp_tools() for local and remote conversations, with an Agent Server REST action.
• Reconnect each configured MCP client and reuse the existing authoritative add/update/remove reconciliation from fix(mcp): reconcile live agent tool snapshots #4367.
• Track MCP clients even when their initial tool list is empty, so a later deployment can add tools and cleanup remains complete.

Issue Number

N/A

How to Test

The real deployment test runs in both stateful and stateless HTTP modes. It starts FastMCP in a separate process with old_tool and changing(old: str), terminates it, starts a new process on the same URL with new_tool and changing(new: int), then refreshes the same LocalConversation. It verifies:

• old_tool is removed and new_tool is added.
• changing receives the new description and input schema.
• Conversation ID, event history, and workspace are unchanged.
• The next real LLM completion receives exactly changing and new_tool.

Commands and results:

uv run pytest -q tests/sdk/conversation/test_local_conversation_mcp.py -k refresh_reconnects_after_mcp_deployment -s
2 passed, 4 deselected

uv run pytest -q tests/sdk/mcp
129 passed

uv run pytest -q tests/agent_server/test_conversation_router.py tests/agent_server/test_event_service.py
201 passed

uv run pytest -q tests/sdk/conversation/test_local_conversation_mcp.py tests/sdk/mcp/test_mcp_tool_list_changed.py tests/sdk/conversation/test_local_conversation_plugins.py tests/cross/test_remote_conversation_live_server.py
75 passed, 1 skipped, 13 warnings

git diff --name-only -z origin/main | xargs -0 uv run pre-commit run --files
All hooks passed, including Ruff, pyright, import dependency rules, and tool registration checks.

Video/Screenshots

N/A — SDK and Agent Server API change with no visual surface.

Type

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

Notes

• Call the method between conversation runs. This change intentionally does not add polling or deployment detection.
• The branch is based directly on current main and does not depend on open PR fix(mcp): close reconciliation gaps left by #4367 #4369; it only reuses reconciliation already merged in fix(mcp): reconcile live agent tool snapshots #4367.
• Matching documentation PR: docs(sdk): document MCP tool refresh docs#694.

[all-hands-bot]

👋 This PR needs a couple of things fixed before OpenHands can review it:

• the PR description's HUMAN: section needs at least 20 characters describing what you tested, not just the template placeholder

Push an update once this is addressed and this check re-runs automatically.

This is an automated check - no AI was used to generate this comment.

[all-hands-bot]

👋 This PR needs a couple of things fixed before OpenHands can review it:

• the PR description's HUMAN: section needs at least 20 characters describing what you tested, not just the template placeholder

Push an update once this is addressed and this check re-runs automatically.

This is an automated check - no AI was used to generate this comment.

[all-hands-bot]

🚦 CI is currently failing on this PR's latest commit.

Please fix the failing checks before OpenHands reviews it - this is re-checked automatically once you push a new commit. (A maintainer can also request @all-hands-bot as a reviewer to have it reviewed regardless of CI status.)

This is an automated check - no AI was used to generate this comment.

[Shimada666]

Hi @neubig and @VascoSch92 — thank you both for the work and review around #4367 and #4369.

This PR follows the same line of work. #4367 handles add/update/remove reconciliation while an MCP connection remains alive, and #4369 hardens that path. This PR covers a separate deployment boundary: when the MCP server process is replaced, an existing conversation can explicitly reconnect and refresh its tool snapshot. It reuses the reconciliation path introduced in #4367 and preserves the conversation rather than forking or recreating it.

CI is green now. When you have a chance, I’d really appreciate your thoughts on whether this is the right lifecycle and API boundary. Thank you!