Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: MCP settings wont update (#14492)

HeyItsChloeb57250551906
diff --git a/enterprise/storage/org_member_store.py b/enterprise/storage/org_member_store.py
index 4b5af1768e..86afe640fd 100644
--- a/enterprise/storage/org_member_store.py
+++ b/enterprise/storage/org_member_store.py
@@ -15,7 +15,10 @@ from storage.user import User
from storage.user_settings import UserSettings
from openhands.app_server.settings.settings_models import Settings
-from openhands.app_server.utils.jsonpatch_compat import deep_merge
+from openhands.app_server.utils.jsonpatch_compat import (
+ deep_merge,
+ deep_merge_with_wholesale_keys,
+)
class OrgMemberStore:
@@ -267,7 +270,7 @@ class OrgMemberStore:
org_member.llm_api_key = raw_key
if agent_settings_diff is not None:
- org_member.agent_settings_diff = deep_merge(
+ org_member.agent_settings_diff = deep_merge_with_wholesale_keys(
org_member.agent_settings_diff,
agent_settings_diff,
)
diff --git a/enterprise/storage/saas_settings_store.py b/enterprise/storage/saas_settings_store.py
index 9d1b27b2ad..f72b528bf2 100644
--- a/enterprise/storage/saas_settings_store.py
+++ b/enterprise/storage/saas_settings_store.py
@@ -24,7 +24,10 @@ from storage.user_store import UserStore
from openhands.app_server.settings.settings_models import Settings
from openhands.app_server.settings.settings_store import SettingsStore
-from openhands.app_server.utils.jsonpatch_compat import deep_merge
+from openhands.app_server.utils.jsonpatch_compat import (
+ deep_merge,
+ deep_merge_with_wholesale_keys,
+)
from openhands.app_server.utils.llm import is_openhands_model
@@ -240,7 +243,9 @@ class SaasSettingsStore(SettingsStore):
)
effective_agent_settings_diff = self._get_persisted_agent_settings(item)
- org.agent_settings = deep_merge(
+
+ # Single assignment so SQLAlchemy tracks the change
+ org.agent_settings = deep_merge_with_wholesale_keys(
OrgStore.get_agent_settings_from_org(org).model_dump(mode='json'),
effective_agent_settings_diff,
)
diff --git a/enterprise/tests/unit/test_org_member_store.py b/enterprise/tests/unit/test_org_member_store.py
index b8efeb06d2..27751b4207 100644
--- a/enterprise/tests/unit/test_org_member_store.py
+++ b/enterprise/tests/unit/test_org_member_store.py
@@ -1155,3 +1155,767 @@ async def test_update_all_members_settings_async_with_empty_settings(
assert member.agent_settings_diff['llm']['model'] == 'original-model'
# Original key should still be there (encrypted)
assert member._llm_api_key is not None
+
+
+async def test_update_all_members_settings_async_replaces_mcp_config(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing mcp_config in agent_settings_diff
+ WHEN: update_all_members_settings_async is called with fewer MCP servers
+ THEN: mcp_config should be replaced (not merged), so deleted servers stay deleted
+
+ This tests the fix for APP-1862: MCP server settings cannot be updated
+ or deleted because deep_merge was resurrecting deleted servers.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has 3 MCP servers
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ 'server2': {'url': 'https://server2.com', 'transport': 'sse'},
+ 'server3': {'url': 'https://server3.com', 'transport': 'sse'},
+ },
+ },
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update with only 2 servers (delete server3)
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ 'server2': {'url': 'https://server2.com', 'transport': 'sse'},
+ # server3 is deleted
+ },
+ },
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - Only 2 servers should remain, server3 should NOT be resurrected
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ mcp_servers = member.agent_settings_diff.get('mcp_config', {}).get(
+ 'mcpServers', {}
+ )
+ assert len(mcp_servers) == 2, f'Expected 2 servers, got {len(mcp_servers)}'
+ assert 'server1' in mcp_servers
+ assert 'server2' in mcp_servers
+ assert (
+ 'server3' not in mcp_servers
+ ), 'Deleted server was resurrected by deep_merge'
+
+
+async def test_update_all_members_settings_async_replaces_acp_env(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing acp_env in agent_settings_diff
+ WHEN: update_all_members_settings_async is called with fewer env vars
+ THEN: acp_env should be replaced (not merged), so deleted vars stay deleted
+
+ acp_env has the same replacement semantics as mcp_config.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has 3 env vars
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'acp_env': {
+ 'VAR1': 'value1',
+ 'VAR2': 'value2',
+ 'VAR3': 'value3',
+ },
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update with only 2 vars (delete VAR3)
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'acp_env': {
+ 'VAR1': 'value1',
+ 'VAR2': 'value2',
+ # VAR3 is deleted
+ },
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - Only 2 vars should remain, VAR3 should NOT be resurrected
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ acp_env = member.agent_settings_diff.get('acp_env', {})
+ assert len(acp_env) == 2, f'Expected 2 vars, got {len(acp_env)}'
+ assert 'VAR1' in acp_env
+ assert 'VAR2' in acp_env
+ assert 'VAR3' not in acp_env, 'Deleted var was resurrected by deep_merge'
+
+
+async def test_update_all_members_settings_async_mcp_config_not_in_payload(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing mcp_config
+ WHEN: update_all_members_settings_async is called WITHOUT mcp_config in payload
+ THEN: mcp_config should remain unchanged (not be cleared)
+
+ This ensures we only replace mcp_config when it's explicitly in the update.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has MCP servers
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ },
+ },
+ 'llm': {'model': 'old-model'},
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update only llm settings, NOT mcp_config
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'llm': {'model': 'new-model'},
+ # mcp_config is NOT in the payload
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - mcp_config should still exist with server1
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ # LLM should be updated
+ assert member.agent_settings_diff['llm']['model'] == 'new-model'
+ # mcp_config should be unchanged
+ mcp_config = member.agent_settings_diff.get('mcp_config', {})
+ assert 'server1' in mcp_config.get('mcpServers', {})
+
+
+async def test_update_all_members_settings_async_empty_mcp_config(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing mcp_config
+ WHEN: update_all_members_settings_async is called with empty mcp_config
+ THEN: mcp_config should be cleared (all servers deleted)
+
+ This tests the case where user deletes ALL servers.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has MCP servers
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ 'server2': {'url': 'https://server2.com', 'transport': 'sse'},
+ },
+ },
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update with empty mcp_config (delete all servers)
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {}, # Empty - all servers deleted
+ },
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - mcp_config should be empty
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ mcp_config = member.agent_settings_diff.get('mcp_config', {})
+ mcp_servers = mcp_config.get('mcpServers', {})
+ assert len(mcp_servers) == 0, f'Expected 0 servers, got {len(mcp_servers)}'
+
+
+async def test_update_all_members_settings_async_add_first_mcp_server(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with NO existing mcp_config
+ WHEN: update_all_members_settings_async is called with mcp_config
+ THEN: mcp_config should be added correctly
+
+ This tests adding the first server when none exist.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has NO mcp_config
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'llm': {'model': 'some-model'},
+ # No mcp_config
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Add first MCP server
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {
+ 'first-server': {'url': 'https://first.com', 'transport': 'sse'},
+ },
+ },
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - Server should be added
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ mcp_config = member.agent_settings_diff.get('mcp_config', {})
+ mcp_servers = mcp_config.get('mcpServers', {})
+ assert len(mcp_servers) == 1
+ assert 'first-server' in mcp_servers
+
+
+async def test_update_all_members_settings_async_update_server_url(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing mcp_config
+ WHEN: update_all_members_settings_async is called with updated server URL
+ THEN: The server URL should be updated (not duplicated)
+
+ This tests updating an existing server's properties.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {
+ 'myserver': {
+ 'url': 'https://old-url.com',
+ 'transport': 'sse',
+ },
+ },
+ },
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update server URL
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'mcp_config': {
+ 'mcpServers': {
+ 'myserver': {
+ 'url': 'https://new-url.com',
+ 'transport': 'sse',
+ },
+ },
+ },
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - URL should be updated
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ mcp_config = member.agent_settings_diff.get('mcp_config', {})
+ mcp_servers = mcp_config.get('mcpServers', {})
+ assert len(mcp_servers) == 1
+ assert mcp_servers['myserver']['url'] == 'https://new-url.com'
+
+
+async def test_update_all_members_settings_async_acp_env_not_in_payload(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing acp_env
+ WHEN: update_all_members_settings_async is called WITHOUT acp_env in payload
+ THEN: acp_env should remain unchanged (not be cleared)
+
+ This ensures we only replace acp_env when it's explicitly in the update.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has env vars
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'acp_env': {
+ 'SECRET_KEY': 'secret-value',
+ 'API_TOKEN': 'token-value',
+ },
+ 'llm': {'model': 'old-model'},
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update only llm settings, NOT acp_env
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'llm': {'model': 'new-model'},
+ # acp_env is NOT in the payload
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - acp_env should still exist with both vars
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ # LLM should be updated
+ assert member.agent_settings_diff['llm']['model'] == 'new-model'
+ # acp_env should be unchanged
+ acp_env = member.agent_settings_diff.get('acp_env', {})
+ assert 'SECRET_KEY' in acp_env
+ assert 'API_TOKEN' in acp_env
+
+
+async def test_update_all_members_settings_async_empty_acp_env(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing acp_env
+ WHEN: update_all_members_settings_async is called with empty acp_env
+ THEN: acp_env should be cleared (all vars deleted)
+
+ This tests the case where user deletes ALL env vars.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has env vars
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'acp_env': {
+ 'VAR1': 'value1',
+ 'VAR2': 'value2',
+ 'VAR3': 'value3',
+ },
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update with empty acp_env (delete all vars)
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'acp_env': {}, # Empty - all vars deleted
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - acp_env should be empty
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ acp_env = member.agent_settings_diff.get('acp_env', {})
+ assert len(acp_env) == 0, f'Expected 0 vars, got {len(acp_env)}'
+
+
+async def test_update_all_members_settings_async_add_first_acp_env_var(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with NO existing acp_env
+ WHEN: update_all_members_settings_async is called with acp_env
+ THEN: acp_env should be added correctly
+
+ This tests adding the first env var when none exist.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange - Create org with member that has NO acp_env
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'llm': {'model': 'some-model'},
+ # No acp_env
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Add first env var
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'acp_env': {
+ 'FIRST_VAR': 'first-value',
+ },
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - Env var should be added
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ acp_env = member.agent_settings_diff.get('acp_env', {})
+ assert len(acp_env) == 1
+ assert 'FIRST_VAR' in acp_env
+ assert acp_env['FIRST_VAR'] == 'first-value'
+
+
+async def test_update_all_members_settings_async_update_acp_env_value(
+ async_session_maker,
+):
+ """
+ GIVEN: Organization members with existing acp_env
+ WHEN: update_all_members_settings_async is called with updated var value
+ THEN: The var value should be updated
+
+ This tests updating an existing env var's value.
+ """
+ from server.routes.org_models import OrgMemberSettingsUpdate
+
+ # Arrange
+ async with async_session_maker() as session:
+ org = Org(name='test-org')
+ session.add(org)
+ await session.flush()
+
+ role = Role(name='member', rank=2)
+ session.add(role)
+ await session.flush()
+
+ user = User(id=uuid.uuid4(), current_org_id=org.id, email='[email protected]')
+ session.add(user)
+ await session.flush()
+
+ org_member = OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ agent_settings_diff={
+ 'acp_env': {
+ 'MY_SECRET': 'old-secret-value',
+ },
+ },
+ status='active',
+ )
+ session.add(org_member)
+ await session.commit()
+ org_id = org.id
+
+ # Act - Update env var value
+ member_settings = OrgMemberSettingsUpdate(
+ agent_settings_diff={
+ 'acp_env': {
+ 'MY_SECRET': 'new-secret-value',
+ },
+ },
+ )
+
+ async with async_session_maker() as session:
+ await OrgMemberStore.update_all_members_settings_async(
+ session, org_id, member_settings
+ )
+ await session.commit()
+
+ # Assert - Value should be updated
+ async with async_session_maker() as session:
+ from sqlalchemy import select
+
+ result = await session.execute(
+ select(OrgMember).filter(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+
+ acp_env = member.agent_settings_diff.get('acp_env', {})
+ assert len(acp_env) == 1
+ assert acp_env['MY_SECRET'] == 'new-secret-value'
diff --git a/enterprise/tests/unit/test_saas_settings_store.py b/enterprise/tests/unit/test_saas_settings_store.py
index 711be3398f..d1eeb621c5 100644
--- a/enterprise/tests/unit/test_saas_settings_store.py
+++ b/enterprise/tests/unit/test_saas_settings_store.py
@@ -940,3 +940,112 @@ async def test_llm_profiles_are_encrypted_at_rest(
).scalar_one()
assert user.llm_profiles is not None
assert user.llm_profiles['profiles']['work']['api_key'] == 'super-secret-byok'
+
+
+async def test_store_replaces_mcp_config_on_delete(
+ session_maker, async_session_maker, org_with_multiple_members_fixture
+):
+ """When a server is deleted, mcp_config should be replaced wholesale,
+ not merged (which would resurrect deleted servers).
+
+ This tests the fix for APP-1862: MCP server settings cannot be updated
+ or deleted because deep_merge was resurrecting deleted servers.
+ """
+ from sqlalchemy import select
+ from storage.org import Org
+ from storage.org_member import OrgMember
+
+ fixture = org_with_multiple_members_fixture
+ org_id = fixture['org_id']
+ admin_user_id = str(fixture['admin_user_id'])
+ member1_user_id = str(fixture['member1_user_id'])
+
+ store = SaasSettingsStore(admin_user_id)
+
+ # Step 1: Save 3 MCP servers
+ initial_mcp_config = {
+ 'mcpServers': {
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ 'server2': {'url': 'https://server2.com', 'transport': 'sse'},
+ 'server3': {'url': 'https://server3.com', 'transport': 'sse'},
+ },
+ }
+ initial_settings = DataSettings()
+ initial_settings.update(
+ {
+ 'agent_settings_diff': {
+ 'llm': {
+ 'model': 'test-model',
+ 'base_url': 'http://test-url.com',
+ 'api_key': 'test-key',
+ },
+ 'mcp_config': initial_mcp_config,
+ },
+ }
+ )
+
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await store.store(initial_settings)
+
+ # Verify 3 servers are saved
+ with session_maker() as session:
+ org = session.execute(select(Org).where(Org.id == org_id)).scalars().first()
+ assert org is not None
+ assert len(org.agent_settings.get('mcp_config', {}).get('mcpServers', {})) == 3
+
+ # Step 2: Delete one server (save with only 2 servers)
+ updated_mcp_config = {
+ 'mcpServers': {
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ 'server2': {'url': 'https://server2.com', 'transport': 'sse'},
+ # server3 is deleted
+ },
+ }
+ updated_settings = DataSettings()
+ updated_settings.update(
+ {
+ 'agent_settings_diff': {
+ 'llm': {
+ 'model': 'test-model',
+ 'base_url': 'http://test-url.com',
+ 'api_key': 'test-key',
+ },
+ 'mcp_config': updated_mcp_config,
+ },
+ }
+ )
+
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await store.store(updated_settings)
+
+ # Step 3: Verify only 2 servers remain (server3 was not resurrected)
+ with session_maker() as session:
+ org = session.execute(select(Org).where(Org.id == org_id)).scalars().first()
+ assert org is not None
+ mcp_servers = org.agent_settings.get('mcp_config', {}).get('mcpServers', {})
+ assert (
+ len(mcp_servers) == 2
+ ), f'Expected 2 servers, got {len(mcp_servers)}: {mcp_servers}'
+ assert 'server1' in mcp_servers
+ assert 'server2' in mcp_servers
+ assert (
+ 'server3' not in mcp_servers
+ ), 'Deleted server was resurrected by deep_merge'
+
+ # Also verify member diffs have 2 servers
+ members = {
+ str(m.user_id): m
+ for m in session.execute(
+ select(OrgMember).where(OrgMember.org_id == org_id)
+ )
+ .scalars()
+ .all()
+ }
+ admin_mcp = members[admin_user_id].agent_settings_diff.get('mcp_config', {})
+ assert len(admin_mcp.get('mcpServers', {})) == 2
+ assert 'server3' not in admin_mcp.get('mcpServers', {})
+
+ member1_mcp = members[member1_user_id].agent_settings_diff.get('mcp_config', {})
+ assert len(member1_mcp.get('mcpServers', {})) == 2
+ assert 'server3' not in member1_mcp.get('mcpServers', {})
diff --git a/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
new file mode 100644
index 0000000000..eb835c7447
--- /dev/null
+++ b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
@@ -0,0 +1,294 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { useAddMcpServer } from "#/hooks/mutation/use-add-mcp-server";
+import { useDeleteMcpServer } from "#/hooks/mutation/use-delete-mcp-server";
+import { useUpdateMcpServer } from "#/hooks/mutation/use-update-mcp-server";
+import { useSelectedOrganizationStore } from "#/stores/selected-organization-store";
+
+describe("MCP Server Mutation Hooks", () => {
+ beforeEach(() => {
+ vi.restoreAllMocks();
+ useSelectedOrganizationStore.setState({ organizationId: "test-org-id" });
+ });
+
+ const createWrapper = () => {
+ const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: { retry: false },
+ mutations: { retry: false },
+ },
+ });
+ return ({ children }: { children: React.ReactNode }) => (
+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+ );
+ };
+
+ describe("useAddMcpServer", () => {
+ it("fetches fresh settings at mutation time", async () => {
+ const getSettingsSpy = vi
+ .spyOn(SettingsService, "getSettings")
+ .mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ mcpServers: {
+ existing: { url: "https://existing.com", transport: "sse" },
+ },
+ },
+ },
+ } as any);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ type: "sse",
+ url: "https://new-server.com",
+ });
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ expect(getSettingsSpy).toHaveBeenCalledTimes(1);
+ expect(saveSettingsSpy).toHaveBeenCalledWith({
+ agent_settings_diff: {
+ mcp_config: {
+ mcpServers: expect.objectContaining({
+ existing: expect.objectContaining({ url: "https://existing.com" }),
+ }),
+ },
+ },
+ });
+ });
+
+ it("handles adding server when no existing config", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {},
+ } as any);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ type: "sse",
+ url: "https://first-server.com",
+ });
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ expect(saveSettingsSpy).toHaveBeenCalledWith({
+ agent_settings_diff: {
+ mcp_config: {
+ mcpServers: {
+ sse: {
+ url: "https://first-server.com",
+ transport: "sse",
+ },
+ },
+ },
+ },
+ });
+ });
+
+ it("proceeds with empty config when getSettings returns null", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(null as any);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ type: "sse",
+ url: "https://server.com",
+ });
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ // Implementation handles null gracefully and proceeds
+ expect(saveSettingsSpy).toHaveBeenCalledWith({
+ agent_settings_diff: {
+ mcp_config: {
+ mcpServers: {
+ sse: {
+ url: "https://server.com",
+ transport: "sse",
+ },
+ },
+ },
+ },
+ });
+ });
+ });
+
+ describe("useDeleteMcpServer", () => {
+ it("deletes the correct server by index", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ mcpServers: {
+ server1: { url: "https://server1.com", transport: "sse" },
+ server2: { url: "https://server2.com", transport: "sse" },
+ server3: { url: "https://server3.com", transport: "sse" },
+ },
+ },
+ },
+ } as any);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ const { result } = renderHook(() => useDeleteMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ // Use hyphen separator as per implementation: serverId.split("-")
+ result.current.mutate("sse-1");
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ const savedPayload = saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: {
+ mcp_config: { mcpServers: Record<string, unknown> } | null;
+ };
+ };
+ const savedConfig = savedPayload.agent_settings_diff.mcp_config;
+ const serverNames = Object.keys(savedConfig?.mcpServers ?? {});
+ expect(serverNames).toHaveLength(2);
+ });
+
+ it("handles deleting from empty config", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: null,
+ },
+ } as any);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ const { result } = renderHook(() => useDeleteMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate("sse-0");
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ expect(saveSettingsSpy).toHaveBeenCalled();
+ });
+ });
+
+ describe("useUpdateMcpServer", () => {
+ it("updates the correct server URL", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ mcpServers: {
+ myserver: { url: "https://old-url.com", transport: "sse" },
+ },
+ },
+ },
+ } as any);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ const { result } = renderHook(() => useUpdateMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ // Use hyphen separator as per implementation
+ result.current.mutate({
+ serverId: "sse-0",
+ server: {
+ type: "sse",
+ url: "https://new-url.com",
+ },
+ });
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ const savedPayload = saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: {
+ mcp_config: { mcpServers: Record<string, { url: string }> };
+ };
+ };
+ const savedConfig = savedPayload.agent_settings_diff.mcp_config;
+ const serverUrls = Object.values(savedConfig.mcpServers).map(
+ (s) => s.url,
+ );
+ expect(serverUrls).toContain("https://new-url.com");
+ });
+ });
+
+ describe("error handling", () => {
+ it("handles getSettings failure", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockRejectedValue(
+ new Error("Network error"),
+ );
+
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({ type: "sse", url: "https://server.com" });
+
+ await waitFor(() => {
+ expect(result.current.isError).toBe(true);
+ });
+
+ expect(result.current.error).toBeDefined();
+ });
+
+ it("handles saveSettings failure", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: { mcp_config: null },
+ } as any);
+
+ vi.spyOn(SettingsService, "saveSettings").mockRejectedValue(
+ new Error("Save failed"),
+ );
+
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({ type: "sse", url: "https://server.com" });
+
+ await waitFor(() => {
+ expect(result.current.isError).toBe(true);
+ });
+
+ expect(result.current.error).toBeDefined();
+ });
+ });
+});
diff --git a/frontend/__tests__/utils/mcp-config.test.ts b/frontend/__tests__/utils/mcp-config.test.ts
new file mode 100644
index 0000000000..721d9be869
--- /dev/null
+++ b/frontend/__tests__/utils/mcp-config.test.ts
@@ -0,0 +1,442 @@
+import { describe, it, expect } from "vitest";
+import { parseMcpConfig, toSdkMcpConfig } from "#/utils/mcp-config";
+import { MCPConfig } from "#/types/settings";
+
+describe("parseMcpConfig", () => {
+ it("should return empty config for null/undefined input", () => {
+ expect(parseMcpConfig(null)).toEqual({
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ });
+ expect(parseMcpConfig(undefined)).toEqual({
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ });
+ });
+
+ it("should return empty config for invalid input", () => {
+ expect(parseMcpConfig("string")).toEqual({
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ });
+ expect(parseMcpConfig({})).toEqual({
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ });
+ expect(parseMcpConfig({ mcpServers: null })).toEqual({
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ });
+ });
+
+ it("should preserve server names for SSE servers", () => {
+ const input = {
+ mcpServers: {
+ "my-custom-name": {
+ url: "https://example.com",
+ transport: "sse",
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.sse_servers).toHaveLength(1);
+ expect(result.sse_servers[0]).toEqual({
+ name: "my-custom-name",
+ url: "https://example.com",
+ });
+ });
+
+ it("should preserve server names for shttp servers", () => {
+ const input = {
+ mcpServers: {
+ "http-server": {
+ url: "https://example.com",
+ transport: "http",
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.shttp_servers).toHaveLength(1);
+ expect(result.shttp_servers[0]).toEqual({
+ name: "http-server",
+ url: "https://example.com",
+ });
+ });
+
+ it("should preserve server names for stdio servers", () => {
+ const input = {
+ mcpServers: {
+ "my-stdio-server": {
+ command: "/usr/bin/my-server",
+ args: ["--port", "8080"],
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.stdio_servers).toHaveLength(1);
+ expect(result.stdio_servers[0]).toEqual({
+ name: "my-stdio-server",
+ command: "/usr/bin/my-server",
+ args: ["--port", "8080"],
+ });
+ });
+
+ it("should parse api_key from auth field", () => {
+ const input = {
+ mcpServers: {
+ "auth-server": {
+ url: "https://example.com",
+ transport: "sse",
+ auth: "my-secret-key",
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.sse_servers[0]).toEqual({
+ name: "auth-server",
+ url: "https://example.com",
+ api_key: "my-secret-key",
+ });
+ });
+
+ it("should not include api_key when auth is 'oauth'", () => {
+ const input = {
+ mcpServers: {
+ "oauth-server": {
+ url: "https://example.com",
+ transport: "sse",
+ auth: "oauth",
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.sse_servers[0]).toEqual({
+ name: "oauth-server",
+ url: "https://example.com",
+ });
+ expect((result.sse_servers[0] as { api_key?: string }).api_key).toBeUndefined();
+ });
+
+ it("should parse timeout for shttp servers", () => {
+ const input = {
+ mcpServers: {
+ "timeout-server": {
+ url: "https://example.com",
+ transport: "http",
+ timeout: 30,
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.shttp_servers[0]).toEqual({
+ name: "timeout-server",
+ url: "https://example.com",
+ timeout: 30,
+ });
+ });
+});
+
+describe("toSdkMcpConfig", () => {
+ it("should return null for empty config", () => {
+ const config: MCPConfig = {
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ };
+
+ expect(toSdkMcpConfig(config)).toBeNull();
+ });
+
+ it("should use preserved names when available", () => {
+ const config: MCPConfig = {
+ sse_servers: [{ name: "my-custom-name", url: "https://example.com" }],
+ stdio_servers: [],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result).toEqual({
+ mcpServers: {
+ "my-custom-name": {
+ url: "https://example.com",
+ transport: "sse",
+ },
+ },
+ });
+ });
+
+ it("should generate default names for servers without names", () => {
+ const config: MCPConfig = {
+ sse_servers: ["https://example.com"],
+ stdio_servers: [],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result).toEqual({
+ mcpServers: {
+ sse: {
+ url: "https://example.com",
+ transport: "sse",
+ },
+ },
+ });
+ });
+
+ it("should handle name collisions with suffix", () => {
+ const config: MCPConfig = {
+ sse_servers: [
+ { name: "sse", url: "https://example1.com" },
+ { name: "sse", url: "https://example2.com" },
+ { name: "sse", url: "https://example3.com" },
+ ],
+ stdio_servers: [],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result?.mcpServers).toHaveProperty("sse");
+ expect(result?.mcpServers).toHaveProperty("sse_1");
+ expect(result?.mcpServers).toHaveProperty("sse_2");
+ expect(result?.mcpServers["sse"].url).toBe("https://example1.com");
+ expect(result?.mcpServers["sse_1"].url).toBe("https://example2.com");
+ expect(result?.mcpServers["sse_2"].url).toBe("https://example3.com");
+ });
+
+ it("should include api_key as auth field", () => {
+ const config: MCPConfig = {
+ sse_servers: [
+ { name: "secure", url: "https://example.com", api_key: "my-secret" },
+ ],
+ stdio_servers: [],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result?.mcpServers["secure"]).toEqual({
+ url: "https://example.com",
+ transport: "sse",
+ auth: "my-secret",
+ });
+ });
+
+ it("should include timeout for shttp servers", () => {
+ const config: MCPConfig = {
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [
+ { name: "timeout", url: "https://example.com", timeout: 60 },
+ ],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result?.mcpServers["timeout"]).toEqual({
+ url: "https://example.com",
+ timeout: 60,
+ });
+ });
+
+ it("should convert stdio servers correctly", () => {
+ const config: MCPConfig = {
+ sse_servers: [],
+ stdio_servers: [
+ {
+ name: "my-stdio",
+ command: "/usr/bin/server",
+ args: ["--flag"],
+ env: { KEY: "value" },
+ },
+ ],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result?.mcpServers["my-stdio"]).toEqual({
+ command: "/usr/bin/server",
+ args: ["--flag"],
+ env: { KEY: "value" },
+ });
+ });
+});
+
+describe("round-trip preservation", () => {
+ it("should preserve server names through parse -> serialize round-trip", () => {
+ const original = {
+ mcpServers: {
+ "custom-sse-name": {
+ url: "https://sse.example.com",
+ transport: "sse",
+ },
+ "custom-http-name": {
+ url: "https://http.example.com",
+ transport: "http",
+ },
+ "custom-stdio-name": {
+ command: "/usr/bin/server",
+ },
+ },
+ };
+
+ const parsed = parseMcpConfig(original);
+ const serialized = toSdkMcpConfig(parsed);
+
+ expect(serialized?.mcpServers).toHaveProperty("custom-sse-name");
+ expect(serialized?.mcpServers).toHaveProperty("custom-http-name");
+ expect(serialized?.mcpServers).toHaveProperty("custom-stdio-name");
+ });
+
+ it("should not generate new names if original names are preserved", () => {
+ const original = {
+ mcpServers: {
+ server1: { url: "https://server1.com", transport: "sse" },
+ server2: { url: "https://server2.com", transport: "sse" },
+ },
+ };
+
+ const parsed = parseMcpConfig(original);
+ const serialized = toSdkMcpConfig(parsed);
+
+ // Should use original names, not "sse" or "sse_1"
+ expect(serialized?.mcpServers).toHaveProperty("server1");
+ expect(serialized?.mcpServers).toHaveProperty("server2");
+ expect(serialized?.mcpServers).not.toHaveProperty("sse");
+ expect(serialized?.mcpServers).not.toHaveProperty("sse_1");
+ });
+});
+
+describe("edge cases", () => {
+ it("should handle empty mcpServers object", () => {
+ const input = { mcpServers: {} };
+ const result = parseMcpConfig(input);
+
+ expect(result).toEqual({
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ });
+ });
+
+ it("should treat server with missing url as stdio server", () => {
+ const input = {
+ mcpServers: {
+ "no-url-server": {
+ transport: "sse",
+ command: "/usr/bin/server",
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ // Servers without url are treated as stdio servers
+ expect(result.stdio_servers).toHaveLength(1);
+ expect(result.stdio_servers[0]).toEqual({
+ name: "no-url-server",
+ command: "/usr/bin/server",
+ });
+ });
+
+ it("should treat unknown transport type as shttp server", () => {
+ const input = {
+ mcpServers: {
+ "unknown-transport": {
+ url: "https://example.com",
+ transport: "websocket", // not "sse", so falls through to shttp
+ },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ // Non-SSE transports with url go to shttp_servers
+ expect(result.sse_servers).toHaveLength(0);
+ expect(result.shttp_servers).toHaveLength(1);
+ expect(result.shttp_servers[0]).toEqual({
+ name: "unknown-transport",
+ url: "https://example.com",
+ });
+ });
+
+ it("should handle mixed server types correctly", () => {
+ const input = {
+ mcpServers: {
+ "sse-server": { url: "https://sse.com", transport: "sse" },
+ "http-server": { url: "https://http.com", transport: "http" },
+ "stdio-server": { command: "/usr/bin/cmd" },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.sse_servers).toHaveLength(1);
+ expect(result.shttp_servers).toHaveLength(1);
+ expect(result.stdio_servers).toHaveLength(1);
+ });
+
+ it("should handle deleting all servers (empty result)", () => {
+ const config: MCPConfig = {
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result).toBeNull();
+ });
+
+ it("should handle servers with special characters in names", () => {
+ const input = {
+ mcpServers: {
+ "server/with/slashes": { url: "https://s1.com", transport: "sse" },
+ "server:with:colons": { url: "https://s2.com", transport: "sse" },
+ "server with spaces": { url: "https://s3.com", transport: "sse" },
+ },
+ };
+
+ const parsed = parseMcpConfig(input);
+ const serialized = toSdkMcpConfig(parsed);
+
+ expect(serialized?.mcpServers).toHaveProperty("server/with/slashes");
+ expect(serialized?.mcpServers).toHaveProperty("server:with:colons");
+ expect(serialized?.mcpServers).toHaveProperty("server with spaces");
+ });
+
+ it("should handle cross-type name collisions", () => {
+ const config: MCPConfig = {
+ sse_servers: [{ name: "myserver", url: "https://sse.com" }],
+ stdio_servers: [{ name: "myserver", command: "/usr/bin/cmd" }],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ const names = Object.keys(result?.mcpServers || {});
+ expect(names).toContain("myserver");
+ expect(names).toContain("myserver_1");
+ expect(names).toHaveLength(2);
+ });
+});
diff --git a/frontend/src/api/settings-service/settings-service.api.ts b/frontend/src/api/settings-service/settings-service.api.ts
index c966cf182f..18ff1c4a01 100644
--- a/frontend/src/api/settings-service/settings-service.api.ts
+++ b/frontend/src/api/settings-service/settings-service.api.ts
@@ -37,8 +37,8 @@ class SettingsService {
static async saveSettings(
settings: Partial<Settings> & Record<string, unknown>,
): Promise<boolean> {
- const data = await openHands.post("/api/v1/settings", settings);
- return data.status === 200;
+ const response = await openHands.post("/api/v1/settings", settings);
+ return response.status === 200;
}
}
diff --git a/frontend/src/hooks/mutation/use-add-mcp-server.ts b/frontend/src/hooks/mutation/use-add-mcp-server.ts
index e29a4566d6..5c4efe10a4 100644
--- a/frontend/src/hooks/mutation/use-add-mcp-server.ts
+++ b/frontend/src/hooks/mutation/use-add-mcp-server.ts
@@ -1,5 +1,4 @@
import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useSettings } from "#/hooks/query/use-settings";
import SettingsService from "#/api/settings-service/settings-service.api";
import {
MCPSHTTPServer,
@@ -26,14 +25,16 @@ interface MCPServerConfig {
export function useAddMcpServer() {
const queryClient = useQueryClient();
- const { data: settings } = useSettings();
const { organizationId } = useSelectedOrganizationId();
return useMutation({
mutationFn: async (server: MCPServerConfig): Promise<void> => {
- if (!settings) return;
+ // Fetch fresh settings at mutation time to avoid stale closure issues
+ const settings = await SettingsService.getSettings();
- const currentConfig = parseMcpConfig(settings.agent_settings?.mcp_config);
+ const currentConfig = parseMcpConfig(
+ settings?.agent_settings?.mcp_config,
+ );
const newConfig: MCPConfig = {
sse_servers: [...currentConfig.sse_servers],
@@ -64,9 +65,11 @@ export function useAddMcpServer() {
newConfig.shttp_servers.push(shttpServer);
}
- await SettingsService.saveSettings({
+ const payload = {
agent_settings_diff: { mcp_config: toSdkMcpConfig(newConfig) },
- });
+ };
+
+ await SettingsService.saveSettings(payload);
},
onSuccess: () => {
queryClient.invalidateQueries({
diff --git a/frontend/src/hooks/mutation/use-delete-mcp-server.ts b/frontend/src/hooks/mutation/use-delete-mcp-server.ts
index 911099dcc8..97b1165e49 100644
--- a/frontend/src/hooks/mutation/use-delete-mcp-server.ts
+++ b/frontend/src/hooks/mutation/use-delete-mcp-server.ts
@@ -1,5 +1,4 @@
import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useSettings } from "#/hooks/query/use-settings";
import SettingsService from "#/api/settings-service/settings-service.api";
import { MCPConfig } from "#/types/settings";
import { parseMcpConfig, toSdkMcpConfig } from "#/utils/mcp-config";
@@ -8,11 +7,13 @@ import { SETTINGS_QUERY_KEYS } from "#/hooks/query/query-keys";
export function useDeleteMcpServer() {
const queryClient = useQueryClient();
- const { data: settings } = useSettings();
const { organizationId } = useSelectedOrganizationId();
return useMutation({
mutationFn: async (serverId: string): Promise<void> => {
+ // Fetch fresh settings at mutation time to avoid stale closure issues
+ const settings = await SettingsService.getSettings();
+
const currentConfig = parseMcpConfig(
settings?.agent_settings?.mcp_config,
);
@@ -33,9 +34,11 @@ export function useDeleteMcpServer() {
newConfig.shttp_servers.splice(index, 1);
}
- await SettingsService.saveSettings({
+ const payload = {
agent_settings_diff: { mcp_config: toSdkMcpConfig(newConfig) },
- });
+ };
+
+ await SettingsService.saveSettings(payload);
},
onSuccess: () => {
queryClient.invalidateQueries({
diff --git a/frontend/src/hooks/mutation/use-update-mcp-server.ts b/frontend/src/hooks/mutation/use-update-mcp-server.ts
index 33925d5ca9..2e1519745d 100644
--- a/frontend/src/hooks/mutation/use-update-mcp-server.ts
+++ b/frontend/src/hooks/mutation/use-update-mcp-server.ts
@@ -1,5 +1,4 @@
import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useSettings } from "#/hooks/query/use-settings";
import SettingsService from "#/api/settings-service/settings-service.api";
import {
MCPSHTTPServer,
@@ -26,7 +25,6 @@ interface MCPServerConfig {
export function useUpdateMcpServer() {
const queryClient = useQueryClient();
- const { data: settings } = useSettings();
const { organizationId } = useSelectedOrganizationId();
return useMutation({
@@ -37,6 +35,9 @@ export function useUpdateMcpServer() {
serverId: string;
server: MCPServerConfig;
}): Promise<void> => {
+ // Fetch fresh settings at mutation time to avoid stale closure issues
+ const settings = await SettingsService.getSettings();
+
const currentConfig = parseMcpConfig(
settings?.agent_settings?.mcp_config,
);
@@ -72,9 +73,11 @@ export function useUpdateMcpServer() {
newConfig.shttp_servers[index] = shttpServer;
}
- await SettingsService.saveSettings({
+ const payload = {
agent_settings_diff: { mcp_config: toSdkMcpConfig(newConfig) },
- });
+ };
+
+ await SettingsService.saveSettings(payload);
},
onSuccess: () => {
queryClient.invalidateQueries({
diff --git a/frontend/src/types/settings.ts b/frontend/src/types/settings.ts
index c209e94159..5baad30d65 100644
--- a/frontend/src/types/settings.ts
+++ b/frontend/src/types/settings.ts
@@ -27,6 +27,7 @@ export type ProviderToken = {
};
export type MCPSSEServer = {
+ name?: string;
url: string;
api_key?: string;
};
@@ -39,6 +40,7 @@ export type MCPStdioServer = {
};
export type MCPSHTTPServer = {
+ name?: string;
url: string;
api_key?: string;
timeout?: number;
diff --git a/frontend/src/utils/mcp-config.ts b/frontend/src/utils/mcp-config.ts
index 907e09e605..020829d031 100644
--- a/frontend/src/utils/mcp-config.ts
+++ b/frontend/src/utils/mcp-config.ts
@@ -15,9 +15,25 @@ const EMPTY_MCP_CONFIG: MCPConfig = {
type SdkMcpServerConfig = Record<string, SettingsValue>;
type SdkMcpConfig = { mcpServers: Record<string, SdkMcpServerConfig> };
+/**
+ * Generate a unique name for an MCP server, avoiding collisions with existing names.
+ * Only adds a suffix if there's an actual collision.
+ */
+function getUniqueName(base: string, usedNames: Set<string>): string {
+ if (!usedNames.has(base)) {
+ return base;
+ }
+ let suffix = 1;
+ while (usedNames.has(`${base}_${suffix}`)) {
+ suffix += 1;
+ }
+ return `${base}_${suffix}`;
+}
+
/**
* Parse an SDK mcp_config value ({ mcpServers: { ... } }) and convert it
* to the frontend MCPConfig format used by UI components.
+ * Preserves server names for round-trip serialization.
*/
export function parseMcpConfig(value: unknown): MCPConfig {
if (!value || typeof value !== "object") {
@@ -53,11 +69,17 @@ export function parseMcpConfig(value: unknown): MCPConfig {
typeof auth === "string" && auth !== "oauth" ? auth : undefined;
if (transport === "sse") {
- const server: MCPSSEServer = { url };
+ const server: MCPSSEServer = {
+ name: serverName,
+ url,
+ };
if (apiKey) server.api_key = apiKey;
sseServers.push(server);
} else {
- const server: MCPSHTTPServer = { url };
+ const server: MCPSHTTPServer = {
+ name: serverName,
+ url,
+ };
if (apiKey) server.api_key = apiKey;
if (serverConfig.timeout != null) {
server.timeout = serverConfig.timeout as number;
@@ -89,17 +111,13 @@ export function parseMcpConfig(value: unknown): MCPConfig {
/**
* Convert the frontend MCPConfig format back to the SDK { mcpServers: { ... } }
* shape expected by agent_settings.mcp_config on the backend.
+ * Uses preserved names when available, only generates names for new servers.
*/
export function toSdkMcpConfig(config: MCPConfig): SdkMcpConfig | null {
const mcpServers: Record<string, SdkMcpServerConfig> = {};
- let counter = 0;
-
- const nextName = (base: string): string => {
- const name = counter === 0 ? base : `${base}_${counter}`;
- counter += 1;
- return name;
- };
+ const usedNames = new Set<string>();
+ // SSE servers - use preserved name or generate
for (const entry of config.sse_servers) {
const server: SdkMcpServerConfig = {};
if (typeof entry === "string") {
@@ -109,9 +127,15 @@ export function toSdkMcpConfig(config: MCPConfig): SdkMcpConfig | null {
if (entry.api_key) server.auth = entry.api_key;
}
server.transport = "sse";
- mcpServers[nextName("sse")] = server;
+
+ const baseName =
+ typeof entry !== "string" && entry.name ? entry.name : "sse";
+ const name = getUniqueName(baseName, usedNames);
+ usedNames.add(name);
+ mcpServers[name] = server;
}
+ // shttp servers - use preserved name or generate
for (const entry of config.shttp_servers) {
const server: SdkMcpServerConfig = {};
if (typeof entry === "string") {
@@ -121,16 +145,26 @@ export function toSdkMcpConfig(config: MCPConfig): SdkMcpConfig | null {
if (entry.api_key) server.auth = entry.api_key;
if (entry.timeout != null) server.timeout = entry.timeout;
}
- mcpServers[nextName("shttp")] = server;
+
+ const baseName =
+ typeof entry !== "string" && entry.name ? entry.name : "shttp";
+ const name = getUniqueName(baseName, usedNames);
+ usedNames.add(name);
+ mcpServers[name] = server;
}
+ // stdio servers - use preserved name or generate
for (const entry of config.stdio_servers) {
const server: SdkMcpServerConfig = {
command: entry.command,
};
if (entry.args) server.args = entry.args;
if (entry.env) server.env = entry.env;
- mcpServers[nextName(entry.name || "stdio")] = server;
+
+ const baseName = entry.name || "stdio";
+ const name = getUniqueName(baseName, usedNames);
+ usedNames.add(name);
+ mcpServers[name] = server;
}
return Object.keys(mcpServers).length > 0 ? { mcpServers } : null;
diff --git a/openhands/app_server/utils/jsonpatch_compat.py b/openhands/app_server/utils/jsonpatch_compat.py
index 23c0f73f22..0136afc215 100644
--- a/openhands/app_server/utils/jsonpatch_compat.py
+++ b/openhands/app_server/utils/jsonpatch_compat.py
@@ -2,6 +2,10 @@ from __future__ import annotations
from typing import Any
+# Keys that should be replaced wholesale (not deep merged) because they
+# represent sets of items where merging would resurrect deleted entries.
+WHOLESALE_REPLACEMENT_KEYS: frozenset[str] = frozenset({'mcp_config', 'acp_env'})
+
def deep_merge(
base: dict[str, Any],
@@ -22,3 +26,32 @@ def deep_merge(
else:
result[key] = value
return result
+
+
+def deep_merge_with_wholesale_keys(
+ base: dict[str, Any],
+ updates: dict[str, Any],
+ wholesale_keys: frozenset[str] | None = None,
+) -> dict[str, Any]:
+ """Like deep_merge, but specified keys are replaced wholesale (not merged).
+
+ Useful for keys like 'mcp_config' and 'acp_env' where the dict represents
+ a set of items and deep merging would resurrect deleted items.
+
+ Args:
+ base: The base dictionary to merge into.
+ updates: The updates to apply.
+ wholesale_keys: Keys that should be replaced entirely from updates
+ rather than deep merged. Defaults to WHOLESALE_REPLACEMENT_KEYS.
+
+ Returns:
+ A new dictionary with updates applied.
+ """
+ if wholesale_keys is None:
+ wholesale_keys = WHOLESALE_REPLACEMENT_KEYS
+
+ result = deep_merge(base, updates)
+ for key in wholesale_keys:
+ if key in updates:
+ result[key] = updates[key]
+ return result
diff --git a/tests/unit/app_server/utils/test_jsonpatch_compat.py b/tests/unit/app_server/utils/test_jsonpatch_compat.py
new file mode 100644
index 0000000000..0afc41b4cf
--- /dev/null
+++ b/tests/unit/app_server/utils/test_jsonpatch_compat.py
@@ -0,0 +1,182 @@
+"""Tests for jsonpatch_compat utilities."""
+
+from openhands.app_server.utils.jsonpatch_compat import (
+ WHOLESALE_REPLACEMENT_KEYS,
+ deep_merge,
+ deep_merge_with_wholesale_keys,
+)
+
+
+class TestDeepMerge:
+ """Tests for the base deep_merge function."""
+
+ def test_basic_merge(self):
+ base = {'a': 1, 'b': 2}
+ updates = {'b': 3, 'c': 4}
+ result = deep_merge(base, updates)
+ assert result == {'a': 1, 'b': 3, 'c': 4}
+
+ def test_nested_merge(self):
+ base = {'outer': {'inner1': 1, 'inner2': 2}}
+ updates = {'outer': {'inner2': 3, 'inner3': 4}}
+ result = deep_merge(base, updates)
+ assert result == {'outer': {'inner1': 1, 'inner2': 3, 'inner3': 4}}
+
+ def test_none_removes_key(self):
+ base = {'a': 1, 'b': 2}
+ updates = {'b': None}
+ result = deep_merge(base, updates)
+ assert result == {'a': 1}
+
+ def test_does_not_mutate_base(self):
+ base = {'a': 1}
+ updates = {'b': 2}
+ deep_merge(base, updates)
+ assert base == {'a': 1}
+
+
+class TestDeepMergeWithWholesaleKeys:
+ """Tests for deep_merge_with_wholesale_keys function."""
+
+ def test_default_wholesale_keys(self):
+ """Verify default wholesale keys are mcp_config and acp_env."""
+ assert 'mcp_config' in WHOLESALE_REPLACEMENT_KEYS
+ assert 'acp_env' in WHOLESALE_REPLACEMENT_KEYS
+
+ def test_mcp_config_replaced_wholesale(self):
+ """mcp_config should be replaced, not merged."""
+ base = {
+ 'llm': {'model': 'gpt-4'},
+ 'mcp_config': {
+ 'mcpServers': {
+ 'server1': {'url': 'https://s1.com'},
+ 'server2': {'url': 'https://s2.com'},
+ 'server3': {'url': 'https://s3.com'},
+ }
+ },
+ }
+ updates = {
+ 'mcp_config': {
+ 'mcpServers': {
+ 'server1': {'url': 'https://s1.com'},
+ 'server2': {'url': 'https://s2.com'},
+ # server3 deleted
+ }
+ }
+ }
+
+ result = deep_merge_with_wholesale_keys(base, updates)
+
+ # server3 should NOT be resurrected
+ assert len(result['mcp_config']['mcpServers']) == 2
+ assert 'server3' not in result['mcp_config']['mcpServers']
+
+ def test_acp_env_replaced_wholesale(self):
+ """acp_env should be replaced, not merged."""
+ base = {
+ 'acp_env': {
+ 'VAR1': 'value1',
+ 'VAR2': 'value2',
+ 'VAR3': 'value3',
+ }
+ }
+ updates = {
+ 'acp_env': {
+ 'VAR1': 'value1',
+ 'VAR2': 'value2',
+ # VAR3 deleted
+ }
+ }
+
+ result = deep_merge_with_wholesale_keys(base, updates)
+
+ assert len(result['acp_env']) == 2
+ assert 'VAR3' not in result['acp_env']
+
+ def test_other_keys_still_deep_merged(self):
+ """Non-wholesale keys should still be deep merged."""
+ base = {
+ 'llm': {'model': 'gpt-4', 'temperature': 0.7},
+ 'mcp_config': {'mcpServers': {'old': {}}},
+ }
+ updates = {
+ 'llm': {'model': 'gpt-5'}, # should merge
+ 'mcp_config': {'mcpServers': {'new': {}}}, # should replace
+ }
+
+ result = deep_merge_with_wholesale_keys(base, updates)
+
+ # llm should be deep merged (temperature preserved)
+ assert result['llm']['model'] == 'gpt-5'
+ assert result['llm']['temperature'] == 0.7
+
+ # mcp_config should be replaced (old server gone)
+ assert 'old' not in result['mcp_config']['mcpServers']
+ assert 'new' in result['mcp_config']['mcpServers']
+
+ def test_wholesale_key_not_in_updates(self):
+ """If wholesale key not in updates, it should be preserved from base."""
+ base = {
+ 'llm': {'model': 'gpt-4'},
+ 'mcp_config': {'mcpServers': {'existing': {'url': 'https://existing.com'}}},
+ }
+ updates = {
+ 'llm': {'model': 'gpt-5'}
+ # mcp_config NOT in updates
+ }
+
+ result = deep_merge_with_wholesale_keys(base, updates)
+
+ # mcp_config should be preserved (deep merged, not cleared)
+ assert 'mcp_config' in result
+ assert 'existing' in result['mcp_config']['mcpServers']
+
+ def test_empty_wholesale_value(self):
+ """Empty dict for wholesale key should clear it."""
+ base = {
+ 'mcp_config': {
+ 'mcpServers': {
+ 'server1': {'url': 'https://s1.com'},
+ 'server2': {'url': 'https://s2.com'},
+ }
+ }
+ }
+ updates = {
+ 'mcp_config': {
+ 'mcpServers': {} # delete all servers
+ }
+ }
+
+ result = deep_merge_with_wholesale_keys(base, updates)
+
+ assert result['mcp_config']['mcpServers'] == {}
+
+ def test_custom_wholesale_keys(self):
+ """Should support custom wholesale keys via parameter."""
+ base = {'custom_dict': {'a': 1, 'b': 2, 'c': 3}}
+ updates = {
+ 'custom_dict': {'a': 1, 'b': 2} # c deleted
+ }
+
+ # Without custom keys, c would be preserved (deep merge)
+ result_default = deep_merge_with_wholesale_keys(base, updates)
+ assert 'c' in result_default['custom_dict']
+
+ # With custom keys, c should be deleted (wholesale replace)
+ result_custom = deep_merge_with_wholesale_keys(
+ base, updates, wholesale_keys=frozenset({'custom_dict'})
+ )
+ assert 'c' not in result_custom['custom_dict']
+
+ def test_does_not_mutate_inputs(self):
+ """Should not mutate base or updates."""
+ base = {'mcp_config': {'mcpServers': {'s1': {}}}}
+ updates = {'mcp_config': {'mcpServers': {'s2': {}}}}
+
+ base_copy = {'mcp_config': {'mcpServers': {'s1': {}}}}
+ updates_copy = {'mcp_config': {'mcpServers': {'s2': {}}}}
+
+ deep_merge_with_wholesale_keys(base, updates)
+
+ assert base == base_copy
+ assert updates == updates_copy