Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(mcp): preserve SaaS credentials with encrypted storage (#15257)

simonrosenberg478a05bf58a8
diff --git a/enterprise/migrations/versions/137_encrypt_member_mcp_config.py b/enterprise/migrations/versions/137_encrypt_member_mcp_config.py
new file mode 100644
index 0000000000..a1692da120
--- /dev/null
+++ b/enterprise/migrations/versions/137_encrypt_member_mcp_config.py
@@ -0,0 +1,400 @@
+"""Move MCP configuration into encrypted member storage."""
+
+import json
+import re
+from copy import deepcopy
+from typing import Any
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = '137'
+down_revision = '136'
+branch_labels = None
+depends_on = None
+
+# Pin the SDK marker present in data written before revision 137.
+_REDACTED_SECRET = '**********'
+
+
+def _extract_mcp_config(
+ settings: dict[str, Any] | None,
+) -> tuple[dict[str, Any] | None, dict[str, Any], bool]:
+ cleaned = dict(settings or {})
+ if 'mcp_config' not in cleaned:
+ return None, cleaned, False
+ value = cleaned.pop('mcp_config')
+ return value if isinstance(value, dict) else None, cleaned, True
+
+
+def _with_mcp_config(
+ settings: dict[str, Any] | None,
+ mcp_config: dict[str, Any],
+) -> dict[str, Any]:
+ restored = dict(settings or {})
+ restored['mcp_config'] = mcp_config
+ return restored
+
+
+def _is_redacted_secret(value: object) -> bool:
+ if not isinstance(value, str):
+ return False
+ return value == _REDACTED_SECRET or bool(
+ re.fullmatch(
+ rf'Bearer\s+{re.escape(_REDACTED_SECRET)}',
+ value,
+ flags=re.IGNORECASE,
+ )
+ )
+
+
+def _restore_redacted_value(value: Any, backup: Any) -> Any:
+ if _is_redacted_secret(value):
+ if isinstance(backup, str) and not _is_redacted_secret(backup):
+ return backup
+ return value
+ if isinstance(value, dict):
+ backup_dict = backup if isinstance(backup, dict) else {}
+ return {
+ key: _restore_redacted_value(item, backup_dict.get(key))
+ for key, item in value.items()
+ }
+ return value
+
+
+def _mcp_server_map(value: dict[str, Any]) -> dict[str, Any] | None:
+ servers = value.get('mcpServers', value)
+ return servers if isinstance(servers, dict) else None
+
+
+def _mcp_endpoint_identity(server: dict[str, Any]) -> tuple[Any, ...] | None:
+ url = server.get('url')
+ if isinstance(url, str) and url:
+ return ('url', url)
+ command = server.get('command')
+ if not isinstance(command, str) or not command:
+ return None
+ args = server.get('args')
+ # Bind environment secrets to the full process invocation.
+ return (
+ 'stdio',
+ command,
+ tuple(args) if isinstance(args, list) else (),
+ server.get('cwd'),
+ )
+
+
+def _mcp_bearer_token(server: dict[str, Any]) -> str | None:
+ auth = server.get('auth')
+ if isinstance(auth, dict):
+ value = auth.get('value')
+ if (
+ str(auth.get('strategy', '')).lower() == 'bearer'
+ and isinstance(value, str)
+ and not _is_redacted_secret(value)
+ ):
+ return value
+ elif (
+ isinstance(auth, str)
+ and auth.lower() != 'oauth'
+ and not _is_redacted_secret(auth)
+ ):
+ return auth
+
+ headers = server.get('headers')
+ if not isinstance(headers, dict):
+ return None
+ for key, value in headers.items():
+ if not isinstance(key, str) or key.lower() != 'authorization':
+ continue
+ if not isinstance(value, str):
+ continue
+ match = re.fullmatch(r'Bearer\s+(.+)', value, flags=re.IGNORECASE)
+ if match and not _is_redacted_secret(match.group(1)):
+ return match.group(1)
+ return None
+
+
+def _has_redacted_secret(value: object) -> bool:
+ if _is_redacted_secret(value):
+ return True
+ if isinstance(value, dict):
+ return any(_has_redacted_secret(item) for item in value.values())
+ if isinstance(value, list):
+ return any(_has_redacted_secret(item) for item in value)
+ return False
+
+
+def _restore_redacted_auth(value: Any, backup: Any) -> Any:
+ if _has_redacted_secret(value) and backup is not None:
+ if isinstance(value, dict) and isinstance(backup, dict):
+ if value.get('strategy') != backup.get('strategy'):
+ return deepcopy(backup)
+ elif not isinstance(value, str) or not isinstance(backup, str):
+ return deepcopy(backup)
+ return _restore_redacted_value(value, backup)
+
+
+def _mcp_credential_backup(
+ current: dict[str, Any],
+ backup: dict[str, Any],
+) -> dict[str, Any]:
+ projected = deepcopy(backup)
+ bearer_token = _mcp_bearer_token(backup)
+ if bearer_token is None:
+ return projected
+
+ current_auth = current.get('auth')
+ if projected.get('auth') is None:
+ if (
+ isinstance(current_auth, dict)
+ and str(current_auth.get('strategy', '')).lower() == 'bearer'
+ ):
+ projected['auth'] = {'strategy': 'bearer', 'value': bearer_token}
+ elif _is_redacted_secret(current_auth):
+ projected['auth'] = bearer_token
+
+ current_headers = current.get('headers')
+ if isinstance(current_headers, dict):
+ projected_headers = (
+ dict(projected['headers'])
+ if isinstance(projected.get('headers'), dict)
+ else {}
+ )
+ for key, value in current_headers.items():
+ if (
+ isinstance(key, str)
+ and key.lower() == 'authorization'
+ and _is_redacted_secret(value)
+ ):
+ projected_headers[key] = f'Bearer {bearer_token}'
+ projected['headers'] = projected_headers
+ return projected
+
+
+def _recover_redacted_mcp_config(
+ value: dict[str, Any],
+ backup: dict[str, Any],
+) -> dict[str, Any]:
+ recovered = deepcopy(value)
+ current_servers = _mcp_server_map(recovered)
+ backup_servers = _mcp_server_map(backup)
+ if current_servers is None or backup_servers is None:
+ return recovered
+
+ for name, current_server in current_servers.items():
+ backup_server = backup_servers.get(name)
+ if not isinstance(current_server, dict) or not isinstance(backup_server, dict):
+ continue
+ endpoint = _mcp_endpoint_identity(current_server)
+ if endpoint is None or endpoint != _mcp_endpoint_identity(backup_server):
+ continue
+ credential_backup = _mcp_credential_backup(current_server, backup_server)
+ for field in ('headers', 'env', 'auth'):
+ if field in current_server:
+ restore = (
+ _restore_redacted_auth
+ if field == 'auth'
+ else _restore_redacted_value
+ )
+ current_server[field] = restore(
+ current_server[field], credential_backup.get(field)
+ )
+ return recovered
+
+
+def _encrypt_json(value: dict[str, Any]) -> str:
+ from storage.encrypt_utils import encrypt_value
+
+ return encrypt_value(json.dumps(value))
+
+
+def _decrypt_json(value: str) -> dict[str, Any]:
+ from storage.encrypt_utils import decrypt_value
+
+ decrypted = json.loads(decrypt_value(value))
+ if not isinstance(decrypted, dict):
+ raise ValueError('Expected MCP configuration to be a JSON object')
+ return decrypted
+
+
+def upgrade() -> None:
+ op.add_column('org_member', sa.Column('mcp_config', sa.String(), nullable=True))
+ op.add_column(
+ 'user_settings',
+ sa.Column('mcp_config_encrypted', sa.String(), nullable=True),
+ )
+
+ bind = op.get_bind()
+ user_settings = sa.table(
+ 'user_settings',
+ sa.column('id', sa.Integer()),
+ sa.column('keycloak_user_id', sa.String()),
+ sa.column('already_migrated', sa.Boolean()),
+ sa.column('agent_settings', sa.JSON()),
+ sa.column('mcp_config', sa.JSON()),
+ sa.column('mcp_config_encrypted', sa.String()),
+ )
+ personal_mcp_backups: dict[str, dict[str, Any]] = {}
+ for row in bind.execute(
+ sa.select(
+ user_settings.c.id,
+ user_settings.c.keycloak_user_id,
+ user_settings.c.already_migrated,
+ user_settings.c.agent_settings,
+ user_settings.c.mcp_config,
+ )
+ ).mappings():
+ nested, cleaned, present = _extract_mcp_config(row['agent_settings'])
+ standalone = row['mcp_config']
+ mcp_config = nested if present else standalone
+ if isinstance(mcp_config, dict) and isinstance(standalone, dict):
+ mcp_config = _recover_redacted_mcp_config(mcp_config, standalone)
+ if (
+ row['already_migrated'] is True
+ and isinstance(row['keycloak_user_id'], str)
+ and isinstance(mcp_config, dict)
+ ):
+ personal_mcp_backups[row['keycloak_user_id'].lower()] = mcp_config
+ if not present and standalone is None:
+ continue
+ if mcp_config is not None and not isinstance(mcp_config, dict):
+ mcp_config = None
+ bind.execute(
+ user_settings.update()
+ .where(user_settings.c.id == row['id'])
+ .values(
+ agent_settings=cleaned,
+ mcp_config_encrypted=(
+ _encrypt_json(mcp_config) if mcp_config is not None else None
+ ),
+ )
+ )
+
+ org_member = sa.table(
+ 'org_member',
+ sa.column('org_id', sa.Uuid()),
+ sa.column('user_id', sa.Uuid()),
+ sa.column('agent_settings_diff', sa.JSON()),
+ sa.column('mcp_config', sa.String()),
+ )
+ for row in bind.execute(
+ sa.select(
+ org_member.c.org_id,
+ org_member.c.user_id,
+ org_member.c.agent_settings_diff,
+ )
+ ).mappings():
+ mcp_config, cleaned, present = _extract_mcp_config(row['agent_settings_diff'])
+ if not present:
+ continue
+ if (
+ isinstance(mcp_config, dict)
+ and row['org_id'] == row['user_id']
+ and (backup := personal_mcp_backups.get(str(row['user_id']).lower()))
+ is not None
+ ):
+ mcp_config = _recover_redacted_mcp_config(mcp_config, backup)
+ bind.execute(
+ org_member.update()
+ .where(org_member.c.org_id == row['org_id'])
+ .where(org_member.c.user_id == row['user_id'])
+ .values(
+ agent_settings_diff=cleaned,
+ mcp_config=_encrypt_json(mcp_config)
+ if mcp_config is not None
+ else None,
+ )
+ )
+
+ org = sa.table(
+ 'org',
+ sa.column('id', sa.Uuid()),
+ sa.column('agent_settings', sa.JSON()),
+ )
+ for row in bind.execute(sa.select(org.c.id, org.c.agent_settings)).mappings():
+ _, cleaned, present = _extract_mcp_config(row['agent_settings'])
+ if present:
+ bind.execute(
+ org.update().where(org.c.id == row['id']).values(agent_settings=cleaned)
+ )
+
+ op.drop_column('user_settings', 'mcp_config')
+ op.alter_column(
+ 'user_settings',
+ 'mcp_config_encrypted',
+ new_column_name='mcp_config',
+ existing_type=sa.String(),
+ )
+
+
+def downgrade() -> None:
+ op.add_column(
+ 'user_settings',
+ sa.Column('mcp_config_plain', sa.JSON(), nullable=True),
+ )
+
+ bind = op.get_bind()
+ org_member = sa.table(
+ 'org_member',
+ sa.column('org_id', sa.Uuid()),
+ sa.column('user_id', sa.Uuid()),
+ sa.column('agent_settings_diff', sa.JSON()),
+ sa.column('mcp_config', sa.String()),
+ )
+ for row in bind.execute(
+ sa.select(
+ org_member.c.org_id,
+ org_member.c.user_id,
+ org_member.c.agent_settings_diff,
+ org_member.c.mcp_config,
+ )
+ ).mappings():
+ if row['mcp_config'] is None:
+ continue
+ mcp_config = _decrypt_json(row['mcp_config'])
+ bind.execute(
+ org_member.update()
+ .where(org_member.c.org_id == row['org_id'])
+ .where(org_member.c.user_id == row['user_id'])
+ .values(
+ agent_settings_diff=_with_mcp_config(
+ row['agent_settings_diff'], mcp_config
+ )
+ )
+ )
+
+ user_settings = sa.table(
+ 'user_settings',
+ sa.column('id', sa.Integer()),
+ sa.column('agent_settings', sa.JSON()),
+ sa.column('mcp_config', sa.String()),
+ sa.column('mcp_config_plain', sa.JSON()),
+ )
+ for row in bind.execute(
+ sa.select(
+ user_settings.c.id,
+ user_settings.c.agent_settings,
+ user_settings.c.mcp_config,
+ )
+ ).mappings():
+ if row['mcp_config'] is None:
+ continue
+ mcp_config = _decrypt_json(row['mcp_config'])
+ bind.execute(
+ user_settings.update()
+ .where(user_settings.c.id == row['id'])
+ .values(
+ agent_settings=_with_mcp_config(row['agent_settings'], mcp_config),
+ mcp_config_plain=mcp_config,
+ )
+ )
+
+ op.drop_column('user_settings', 'mcp_config')
+ op.alter_column(
+ 'user_settings',
+ 'mcp_config_plain',
+ new_column_name='mcp_config',
+ existing_type=sa.JSON(),
+ )
+ op.drop_column('org_member', 'mcp_config')
diff --git a/enterprise/server/routes/org_models.py b/enterprise/server/routes/org_models.py
index 01f6b0a932..f76548d41f 100644
--- a/enterprise/server/routes/org_models.py
+++ b/enterprise/server/routes/org_models.py
@@ -32,6 +32,8 @@ from openhands.sdk.settings import (
logger = logging.getLogger(__name__)
+MEMBER_PRIVATE_AGENT_KEYS: frozenset[str] = frozenset({'mcp_config'})
+
class OrgCreationError(Exception):
"""Base exception for organization creation errors."""
@@ -298,6 +300,9 @@ class OrgUpdate(BaseModel):
def _normalize_agent_settings_diff(self) -> None:
"""Normalize nested LLM settings inside ``agent_settings_diff``."""
+ if self.agent_settings_diff is not None:
+ for key in MEMBER_PRIVATE_AGENT_KEYS:
+ self.agent_settings_diff.pop(key, None)
llm_diff = self._get_agent_llm_diff()
if llm_diff is None:
return
diff --git a/enterprise/storage/agent_profile_resolution.py b/enterprise/storage/agent_profile_resolution.py
index 0ba27baa5e..340571bb49 100644
--- a/enterprise/storage/agent_profile_resolution.py
+++ b/enterprise/storage/agent_profile_resolution.py
@@ -92,15 +92,8 @@ class OrgLLMProfileMutator:
def member_mcp_config(member: OrgMember) -> dict[str, MCPServer]:
- """The acting member's globally-configured MCP servers as a server map.
-
- ``mcp_config`` is member-private (it lives only on the member's
- ``agent_settings_diff``; the org dump strips it β€” see
- ``MEMBER_PRIVATE_AGENT_KEYS``), so the member-effective set is exactly the
- member diff's ``mcp_config``. Used to resolve / filter ``mcp_server_refs``.
- Returns ``{}`` when the member configured no MCP servers.
- """
- raw = (member.agent_settings_diff or {}).get('mcp_config')
+ """Return the acting member's configured MCP servers."""
+ raw = member.effective_mcp_config
if not raw:
return {}
try:
diff --git a/enterprise/storage/org_member.py b/enterprise/storage/org_member.py
index a9f9e5e912..63b05333fe 100644
--- a/enterprise/storage/org_member.py
+++ b/enterprise/storage/org_member.py
@@ -9,7 +9,7 @@ from pydantic import SecretStr
from sqlalchemy import JSON, ForeignKey, String
from sqlalchemy.orm import Mapped, mapped_column, relationship
from storage.base import Base
-from storage.encrypt_utils import decrypt_value, encrypt_value
+from storage.encrypt_utils import EncryptedJSON, decrypt_value, encrypt_value
if TYPE_CHECKING:
from storage.org import Org
@@ -31,6 +31,9 @@ class OrgMember(Base):
agent_settings_diff: Mapped[dict[str, Any]] = mapped_column(
JSON, nullable=False, default=dict
)
+ mcp_config: Mapped[dict[str, Any] | None] = mapped_column(
+ EncryptedJSON, nullable=True
+ )
# Per-member pointer to the active AgentProfile id β€” the sole launch
# authority for Agent Profiles (mirrors the per-member _llm_api_key
# precedent). NULL falls back to the org default (org.agent_profiles.active)
@@ -82,3 +85,10 @@ class OrgMember(Base):
def llm_api_key_for_byor(self, value: str | SecretStr | None):
raw = value.get_secret_value() if isinstance(value, SecretStr) else value
self._llm_api_key_for_byor = encrypt_value(raw) if raw else None
+
+ @property
+ def effective_mcp_config(self) -> dict[str, Any] | None:
+ if self.mcp_config is not None:
+ return self.mcp_config
+ value = (self.agent_settings_diff or {}).get('mcp_config')
+ return value if isinstance(value, dict) else None
diff --git a/enterprise/storage/org_member_store.py b/enterprise/storage/org_member_store.py
index 86afe640fd..57e9826f64 100644
--- a/enterprise/storage/org_member_store.py
+++ b/enterprise/storage/org_member_store.py
@@ -5,7 +5,10 @@ Store class for managing organization-member relationships.
from typing import Any, Optional
from uuid import UUID
-from server.routes.org_models import OrgMemberSettingsUpdate
+from server.routes.org_models import (
+ MEMBER_PRIVATE_AGENT_KEYS,
+ OrgMemberSettingsUpdate,
+)
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.orm import joinedload
@@ -15,10 +18,23 @@ 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,
- deep_merge_with_wholesale_keys,
-)
+from openhands.app_server.utils.jsonpatch_compat import deep_merge
+from openhands.sdk.mcp.config import coerce_mcp_config, dump_mcp_config
+
+_MISSING = object()
+
+
+def serialize_mcp_config(value: object) -> dict[str, Any] | None:
+ if value is None:
+ return None
+ return dump_mcp_config(
+ coerce_mcp_config(value),
+ context={'expose_secrets': 'plaintext'},
+ )
+
+
+def _pop_mcp_config(settings: dict[str, Any]) -> object:
+ return settings.pop('mcp_config', _MISSING)
class OrgMemberStore:
@@ -35,6 +51,8 @@ class OrgMemberStore:
conversation_settings_diff: Optional[dict[str, Any]] = None,
) -> OrgMember:
"""Add a user to an organization with a specific role."""
+ agent_settings_diff = dict(agent_settings_diff or {})
+ mcp_config = _pop_mcp_config(agent_settings_diff)
async with a_session_maker() as session:
org_member = OrgMember(
org_id=org_id,
@@ -42,7 +60,12 @@ class OrgMemberStore:
role_id=role_id,
llm_api_key=llm_api_key,
status=status,
- agent_settings_diff=dict(agent_settings_diff or {}),
+ agent_settings_diff=agent_settings_diff,
+ mcp_config=(
+ serialize_mcp_config(mcp_config)
+ if mcp_config is not _MISSING
+ else None
+ ),
conversation_settings_diff=dict(conversation_settings_diff or {}),
)
session.add(org_member)
@@ -155,15 +178,24 @@ class OrgMemberStore:
return {
'llm_api_key': settings.agent_settings.llm.api_key,
'agent_settings_diff': {},
+ 'mcp_config': serialize_mcp_config(settings.agent_settings.mcp_config),
'conversation_settings_diff': {},
}
@staticmethod
def get_kwargs_from_user_settings(user_settings: UserSettings) -> dict[str, Any]:
"""Return kwargs for OrgMember construction (keys match column names)."""
+ agent_settings_diff = dict(user_settings.agent_settings or {})
+ nested_mcp_config = _pop_mcp_config(agent_settings_diff)
+ mcp_config = (
+ nested_mcp_config
+ if nested_mcp_config is not _MISSING
+ else user_settings.mcp_config
+ )
return {
'llm_api_key': user_settings.llm_api_key,
- 'agent_settings_diff': dict(user_settings.agent_settings),
+ 'agent_settings_diff': agent_settings_diff,
+ 'mcp_config': serialize_mcp_config(mcp_config),
'conversation_settings_diff': dict(user_settings.conversation_settings),
}
@@ -264,13 +296,17 @@ class OrgMemberStore:
raw_key = values.pop('llm_api_key', None)
agent_settings_diff = values.pop('agent_settings_diff', None)
conversation_settings_diff = values.pop('conversation_settings_diff', None)
+ if agent_settings_diff is not None:
+ agent_settings_diff = dict(agent_settings_diff)
+ for key in MEMBER_PRIVATE_AGENT_KEYS:
+ agent_settings_diff.pop(key, None)
for org_member in org_members:
if raw_key is not None:
org_member.llm_api_key = raw_key
if agent_settings_diff is not None:
- org_member.agent_settings_diff = deep_merge_with_wholesale_keys(
+ org_member.agent_settings_diff = deep_merge(
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 cc12d7d553..414559dc8c 100644
--- a/enterprise/storage/saas_settings_store.py
+++ b/enterprise/storage/saas_settings_store.py
@@ -9,7 +9,10 @@ from pydantic import SecretStr
from server.auth.token_manager import TokenManager
from server.constants import LITE_LLM_API_URL
from server.logger import logger
-from server.routes.org_models import OrgMemberSettingsUpdate
+from server.routes.org_models import (
+ MEMBER_PRIVATE_AGENT_KEYS,
+ OrgMemberSettingsUpdate,
+)
from sqlalchemy import select
from sqlalchemy.orm import joinedload
from storage.agent_profile_resolution import (
@@ -21,7 +24,7 @@ from storage.database import a_session_maker
from storage.lite_llm_manager import LiteLlmManager, get_openhands_cloud_key_alias
from storage.org import Org
from storage.org_member import OrgMember
-from storage.org_member_store import OrgMemberStore
+from storage.org_member_store import OrgMemberStore, serialize_mcp_config
from storage.org_store import OrgStore
from storage.user import User
from storage.user_settings import UserSettings
@@ -31,7 +34,6 @@ from openhands.app_server.settings.llm_profiles import LLMProfiles, resolve_prof
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 (
- WHOLESALE_REPLACEMENT_KEYS,
deep_merge,
deep_merge_with_wholesale_keys,
)
@@ -42,35 +44,6 @@ from openhands.sdk.llm.utils.openhands_provider import (
from openhands.sdk.mcp.config import MCPServer, coerce_mcp_config
from openhands.sdk.profiles import resolve_agent_profile
-# Agent-settings keys private to each org member: never written to
-# org-level defaults nor broadcast across the org. Covers ``mcp_config``
-# (per-user MCP server set, a dict-of-items collection). ACP provider
-# creds are not here β€” they ride the per-user Secrets panel
-# (``request.secrets`` -> ``state.secret_registry``), not agent_settings.
-MEMBER_PRIVATE_AGENT_KEYS: frozenset[str] = WHOLESALE_REPLACEMENT_KEYS
-
-
-def _split_member_private_keys(
- agent_settings_diff: dict[str, Any],
-) -> tuple[dict[str, Any], dict[str, Any]]:
- """Split an agent_settings dump into (shared, private) halves.
-
- The shared half is safe to write to ``org.agent_settings`` and to
- broadcast through ``update_all_members_settings_async``. The private
- half must be applied only to the acting member's row.
- """
- private = {
- key: agent_settings_diff[key]
- for key in MEMBER_PRIVATE_AGENT_KEYS
- if key in agent_settings_diff
- }
- shared = {
- key: value
- for key, value in agent_settings_diff.items()
- if key not in MEMBER_PRIVATE_AGENT_KEYS
- }
- return shared, private
-
@dataclass
class SaasSettingsStore(SettingsStore):
@@ -144,7 +117,16 @@ class SaasSettingsStore(SettingsStore):
@staticmethod
def _get_persisted_agent_settings(item: Settings) -> dict[str, Any]:
- return item.agent_settings.model_dump(mode='json')
+ persisted = item.agent_settings.model_dump(
+ mode='json',
+ exclude={'llm': {'api_key'}},
+ )
+ persisted.pop('mcp_config', None)
+ return persisted
+
+ @staticmethod
+ def _get_persisted_mcp_config(item: Settings) -> dict[str, Any] | None:
+ return serialize_mcp_config(item.agent_settings.mcp_config)
def _resolve_active_agent_profile(
self,
@@ -305,6 +287,8 @@ class SaasSettingsStore(SettingsStore):
return None
org_agent_settings = OrgStore.get_agent_settings_from_org(org)
member_agent_settings_diff = dict(org_member.agent_settings_diff)
+ member_agent_settings_diff.pop('mcp_config', None)
+ member_mcp_config = org_member.effective_mcp_config
kwargs = {
**{
@@ -334,6 +318,8 @@ class SaasSettingsStore(SettingsStore):
org_agent_settings_dump,
member_agent_settings_diff,
)
+ if member_mcp_config is not None:
+ merged_agent_settings['mcp_config'] = member_mcp_config
effective_llm_api_key = self._get_effective_llm_api_key(org, org_member)
if effective_llm_api_key is not None:
merged_agent_settings.setdefault('llm', {})['api_key'] = (
@@ -449,6 +435,7 @@ class SaasSettingsStore(SettingsStore):
kwargs['active_agent_profile_revision'] = resolved_revision
settings = Settings(**kwargs)
+ settings._mcp_config_updated = False
if resolution_requested:
# Launch view (even when resolution fell back): never persistable.
settings._resolved_view = True
@@ -584,15 +571,11 @@ class SaasSettingsStore(SettingsStore):
)
effective_agent_settings_diff = self._get_persisted_agent_settings(item)
-
- # Keep mcp_config scoped to the acting member only.
- # ``shared_agent_settings_diff`` is the slice safe for org-wide
- # state; ``private_agent_settings_diff`` is applied below to the
- # acting member's row only so other members don't inherit one
- # user's MCP servers.
- shared_agent_settings_diff, private_agent_settings_diff = (
- _split_member_private_keys(effective_agent_settings_diff)
- )
+ shared_agent_settings_diff = {
+ key: value
+ for key, value in effective_agent_settings_diff.items()
+ if key not in MEMBER_PRIVATE_AGENT_KEYS
+ }
# Strip any pre-existing private keys from the org dump before
# merging, so legacy values written by older code paths are
@@ -674,14 +657,15 @@ class SaasSettingsStore(SettingsStore):
),
)
- # Member-private keys (mcp_config) live only on the acting
- # member's row. Use the wholesale-replacement semantics so
- # deletes stick (APP-1862).
- if private_agent_settings_diff:
- org_member.agent_settings_diff = deep_merge_with_wholesale_keys(
- dict(org_member.agent_settings_diff),
- private_agent_settings_diff,
- )
+ member_mcp_config = org_member.effective_mcp_config
+ member_agent_settings_diff = dict(org_member.agent_settings_diff)
+ for private_key in MEMBER_PRIVATE_AGENT_KEYS:
+ member_agent_settings_diff.pop(private_key, None)
+ org_member.agent_settings_diff = member_agent_settings_diff
+ if item._mcp_config_updated:
+ org_member.mcp_config = self._get_persisted_mcp_config(item)
+ elif org_member.mcp_config is None and member_mcp_config is not None:
+ org_member.mcp_config = serialize_mcp_config(member_mcp_config)
if uses_managed_llm_key and current_member_llm_api_key is not None:
# Managed/proxy key β€” store on this member but mark as org-managed
diff --git a/enterprise/storage/user_settings.py b/enterprise/storage/user_settings.py
index 362903fce9..09507b9b80 100644
--- a/enterprise/storage/user_settings.py
+++ b/enterprise/storage/user_settings.py
@@ -10,7 +10,11 @@ from sqlalchemy import DateTime, Identity, String
from sqlalchemy.dialects.postgresql import JSON
from sqlalchemy.orm import Mapped, mapped_column
from storage.base import Base
-from storage.encrypt_utils import decrypt_legacy_value, encrypt_legacy_value
+from storage.encrypt_utils import (
+ EncryptedJSON,
+ decrypt_legacy_value,
+ encrypt_legacy_value,
+)
from openhands.app_server.settings.settings_models import MarketplaceRegistration
@@ -50,8 +54,10 @@ class UserSettings(Base):
default_sandbox_spec_id: Mapped[str | None] = mapped_column(String, nullable=True)
user_version: Mapped[int] = mapped_column(nullable=False, default=0)
accepted_tos: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
- # Deprecated (v0): mcp_config now lives inside AgentSettings on Org / OrgMember.
- mcp_config: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
+ # Deprecated (v0): retained only while old users migrate to OrgMember.
+ mcp_config: Mapped[dict[str, Any] | None] = mapped_column(
+ EncryptedJSON, nullable=True
+ )
disabled_skills: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
search_api_key: Mapped[str | None] = mapped_column(String, nullable=True)
sandbox_api_key: Mapped[str | None] = mapped_column(String, nullable=True)
@@ -117,8 +123,14 @@ class UserSettings(Base):
source_name='user settings',
)
- return Settings(
- agent_settings=self.agent_settings or {},
+ agent_settings = dict(self.agent_settings or {})
+ if self.mcp_config is not None:
+ agent_settings['mcp_config'] = self.mcp_config
+
+ settings = Settings(
+ agent_settings=agent_settings,
conversation_settings=self.conversation_settings or {},
registered_marketplaces=marketplaces,
)
+ settings._mcp_config_updated = False
+ return settings
diff --git a/enterprise/storage/user_store.py b/enterprise/storage/user_store.py
index f56a25af3f..0eb690684b 100644
--- a/enterprise/storage/user_store.py
+++ b/enterprise/storage/user_store.py
@@ -569,17 +569,7 @@ class UserStore:
# For new sign-ups after migration, user_settings won't exist
# Fall back to getting data from org_members
if user_settings:
- if org_member.llm_api_key and org_member.llm_api_key.get_secret_value():
- user_settings.llm_api_key = encrypt_legacy_value(
- org_member.llm_api_key.get_secret_value()
- )
- if (
- org_member.llm_api_key_for_byor
- and org_member.llm_api_key_for_byor.get_secret_value()
- ):
- user_settings.llm_api_key_for_byor = encrypt_legacy_value(
- org_member.llm_api_key_for_byor.get_secret_value()
- )
+ UserStore._sync_user_settings_from_org_member(user_settings, org_member)
logger.info(
'user_store:downgrade_user:updated_user_settings_from_org_member',
extra={'user_id': user_id},
@@ -1224,6 +1214,23 @@ class UserStore:
}
return kwargs
+ @staticmethod
+ def _sync_user_settings_from_org_member(
+ user_settings: UserSettings, org_member: OrgMember
+ ) -> None:
+ user_settings.mcp_config = org_member.effective_mcp_config
+ if org_member.llm_api_key and org_member.llm_api_key.get_secret_value():
+ user_settings.llm_api_key = encrypt_legacy_value(
+ org_member.llm_api_key.get_secret_value()
+ )
+ if (
+ org_member.llm_api_key_for_byor
+ and org_member.llm_api_key_for_byor.get_secret_value()
+ ):
+ user_settings.llm_api_key_for_byor = encrypt_legacy_value(
+ org_member.llm_api_key_for_byor.get_secret_value()
+ )
+
@staticmethod
def _create_user_settings_from_entities(
user_id: str, org_member: OrgMember, user: User, org: Org
@@ -1246,9 +1253,13 @@ class UserStore:
from storage.org_store import OrgStore
member_agent_settings_diff = dict(org_member.agent_settings_diff)
+ member_agent_settings_diff.pop('mcp_config', None)
+ member_mcp_config = org_member.effective_mcp_config
org_agent_settings = OrgStore.get_agent_settings_from_org(org)
+ org_agent_settings_dump = org_agent_settings.model_dump(mode='json')
+ org_agent_settings_dump.pop('mcp_config', None)
agent_settings = {
- **org_agent_settings.model_dump(mode='json'),
+ **org_agent_settings_dump,
**member_agent_settings_diff,
}
@@ -1291,6 +1302,7 @@ class UserStore:
v1_enabled=org.v1_enabled,
sandbox_grouping_strategy=org.sandbox_grouping_strategy,
agent_settings=agent_settings,
+ mcp_config=member_mcp_config,
conversation_settings=conversation_settings,
already_migrated=False,
)
diff --git a/enterprise/tests/unit/test_agent_profiles.py b/enterprise/tests/unit/test_agent_profiles.py
index dfe5290b40..e62b03220e 100644
--- a/enterprise/tests/unit/test_agent_profiles.py
+++ b/enterprise/tests/unit/test_agent_profiles.py
@@ -155,7 +155,8 @@ def test_load_agent_profiles_defaults_empty_and_degrades():
def test_member_mcp_config_degrades_on_non_validation_error():
"""coerce_mcp_config failures beyond ValidationError degrade to {}, not raise."""
member = MagicMock(spec=OrgMember)
- member.agent_settings_diff = {'mcp_config': {'mcpServers': {}}}
+ member.mcp_config = {'mcpServers': {}}
+ member.agent_settings_diff = {}
with patch(
'storage.agent_profile_resolution.coerce_mcp_config',
side_effect=TypeError('contract drift'),
@@ -836,8 +837,8 @@ class TestPersistedVsResolvedSettingsView:
'model': 'gpt-4o',
'base_url': 'https://api.openai.com/v1',
},
- 'mcp_config': {'mcpServers': dict(MEMBER_MCP_SERVERS)},
}
+ member.mcp_config = dict(MEMBER_MCP_SERVERS)
await session.commit()
return profile
@@ -888,7 +889,7 @@ class TestPersistedVsResolvedSettingsView:
await store.store(settings)
member = await _read_member(async_session_maker, org_id, USER_ID)
- stored_mcp = member.agent_settings_diff.get('mcp_config') or {}
+ stored_mcp = member.mcp_config or {}
assert set(stored_mcp) == {'a', 'b', 'c'}
@pytest.mark.asyncio
diff --git a/enterprise/tests/unit/test_migration_137_encrypt_member_mcp_config.py b/enterprise/tests/unit/test_migration_137_encrypt_member_mcp_config.py
new file mode 100644
index 0000000000..0e36b8e341
--- /dev/null
+++ b/enterprise/tests/unit/test_migration_137_encrypt_member_mcp_config.py
@@ -0,0 +1,340 @@
+import json
+from copy import deepcopy
+from datetime import UTC, datetime
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from uuid import uuid4
+
+import sqlalchemy as sa
+from alembic.migration import MigrationContext
+from alembic.operations import Operations
+from pydantic import SecretStr
+
+from openhands.app_server.services.jwt_service import JwtService
+from openhands.app_server.utils.encryption_key import EncryptionKey
+
+MIGRATION_PATH = (
+ Path(__file__).resolve().parents[2]
+ / 'migrations'
+ / 'versions'
+ / '137_encrypt_member_mcp_config.py'
+)
+spec = spec_from_file_location('migration_137', MIGRATION_PATH)
+assert spec is not None and spec.loader is not None
+migration_137 = module_from_spec(spec)
+spec.loader.exec_module(migration_137)
+
+
+def _json_object(value):
+ return json.loads(value) if isinstance(value, str) else value
+
+
+def test_bearer_token_skips_malformed_authorization_values():
+ assert (
+ migration_137._mcp_bearer_token(
+ {
+ 'headers': {
+ 'AUTHORIZATION': None,
+ 'Authorization': 'Bearer real-key',
+ }
+ }
+ )
+ == 'real-key'
+ )
+
+
+def test_recovery_preserves_non_bearer_auth_shape():
+ recovered = migration_137._recover_redacted_mcp_config(
+ {
+ 'server': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {'strategy': 'bearer', 'value': '**********'},
+ }
+ },
+ {
+ 'server': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {
+ 'strategy': 'api_key',
+ 'value': 'real-key',
+ 'header_name': 'X-API-Key',
+ },
+ }
+ },
+ )
+
+ assert recovered['server']['auth'] == {
+ 'strategy': 'api_key',
+ 'value': 'real-key',
+ 'header_name': 'X-API-Key',
+ }
+
+
+def test_recovery_preserves_typed_bearer_from_scalar_redaction():
+ recovered = migration_137._recover_redacted_mcp_config(
+ {
+ 'server': {
+ 'url': 'https://mcp.example.com',
+ 'auth': '**********',
+ }
+ },
+ {
+ 'server': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {'strategy': 'bearer', 'value': 'real-key'},
+ }
+ },
+ )
+
+ assert recovered['server']['auth'] == {
+ 'strategy': 'bearer',
+ 'value': 'real-key',
+ }
+
+
+def test_recovery_preserves_typed_basic_from_scalar_redaction():
+ recovered = migration_137._recover_redacted_mcp_config(
+ {
+ 'server': {
+ 'url': 'https://mcp.example.com',
+ 'auth': '**********',
+ }
+ },
+ {
+ 'server': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {
+ 'strategy': 'basic',
+ 'username': 'user',
+ 'password': 'real-key',
+ },
+ }
+ },
+ )
+
+ assert recovered['server']['auth'] == {
+ 'strategy': 'basic',
+ 'username': 'user',
+ 'password': 'real-key',
+ }
+
+
+def test_upgrade_encrypts_and_moves_legacy_mcp_config(monkeypatch):
+ engine = sa.create_engine('sqlite://')
+ metadata = sa.MetaData()
+ org_member = sa.Table(
+ 'org_member',
+ metadata,
+ sa.Column('org_id', sa.Uuid(), primary_key=True),
+ sa.Column('user_id', sa.Uuid(), primary_key=True),
+ sa.Column('agent_settings_diff', sa.JSON(), nullable=False),
+ )
+ user_settings = sa.Table(
+ 'user_settings',
+ metadata,
+ sa.Column('id', sa.Integer(), primary_key=True),
+ sa.Column('keycloak_user_id', sa.String()),
+ sa.Column('already_migrated', sa.Boolean()),
+ sa.Column('agent_settings', sa.JSON(), nullable=False),
+ sa.Column('mcp_config', sa.JSON()),
+ )
+ org = sa.Table(
+ 'org',
+ metadata,
+ sa.Column('id', sa.Uuid(), primary_key=True),
+ sa.Column('agent_settings', sa.JSON(), nullable=False),
+ )
+ metadata.create_all(engine)
+
+ member_secret = 'member-mcp-secret'
+ legacy_secret = 'legacy-user-mcp-secret'
+ legacy_stdio_secret = 'legacy-stdio-secret'
+ redacted_config = {
+ 'integration-hub': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': '**********'},
+ },
+ 'local': {
+ 'command': 'local-mcp',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': '**********'},
+ },
+ 'changed-endpoint': {
+ 'url': 'https://new.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': '**********'},
+ },
+ }
+ member_config = {
+ 'server': {
+ 'url': 'https://mcp.example.com',
+ 'headers': {'Authorization': f'Bearer {member_secret}'},
+ },
+ **deepcopy(redacted_config),
+ }
+ legacy_config = {
+ 'integration-hub': {
+ 'url': 'https://integration.example.com/mcp',
+ 'headers': {'Authorization': f'Bearer {legacy_secret}'},
+ },
+ 'local': {
+ 'command': 'local-mcp',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': legacy_stdio_secret},
+ },
+ 'changed-endpoint': {
+ 'url': 'https://old.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': legacy_secret},
+ },
+ }
+ recovered_config = {
+ 'integration-hub': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': legacy_secret},
+ },
+ 'local': {
+ 'command': 'local-mcp',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': legacy_stdio_secret},
+ },
+ 'changed-endpoint': {
+ 'url': 'https://new.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': '**********'},
+ },
+ }
+ user_id = uuid4()
+ org_id = user_id
+ other_org_id = uuid4()
+
+ jwt_service = JwtService(
+ [
+ EncryptionKey(
+ id='migration-test-key',
+ key=SecretStr('migration-test-secret'),
+ created_at=datetime(2026, 1, 1, tzinfo=UTC),
+ )
+ ]
+ )
+ import storage.encrypt_utils as encrypt_utils
+
+ monkeypatch.setattr(encrypt_utils, '_jwt_service', jwt_service)
+
+ with engine.begin() as connection:
+ connection.execute(
+ org_member.insert(),
+ [
+ {
+ 'org_id': org_id,
+ 'user_id': user_id,
+ 'agent_settings_diff': {
+ 'llm': {},
+ 'mcp_config': member_config,
+ },
+ },
+ {
+ 'org_id': other_org_id,
+ 'user_id': user_id,
+ 'agent_settings_diff': {
+ 'llm': {},
+ 'mcp_config': member_config,
+ },
+ },
+ ],
+ )
+ connection.execute(
+ user_settings.insert().values(
+ id=1,
+ keycloak_user_id=str(user_id),
+ already_migrated=True,
+ agent_settings={'llm': {}, 'mcp_config': redacted_config},
+ mcp_config=legacy_config,
+ )
+ )
+ connection.execute(
+ org.insert().values(
+ id=org_id,
+ agent_settings={'mcp_config': member_config},
+ )
+ )
+
+ context = MigrationContext.configure(connection)
+ monkeypatch.setattr(migration_137, 'op', Operations(context))
+ migration_137.upgrade()
+
+ upgraded_member = sa.Table(
+ 'org_member', sa.MetaData(), autoload_with=connection
+ )
+ member_row = (
+ connection.execute(
+ sa.select(
+ upgraded_member.c.agent_settings_diff,
+ upgraded_member.c.mcp_config,
+ ).where(upgraded_member.c.org_id == org_id)
+ )
+ .mappings()
+ .one()
+ )
+ other_member_row = (
+ connection.execute(
+ sa.select(upgraded_member.c.mcp_config).where(
+ upgraded_member.c.org_id == other_org_id
+ )
+ )
+ .mappings()
+ .one()
+ )
+ legacy_row = (
+ connection.execute(
+ sa.text('SELECT agent_settings, mcp_config FROM user_settings')
+ )
+ .mappings()
+ .one()
+ )
+ org_row = (
+ connection.execute(sa.text('SELECT agent_settings FROM org'))
+ .mappings()
+ .one()
+ )
+
+ assert member_secret not in member_row['mcp_config']
+ assert legacy_secret not in legacy_row['mcp_config']
+ assert legacy_stdio_secret not in legacy_row['mcp_config']
+ recovered_member_config = {
+ 'server': member_config['server'],
+ **recovered_config,
+ }
+ assert (
+ migration_137._decrypt_json(member_row['mcp_config'])
+ == recovered_member_config
+ )
+ assert migration_137._decrypt_json(legacy_row['mcp_config']) == recovered_config
+ assert (
+ migration_137._decrypt_json(other_member_row['mcp_config']) == member_config
+ )
+ assert 'mcp_config' not in _json_object(member_row['agent_settings_diff'])
+ assert 'mcp_config' not in _json_object(legacy_row['agent_settings'])
+ assert 'mcp_config' not in _json_object(org_row['agent_settings'])
+
+ migration_137.downgrade()
+
+ downgraded_member = sa.Table(
+ 'org_member', sa.MetaData(), autoload_with=connection
+ )
+ restored_member = connection.execute(
+ sa.select(downgraded_member.c.agent_settings_diff).where(
+ downgraded_member.c.org_id == org_id
+ )
+ ).scalar_one()
+ restored_user = (
+ connection.execute(
+ sa.text('SELECT agent_settings, mcp_config FROM user_settings')
+ )
+ .mappings()
+ .one()
+ )
+
+ assert _json_object(restored_member)['mcp_config'] == recovered_member_config
+ assert (
+ _json_object(restored_user['agent_settings'])['mcp_config']
+ == recovered_config
+ )
+ assert _json_object(restored_user['mcp_config']) == recovered_config
diff --git a/enterprise/tests/unit/test_org_member_store.py b/enterprise/tests/unit/test_org_member_store.py
index 6b0aea0ebd..775f836f69 100644
--- a/enterprise/tests/unit/test_org_member_store.py
+++ b/enterprise/tests/unit/test_org_member_store.py
@@ -28,6 +28,9 @@ def test_get_kwargs_from_user_settings_uses_agent_settings_as_source_of_truth():
'enabled': False,
'max_size': 128,
},
+ 'mcp_config': {
+ 'private': {'url': 'https://mcp.example.com'},
+ },
},
conversation_settings={
'confirmation_mode': True,
@@ -47,6 +50,8 @@ def test_get_kwargs_from_user_settings_uses_agent_settings_as_source_of_truth():
assert kwargs['agent_settings_diff']['llm']['base_url'] == 'https://api.example.com'
assert kwargs['agent_settings_diff']['condenser']['enabled'] is False
assert kwargs['agent_settings_diff']['condenser']['max_size'] == 128
+ assert 'mcp_config' not in kwargs['agent_settings_diff']
+ assert kwargs['mcp_config'] == {'private': {'url': 'https://mcp.example.com'}}
assert kwargs['conversation_settings_diff']['confirmation_mode'] is True
assert kwargs['conversation_settings_diff']['security_analyzer'] == 'llm'
assert kwargs['conversation_settings_diff']['max_iterations'] == 42
@@ -1158,17 +1163,10 @@ async def test_update_all_members_settings_async_with_empty_settings(
@pytest.mark.asyncio
-async def test_update_all_members_settings_async_replaces_mcp_config(
+async def test_update_all_members_settings_async_does_not_replace_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.
- """
+ """Ignore member-private MCP config in bulk updates."""
from server.routes.org_models import OrgMemberSettingsUpdate
# Arrange - Create org with member that has 3 MCP servers
@@ -1190,14 +1188,11 @@ async def test_update_all_members_settings_async_replaces_mcp_config(
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'},
- },
- },
+ agent_settings_diff={},
+ mcp_config={
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ 'server2': {'url': 'https://server2.com', 'transport': 'sse'},
+ 'server3': {'url': 'https://server3.com', 'transport': 'sse'},
},
status='active',
)
@@ -1224,7 +1219,6 @@ async def test_update_all_members_settings_async_replaces_mcp_config(
)
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
@@ -1233,28 +1227,19 @@ async def test_update_all_members_settings_async_replaces_mcp_config(
)
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)}'
+ mcp_servers = member.mcp_config or {}
+ assert 'mcp_config' not in member.agent_settings_diff
+ assert len(mcp_servers) == 3
assert 'server1' in mcp_servers
assert 'server2' in mcp_servers
- assert 'server3' not in mcp_servers, (
- 'Deleted server was resurrected by deep_merge'
- )
+ assert 'server3' in mcp_servers
@pytest.mark.asyncio
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.
- """
+ """Preserve MCP servers when an update omits the field."""
from server.routes.org_models import OrgMemberSettingsUpdate
# Arrange - Create org with member that has MCP servers
@@ -1276,12 +1261,10 @@ async def test_update_all_members_settings_async_mcp_config_not_in_payload(
user_id=user.id,
role_id=role.id,
llm_api_key='test-key',
+ mcp_config={
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ },
agent_settings_diff={
- 'mcp_config': {
- 'mcpServers': {
- 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
- },
- },
'llm': {'model': 'old-model'},
},
status='active',
@@ -1315,22 +1298,16 @@ async def test_update_all_members_settings_async_mcp_config_not_in_payload(
# 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', {})
+ assert member.mcp_config is not None
+ assert 'server1' in member.mcp_config
+ assert 'mcp_config' not in member.agent_settings_diff
@pytest.mark.asyncio
-async def test_update_all_members_settings_async_empty_mcp_config(
+async def test_update_all_members_settings_async_does_not_clear_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.
- """
+ """Ignore an empty MCP config in bulk updates."""
from server.routes.org_models import OrgMemberSettingsUpdate
# Arrange - Create org with member that has MCP servers
@@ -1352,13 +1329,10 @@ async def test_update_all_members_settings_async_empty_mcp_config(
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'},
- },
- },
+ agent_settings_diff={},
+ mcp_config={
+ 'server1': {'url': 'https://server1.com', 'transport': 'sse'},
+ 'server2': {'url': 'https://server2.com', 'transport': 'sse'},
},
status='active',
)
@@ -1381,7 +1355,6 @@ async def test_update_all_members_settings_async_empty_mcp_config(
)
await session.commit()
- # Assert - mcp_config should be empty
async with async_session_maker() as session:
from sqlalchemy import select
@@ -1390,22 +1363,16 @@ async def test_update_all_members_settings_async_empty_mcp_config(
)
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)}'
+ mcp_servers = member.mcp_config or {}
+ assert 'mcp_config' not in member.agent_settings_diff
+ assert len(mcp_servers) == 2
@pytest.mark.asyncio
-async def test_update_all_members_settings_async_add_first_mcp_server(
+async def test_update_all_members_settings_async_does_not_add_mcp_config(
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.
- """
+ """Do not add member-private MCP config in a bulk update."""
from server.routes.org_models import OrgMemberSettingsUpdate
# Arrange - Create org with member that has NO mcp_config
@@ -1454,7 +1421,6 @@ async def test_update_all_members_settings_async_add_first_mcp_server(
)
await session.commit()
- # Assert - Server should be added
async with async_session_maker() as session:
from sqlalchemy import select
@@ -1463,23 +1429,16 @@ async def test_update_all_members_settings_async_add_first_mcp_server(
)
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
+ mcp_servers = member.mcp_config or {}
+ assert 'mcp_config' not in member.agent_settings_diff
+ assert not mcp_servers
@pytest.mark.asyncio
-async def test_update_all_members_settings_async_update_server_url(
+async def test_update_all_members_settings_async_does_not_update_mcp_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.
- """
+ """Keep member-private MCP endpoints unchanged in bulk updates."""
from server.routes.org_models import OrgMemberSettingsUpdate
# Arrange
@@ -1501,14 +1460,11 @@ async def test_update_all_members_settings_async_update_server_url(
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',
- },
- },
+ agent_settings_diff={},
+ mcp_config={
+ 'myserver': {
+ 'url': 'https://old-url.com',
+ 'transport': 'sse',
},
},
status='active',
@@ -1537,7 +1493,6 @@ async def test_update_all_members_settings_async_update_server_url(
)
await session.commit()
- # Assert - URL should be updated
async with async_session_maker() as session:
from sqlalchemy import select
@@ -1546,7 +1501,7 @@ async def test_update_all_members_settings_async_update_server_url(
)
member = result.scalars().first()
- mcp_config = member.agent_settings_diff.get('mcp_config', {})
- mcp_servers = mcp_config.get('mcpServers', {})
+ mcp_servers = member.mcp_config or {}
+ assert 'mcp_config' not in member.agent_settings_diff
assert len(mcp_servers) == 1
- assert mcp_servers['myserver']['url'] == 'https://new-url.com'
+ assert mcp_servers['myserver']['url'] == 'https://old-url.com'
diff --git a/enterprise/tests/unit/test_org_store.py b/enterprise/tests/unit/test_org_store.py
index 6b7a526f6f..191bebf59f 100644
--- a/enterprise/tests/unit/test_org_store.py
+++ b/enterprise/tests/unit/test_org_store.py
@@ -1549,6 +1549,92 @@ async def test_update_org_defaults_async_non_key_changes_keep_custom_key_flags()
assert member_settings.has_custom_llm_api_key is None
+async def test_update_org_defaults_async_does_not_broadcast_mcp_config(
+ async_session_maker,
+):
+ async with async_session_maker() as session:
+ org = Org(
+ name='test-org',
+ agent_settings=OpenHandsAgentSettings(
+ llm={'model': 'old-model'}
+ ).model_dump(mode='json'),
+ )
+ role = Role(name='member', rank=2)
+ session.add_all([org, role])
+ await session.flush()
+
+ users = [
+ User(
+ id=uuid.uuid4(),
+ current_org_id=org.id,
+ email=f'user{i}@example.com',
+ )
+ for i in range(2)
+ ]
+ session.add_all(users)
+ await session.flush()
+ session.add_all(
+ [
+ OrgMember(
+ org_id=org.id,
+ user_id=user.id,
+ role_id=role.id,
+ llm_api_key='test-key',
+ mcp_config={f'private-{i}': {'url': f'https://mcp{i}.example.com'}},
+ status='active',
+ )
+ for i, user in enumerate(users)
+ ]
+ )
+ org_id = org.id
+ user_ids = [user.id for user in users]
+ await session.commit()
+ acting_user_id = str(user_ids[0])
+
+ update_data = OrgUpdate(
+ agent_settings_diff={
+ 'llm': {'model': 'new-model'},
+ 'mcp_config': {
+ 'admin': {
+ 'url': 'https://admin.example.com',
+ 'auth': {'strategy': 'bearer', 'value': 'admin-secret'},
+ }
+ },
+ }
+ )
+ assert update_data.agent_settings_diff == {'llm': {'model': 'new-model'}}
+
+ with (
+ patch('storage.org_store.a_session_maker', async_session_maker),
+ patch(
+ 'storage.org_store.OrgStore._maybe_get_managed_llm_key_for_user',
+ AsyncMock(return_value=None),
+ ),
+ ):
+ updated_org = await OrgStore.update_org_defaults_async(
+ org_id,
+ update_data,
+ acting_user_id,
+ )
+
+ assert updated_org is not None
+ assert not updated_org.agent_settings.get('mcp_config')
+ async with async_session_maker() as session:
+ result = await session.execute(
+ select(OrgMember).where(OrgMember.org_id == org_id)
+ )
+ members = {member.user_id: member for member in result.scalars().all()}
+
+ for i, user_id in enumerate(user_ids):
+ member = members[user_id]
+ assert member.mcp_config == {
+ f'private-{i}': {'url': f'https://mcp{i}.example.com'}
+ }
+ assert 'mcp_config' not in member.agent_settings_diff
+ assert member.agent_settings_diff['llm']['model'] == 'new-model'
+
+
@pytest.mark.asyncio
async def test_update_org_defaults_async_org_not_found():
"""GIVEN: Non-existent organization ID
diff --git a/enterprise/tests/unit/test_saas_settings_store.py b/enterprise/tests/unit/test_saas_settings_store.py
index 52b891c659..e2a6297020 100644
--- a/enterprise/tests/unit/test_saas_settings_store.py
+++ b/enterprise/tests/unit/test_saas_settings_store.py
@@ -108,6 +108,36 @@ def test_member_settings_persist_full_effective_agent_settings():
assert settings.conversation_settings.security_analyzer == 'llm'
+def test_persisted_mcp_config_exposes_only_mcp_secrets():
+ settings = Settings(
+ agent_settings={
+ 'llm': {'model': 'test-model', 'api_key': 'llm-key'},
+ 'mcp_config': {
+ 'remote': {
+ 'url': 'https://mcp.example.com',
+ 'headers': {'Authorization': 'Bearer mcp-key'},
+ },
+ 'local': {
+ 'command': 'mcp-server',
+ 'env': {'API_KEY': 'mcp-env-key'},
+ },
+ },
+ }
+ )
+
+ persisted = SaasSettingsStore._get_persisted_agent_settings(settings)
+ persisted_mcp = SaasSettingsStore._get_persisted_mcp_config(settings)
+
+ assert 'api_key' not in persisted['llm']
+ assert 'mcp_config' not in persisted
+ assert persisted_mcp is not None
+ assert persisted_mcp['remote']['auth'] == {
+ 'strategy': 'bearer',
+ 'value': 'mcp-key',
+ }
+ assert persisted_mcp['local']['env'] == {'API_KEY': 'mcp-env-key'}
+
+
@pytest.fixture
def settings_store(async_session_maker):
store = SaasSettingsStore('5594c7b6-f959-4b81-92e9-b09c206f5081')
@@ -831,10 +861,10 @@ async def test_store_keeps_mcp_config_private_to_acting_member(
}
assert 'mcp_config' not in org.agent_settings
- assert (
- members[admin_user_id].agent_settings_diff.get('mcp_config')
- == persisted_mcp_config
- )
+ assert members[admin_user_id].mcp_config == persisted_mcp_config
+ assert 'mcp_config' not in members[admin_user_id].agent_settings_diff
+ assert members[member1_user_id].mcp_config is None
+ assert members[member2_user_id].mcp_config is None
assert 'mcp_config' not in members[member1_user_id].agent_settings_diff
assert 'mcp_config' not in members[member2_user_id].agent_settings_diff
@@ -918,14 +948,17 @@ async def test_store_calls_ensure_api_key_when_base_url_is_litellm_proxy(
async def test_store_and_load_mcp_config_via_agent_settings(
async_session_maker, org_with_multiple_members_fixture
):
- """mcp_config is persisted inside agent_settings / agent_settings_diff and
- round-trips correctly through store β†’ load."""
+ """MCP config round-trips through encrypted member storage."""
fixture = org_with_multiple_members_fixture
admin_user_id = str(fixture['admin_user_id'])
admin_mcp_config = {
'mcpServers': {
- 'admin': {'url': 'https://admin-private-server.com', 'transport': 'sse'}
+ 'admin': {
+ 'url': 'https://admin-private-server.com',
+ 'transport': 'sse',
+ 'headers': {'Authorization': 'Bearer admin-secret'},
+ }
},
}
@@ -961,6 +994,65 @@ async def test_store_and_load_mcp_config_via_agent_settings(
loaded.agent_settings.mcp_config['admin'].url
== 'https://admin-private-server.com'
)
+ auth = loaded.agent_settings.mcp_config['admin'].auth
+ assert auth is not None
+ assert auth.to_http_headers() == {'Authorization': 'Bearer admin-secret'}
+
+
+async def test_mcp_config_is_encrypted_at_rest(
+ async_session_maker, org_with_multiple_members_fixture
+):
+ """Keep MCP credentials out of raw database values."""
+ import json
+
+ from sqlalchemy import select, text
+ from storage.org_member import OrgMember
+
+ admin_user_id = org_with_multiple_members_fixture['admin_user_id']
+ settings = DataSettings(
+ agent_settings={
+ 'llm': {
+ 'model': 'test-model',
+ 'base_url': 'http://non-litellm-url.com',
+ 'api_key': 'test-api-key',
+ },
+ 'mcp_config': {
+ 'private': {
+ 'url': 'https://mcp.example.com',
+ 'headers': {'Authorization': 'Bearer database-secret'},
+ }
+ },
+ }
+ )
+ store = SaasSettingsStore(str(admin_user_id))
+
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await store.store(settings)
+
+ async with async_session_maker() as session:
+ rows = (
+ await session.execute(text('SELECT user_id, mcp_config FROM org_member'))
+ ).all()
+ raw = next(
+ value
+ for user_id, value in rows
+ if str(user_id).replace('-', '') == admin_user_id.hex
+ )
+ member = (
+ await session.execute(
+ select(OrgMember).where(OrgMember.user_id == admin_user_id)
+ )
+ ).scalar_one()
+
+ assert 'database-secret' not in raw
+ with pytest.raises(json.JSONDecodeError):
+ json.loads(raw)
+ assert member.mcp_config is not None
+ assert member.mcp_config['private']['auth'] == {
+ 'strategy': 'bearer',
+ 'value': 'database-secret',
+ }
@pytest.mark.asyncio
@@ -1274,6 +1366,106 @@ async def test_llm_profiles_are_encrypted_at_rest(
assert user.llm_profiles['profiles']['work']['api_key'] == 'super-secret-byok'
+async def test_partial_settings_store_preserves_existing_mcp_config(
+ session_maker, async_session_maker, org_with_multiple_members_fixture
+):
+ from sqlalchemy import select
+ from storage.org_member import OrgMember
+
+ admin_user_id = str(org_with_multiple_members_fixture['admin_user_id'])
+ org_id = org_with_multiple_members_fixture['org_id']
+ store = SaasSettingsStore(admin_user_id)
+
+ initial_settings = _make_settings(
+ model='test-model',
+ base_url='http://test-url.com',
+ api_key='test-key',
+ mcp_config={
+ 'integration-hub': {
+ 'url': 'https://mcp.example.com',
+ 'headers': {'Authorization': 'Bearer secret'},
+ }
+ },
+ )
+ partial_settings = _make_settings(
+ model='updated-model',
+ base_url='http://test-url.com',
+ api_key='updated-key',
+ )
+
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await store.store(initial_settings)
+ await store.store(partial_settings)
+
+ with session_maker() as session:
+ member = session.execute(
+ select(OrgMember)
+ .where(OrgMember.org_id == org_id)
+ .where(
+ OrgMember.user_id == org_with_multiple_members_fixture['admin_user_id']
+ )
+ ).scalar_one()
+
+ assert member.mcp_config == {
+ 'integration-hub': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {'strategy': 'bearer', 'value': 'secret'},
+ }
+ }
+
+
+async def test_partial_store_migrates_legacy_member_mcp_config(
+ session_maker, async_session_maker, org_with_multiple_members_fixture
+):
+ from sqlalchemy import select
+ from storage.org_member import OrgMember
+
+ fixture = org_with_multiple_members_fixture
+ org_id = fixture['org_id']
+ admin_user_id = fixture['admin_user_id']
+ legacy_config = {
+ 'integration-hub': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {'strategy': 'bearer', 'value': 'legacy-secret'},
+ }
+ }
+ async with async_session_maker() as session:
+ member = (
+ await session.execute(
+ select(OrgMember)
+ .where(OrgMember.org_id == org_id)
+ .where(OrgMember.user_id == admin_user_id)
+ )
+ ).scalar_one()
+ member.mcp_config = None
+ member.agent_settings_diff = {
+ **member.agent_settings_diff,
+ 'mcp_config': legacy_config,
+ }
+ await session.commit()
+
+ settings = _make_settings(
+ model='updated-model',
+ base_url='http://test-url.com',
+ api_key='updated-key',
+ )
+ store = SaasSettingsStore(str(admin_user_id))
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await store.store(settings)
+
+ with session_maker() as session:
+ member = session.execute(
+ select(OrgMember)
+ .where(OrgMember.org_id == org_id)
+ .where(OrgMember.user_id == admin_user_id)
+ ).scalar_one()
+
+ assert member.mcp_config == legacy_config
+ assert 'mcp_config' not in member.agent_settings_diff
+
+
@pytest.mark.asyncio
async def test_store_replaces_mcp_config_on_delete(
session_maker, async_session_maker, org_with_multiple_members_fixture
@@ -1355,8 +1547,10 @@ async def test_store_replaces_mcp_config_on_delete(
# The persisted ``mcp_config`` is the SDK 1.31.x flat server map (no
# ``mcpServers`` wrapper), so reach directly into it instead of going
# through the legacy wrapper key.
- admin_servers = members[admin_user_id].agent_settings_diff.get('mcp_config', {})
+ admin_servers = members[admin_user_id].mcp_config or {}
assert set(admin_servers.keys()) == {'server1', 'server2'}
+ assert 'mcp_config' not in members[admin_user_id].agent_settings_diff
+ assert members[member1_user_id].mcp_config is None
assert 'mcp_config' not in members[member1_user_id].agent_settings_diff
diff --git a/enterprise/tests/unit/test_user_store.py b/enterprise/tests/unit/test_user_store.py
index 48b7e874c2..f50a628186 100644
--- a/enterprise/tests/unit/test_user_store.py
+++ b/enterprise/tests/unit/test_user_store.py
@@ -1120,6 +1120,13 @@ def test_create_user_settings_from_entities():
'base_url': 'https://api.example.com',
},
}
+ org_member.mcp_config = {
+ 'private': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {'strategy': 'bearer', 'value': 'mcp-secret'},
+ }
+ }
+ org_member.effective_mcp_config = org_member.mcp_config
org_member.conversation_settings_diff = {
'max_iterations': 50,
}
@@ -1161,6 +1168,8 @@ def test_create_user_settings_from_entities():
assert result.agent_settings['llm']['model'] == 'claude-3-5-sonnet'
assert result.agent_settings['llm']['base_url'] == 'https://api.example.com'
assert result.agent_settings['agent'] == 'CodeActAgent'
+ assert 'mcp_config' not in result.agent_settings
+ assert result.mcp_config == org_member.mcp_config
assert result.conversation_settings['security_analyzer'] == 'llm'
assert result.conversation_settings['max_iterations'] == 50
assert result.language == 'en'
@@ -1175,6 +1184,8 @@ def test_create_user_settings_from_entities_with_org_fallback():
org_member = MagicMock()
org_member.llm_api_key = None
org_member.agent_settings_diff = {}
+ org_member.mcp_config = None
+ org_member.effective_mcp_config = None
org_member.conversation_settings_diff = {}
user = MagicMock()
@@ -1229,6 +1240,45 @@ def test_create_user_settings_from_entities_with_org_fallback():
assert result.search_api_key == 'search-key'
+def test_user_settings_to_settings_is_not_a_live_mcp_update():
+ from storage.user_settings import UserSettings
+
+ user_settings = UserSettings(
+ keycloak_user_id='test-user',
+ agent_settings={},
+ mcp_config={'server': {'url': 'https://mcp.example.com'}},
+ )
+
+ settings = user_settings.to_settings()
+
+ assert settings.agent_settings.mcp_config is not None
+ assert settings._mcp_config_updated is False
+
+
+def test_sync_user_settings_from_org_member_updates_mcp_config():
+ from storage.user_settings import UserSettings
+
+ current_mcp_config = {
+ 'current': {
+ 'url': 'https://mcp.example.com',
+ 'auth': {'strategy': 'bearer', 'value': 'current-secret'},
+ }
+ }
+ user_settings = UserSettings(
+ keycloak_user_id='test-user',
+ mcp_config={'stale': {'url': 'https://stale.example.com'}},
+ )
+ org_member = MagicMock(
+ effective_mcp_config=current_mcp_config,
+ llm_api_key=None,
+ llm_api_key_for_byor=None,
+ )
+
+ UserStore._sync_user_settings_from_org_member(user_settings, org_member)
+
+ assert user_settings.mcp_config == current_mcp_config
+
+
# --- Tests for Redis lock functions (mocked) ---
diff --git a/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
index 2d1050c573..c6175b632a 100644
--- a/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
+++ b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
@@ -6,6 +6,7 @@ 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";
+import type { Settings } from "#/types/settings";
describe("MCP Server Mutation Hooks", () => {
beforeEach(() => {
@@ -282,6 +283,219 @@ describe("MCP Server Mutation Hooks", () => {
const savedConfig = savedPayload.agent_settings_diff.mcp_config;
const serverUrls = Object.values(savedConfig).map((s) => s.url);
expect(serverUrls).toContain("https://new-url.com");
+ expect(savedConfig).toHaveProperty("myserver");
+ });
+
+ it("removes a cleared SHTTP timeout", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ myserver: {
+ url: "https://server.example.com",
+ timeout: 45,
+ },
+ },
+ },
+ } as unknown as Settings);
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+ const { result } = renderHook(() => useUpdateMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ serverId: "shttp-0",
+ server: { type: "shttp", url: "https://server.example.com" },
+ });
+
+ await waitFor(() => expect(result.current.isSuccess).toBe(true));
+ const payload = saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: {
+ mcp_config: Record<string, { timeout?: number }>;
+ };
+ };
+ expect(
+ payload.agent_settings_diff.mcp_config.myserver,
+ ).not.toHaveProperty("timeout");
+ });
+
+ it("sends explicit null when removing remote auth", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ myserver: {
+ url: "https://server.example.com",
+ auth: { strategy: "bearer", value: "**********" },
+ },
+ },
+ },
+ } as unknown as Settings);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+ const { result } = renderHook(() => useUpdateMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ serverId: "shttp-0",
+ server: {
+ type: "shttp",
+ url: "https://server.example.com",
+ },
+ });
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ const savedPayload = saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: {
+ mcp_config: Record<string, { auth?: unknown }>;
+ };
+ };
+ const savedConfig = savedPayload.agent_settings_diff.mcp_config;
+ expect(savedConfig.myserver).toHaveProperty("auth", null);
+ });
+
+ it.each([
+ {
+ strategy: "basic",
+ username: "user",
+ password: "**********",
+ },
+ {
+ strategy: "header",
+ headers: { "X-API-Key": "**********" },
+ },
+ {
+ strategy: "oauth2",
+ state: { tokens: { access_token: "**********" } },
+ },
+ ])("preserves $strategy auth on unrelated edits", async (auth) => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ myserver: {
+ url: "https://server.example.com",
+ auth,
+ },
+ },
+ },
+ } as unknown as Settings);
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+ const { result } = renderHook(() => useUpdateMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ serverId: "shttp-0",
+ server: {
+ type: "shttp",
+ url: "https://server.example.com",
+ timeout: 45,
+ },
+ });
+
+ await waitFor(() => expect(result.current.isSuccess).toBe(true));
+ const payload = saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: {
+ mcp_config: Record<string, { auth?: unknown }>;
+ };
+ };
+ expect(payload.agent_settings_diff.mcp_config.myserver.auth).toEqual(
+ auth,
+ );
+ });
+
+ it("preserves custom API-key strategy and headers on edit", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ myserver: {
+ url: "https://server.example.com",
+ headers: { "X-Tenant": "**********" },
+ auth: {
+ strategy: "api_key",
+ value: "**********",
+ header_name: "X-API-Key",
+ },
+ },
+ },
+ },
+ } as unknown as Settings);
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+ const { result } = renderHook(() => useUpdateMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ serverId: "shttp-0",
+ server: {
+ type: "shttp",
+ url: "https://server.example.com",
+ api_key: "**********",
+ },
+ });
+
+ await waitFor(() => expect(result.current.isSuccess).toBe(true));
+ const payload = saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: {
+ mcp_config: Record<string, { auth?: unknown; headers?: unknown }>;
+ };
+ };
+ expect(payload.agent_settings_diff.mcp_config.myserver).toMatchObject({
+ headers: { "X-Tenant": "**********" },
+ auth: {
+ strategy: "api_key",
+ value: "**********",
+ header_name: "X-API-Key",
+ },
+ });
+ });
+
+ it("removes an Authorization header without clearing custom headers", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
+ mcp_config: {
+ myserver: {
+ url: "https://server.example.com",
+ headers: {
+ Authorization: "Bearer **********",
+ "X-Tenant": "**********",
+ },
+ },
+ },
+ },
+ } as unknown as Settings);
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+ const { result } = renderHook(() => useUpdateMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({
+ serverId: "shttp-0",
+ server: { type: "shttp", url: "https://server.example.com" },
+ });
+
+ await waitFor(() => expect(result.current.isSuccess).toBe(true));
+ const payload = saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: {
+ mcp_config: Record<string, { auth?: unknown; headers?: unknown }>;
+ };
+ };
+ expect(payload.agent_settings_diff.mcp_config.myserver).toMatchObject({
+ auth: null,
+ headers: { "X-Tenant": "**********" },
+ });
});
});
diff --git a/frontend/__tests__/utils/mcp-config.test.ts b/frontend/__tests__/utils/mcp-config.test.ts
index 5e604c2029..5e626a209f 100644
--- a/frontend/__tests__/utils/mcp-config.test.ts
+++ b/frontend/__tests__/utils/mcp-config.test.ts
@@ -112,6 +112,86 @@ describe("parseMcpConfig", () => {
});
});
+ it("should parse api_key from SDK bearer credentials", () => {
+ const input = {
+ "auth-server": {
+ url: "https://example.com",
+ auth: { strategy: "bearer", value: "**********" },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.shttp_servers[0]).toEqual({
+ name: "auth-server",
+ url: "https://example.com",
+ api_key: "**********",
+ auth: { strategy: "bearer", value: "**********" },
+ });
+ });
+
+ it.each([
+ {
+ strategy: "api_key" as const,
+ value: "**********",
+ header_name: "X-API-Key",
+ },
+ {
+ strategy: "basic" as const,
+ username: "user",
+ password: "**********",
+ },
+ {
+ strategy: "header" as const,
+ headers: { "X-API-Key": "**********" },
+ },
+ {
+ strategy: "oauth2" as const,
+ state: { tokens: { access_token: "**********" } },
+ },
+ ])("round-trips typed $strategy auth", (auth) => {
+ const parsed = parseMcpConfig({
+ server: { url: "https://example.com", auth },
+ });
+
+ expect(toSdkMcpConfig(parsed)?.server.auth).toEqual(auth);
+ });
+
+ it("round-trips custom headers alongside bearer auth", () => {
+ const persisted = {
+ server: {
+ url: "https://example.com",
+ headers: { "X-Tenant": "**********" },
+ auth: { strategy: "bearer", value: "**********" },
+ },
+ };
+
+ expect(toSdkMcpConfig(parseMcpConfig(persisted))?.server).toEqual(
+ persisted.server,
+ );
+ });
+
+ it("preserves api_key header metadata when updating its value", () => {
+ const parsed = parseMcpConfig({
+ server: {
+ url: "https://example.com",
+ auth: {
+ strategy: "api_key",
+ value: "**********",
+ header_name: "X-API-Key",
+ },
+ },
+ });
+ const server = parsed.shttp_servers[0];
+ if (typeof server === "object") server.api_key = "replacement";
+
+ expect(toSdkMcpConfig(parsed)?.server.auth).toEqual({
+ strategy: "api_key",
+ value: "replacement",
+ header_name: "X-API-Key",
+ });
+ });
+
it("should not include api_key when auth is 'oauth'", () => {
const input = {
mcpServers: {
@@ -129,7 +209,9 @@ describe("parseMcpConfig", () => {
name: "oauth-server",
url: "https://example.com",
});
- expect((result.sse_servers[0] as { api_key?: string }).api_key).toBeUndefined();
+ expect(
+ (result.sse_servers[0] as { api_key?: string }).api_key,
+ ).toBeUndefined();
});
it("should parse timeout for shttp servers", () => {
@@ -219,16 +301,18 @@ describe("toSdkMcpConfig", () => {
expect(result?.["sse_2"].url).toBe("https://example3.com");
});
- it("should serialize api_key as an Authorization bearer header", () => {
- // The SDK only redacts/encrypts ``headers`` (and ``env``), not ``auth`` β€”
- // writing the key to ``auth`` would persist it in plaintext.
+ it("should serialize api_key as an SDK bearer credential", () => {
const config: MCPConfig = {
sse_servers: [
{ name: "secure", url: "https://example.com", api_key: "my-secret" },
],
stdio_servers: [],
shttp_servers: [
- { name: "shttp", url: "https://shttp.example", api_key: "shttp-secret" },
+ {
+ name: "shttp",
+ url: "https://shttp.example",
+ api_key: "shttp-secret",
+ },
],
};
@@ -237,11 +321,11 @@ describe("toSdkMcpConfig", () => {
expect(result?.["secure"]).toEqual({
url: "https://example.com",
transport: "sse",
- headers: { Authorization: "Bearer my-secret" },
+ auth: { strategy: "bearer", value: "my-secret" },
});
expect(result?.["shttp"]).toEqual({
url: "https://shttp.example",
- headers: { Authorization: "Bearer shttp-secret" },
+ auth: { strategy: "bearer", value: "shttp-secret" },
});
});
@@ -258,7 +342,12 @@ describe("toSdkMcpConfig", () => {
const parsed = parseMcpConfig(persisted);
expect(parsed.shttp_servers).toEqual([
- { name: "shttp", url: "https://shttp.example", api_key: "shttp-secret" },
+ {
+ name: "shttp",
+ url: "https://shttp.example",
+ api_key: "shttp-secret",
+ headers: { Authorization: "Bearer shttp-secret" },
+ },
]);
});
@@ -279,7 +368,7 @@ describe("toSdkMcpConfig", () => {
sse: {
url: "https://example.com",
transport: "sse",
- headers: { Authorization: "Bearer legacy-secret" },
+ auth: { strategy: "bearer", value: "legacy-secret" },
},
});
});
diff --git a/frontend/src/hooks/mutation/use-update-mcp-server.ts b/frontend/src/hooks/mutation/use-update-mcp-server.ts
index 2e1519745d..865ab68977 100644
--- a/frontend/src/hooks/mutation/use-update-mcp-server.ts
+++ b/frontend/src/hooks/mutation/use-update-mcp-server.ts
@@ -23,6 +23,49 @@ interface MCPServerConfig {
env?: Record<string, string>;
}
+function withExplicitMcpAuthClear(
+ serialized: NonNullable<ReturnType<typeof toSdkMcpConfig>>,
+ server: MCPSSEServer | MCPSHTTPServer,
+) {
+ if (!server.name || !serialized[server.name]) {
+ return serialized;
+ }
+ const headers = Object.fromEntries(
+ Object.entries(server.headers ?? {}).filter(
+ ([key]) => key.toLowerCase() !== "authorization",
+ ),
+ );
+ return {
+ ...serialized,
+ [server.name]: {
+ ...serialized[server.name],
+ auth: null,
+ ...(server.headers && { headers }),
+ },
+ };
+}
+
+function updatedRemoteServer(
+ current: string | MCPSSEServer | MCPSHTTPServer,
+ server: MCPServerConfig,
+): MCPSSEServer | MCPSHTTPServer {
+ const updated: MCPSHTTPServer = {
+ ...(typeof current === "object" ? current : {}),
+ url: server.url!,
+ };
+ if (server.type === "shttp" && server.timeout !== undefined) {
+ updated.timeout = server.timeout;
+ } else {
+ delete updated.timeout;
+ }
+ if (server.api_key) {
+ updated.api_key = server.api_key;
+ } else {
+ delete updated.api_key;
+ }
+ return updated;
+}
+
export function useUpdateMcpServer() {
const queryClient = useQueryClient();
const { organizationId } = useSelectedOrganizationId();
@@ -49,32 +92,37 @@ export function useUpdateMcpServer() {
};
const [serverType, indexStr] = serverId.split("-");
const index = parseInt(indexStr, 10);
+ let previousRemote: MCPSSEServer | MCPSHTTPServer | undefined;
+ let updatedRemote: MCPSSEServer | MCPSHTTPServer | undefined;
if (serverType === "sse") {
- const sseServer: MCPSSEServer = {
- url: server.url!,
- ...(server.api_key && { api_key: server.api_key }),
- };
- newConfig.sse_servers[index] = sseServer;
+ const current = newConfig.sse_servers[index];
+ previousRemote = typeof current === "object" ? current : undefined;
+ updatedRemote = updatedRemoteServer(current, server);
+ newConfig.sse_servers[index] = updatedRemote;
} else if (serverType === "stdio") {
const stdioServer: MCPStdioServer = {
name: server.name!,
command: server.command!,
...(server.args && { args: server.args }),
- ...(server.env && { env: server.env }),
+ env: server.env ?? {},
};
newConfig.stdio_servers[index] = stdioServer;
} else if (serverType === "shttp") {
- const shttpServer: MCPSHTTPServer = {
- url: server.url!,
- ...(server.api_key && { api_key: server.api_key }),
- ...(server.timeout !== undefined && { timeout: server.timeout }),
- };
- newConfig.shttp_servers[index] = shttpServer;
+ const current = newConfig.shttp_servers[index];
+ previousRemote = typeof current === "object" ? current : undefined;
+ updatedRemote = updatedRemoteServer(current, server);
+ newConfig.shttp_servers[index] = updatedRemote;
}
+ let serialized = toSdkMcpConfig(newConfig);
+ const remoteApiKeyRemoved =
+ previousRemote?.api_key !== undefined && !server.api_key;
+ if (remoteApiKeyRemoved && serialized && updatedRemote) {
+ serialized = withExplicitMcpAuthClear(serialized, updatedRemote);
+ }
const payload = {
- agent_settings_diff: { mcp_config: toSdkMcpConfig(newConfig) },
+ agent_settings_diff: { mcp_config: serialized },
};
await SettingsService.saveSettings(payload);
diff --git a/frontend/src/types/settings.ts b/frontend/src/types/settings.ts
index afbc43734a..f62d5611f1 100644
--- a/frontend/src/types/settings.ts
+++ b/frontend/src/types/settings.ts
@@ -26,10 +26,32 @@ export type ProviderToken = {
host: string | null;
};
+export type MCPJsonValue =
+ | boolean
+ | number
+ | string
+ | null
+ | MCPJsonValue[]
+ | { [key: string]: MCPJsonValue };
+
+export type MCPAuthCredential =
+ | { strategy: "none" }
+ | { strategy: "api_key"; value?: string | null; header_name?: string | null }
+ | { strategy: "bearer"; value?: string | null }
+ | { strategy: "basic"; username: string; password?: string | null }
+ | { strategy: "header"; headers?: Record<string, string> | null }
+ | {
+ strategy: "oauth2";
+ authentication?: Record<string, MCPJsonValue> | null;
+ state?: Record<string, MCPJsonValue> | null;
+ };
+
export type MCPSSEServer = {
name?: string;
url: string;
api_key?: string;
+ auth?: MCPAuthCredential;
+ headers?: Record<string, string>;
};
export type MCPStdioServer = {
@@ -43,6 +65,8 @@ export type MCPSHTTPServer = {
name?: string;
url: string;
api_key?: string;
+ auth?: MCPAuthCredential;
+ headers?: Record<string, string>;
timeout?: number;
};
diff --git a/frontend/src/utils/mcp-config.ts b/frontend/src/utils/mcp-config.ts
index 1d53afdd0e..34cb905bd0 100644
--- a/frontend/src/utils/mcp-config.ts
+++ b/frontend/src/utils/mcp-config.ts
@@ -1,5 +1,6 @@
import {
MCPConfig,
+ MCPAuthCredential,
MCPSSEServer,
MCPSHTTPServer,
MCPStdioServer,
@@ -12,7 +13,39 @@ const EMPTY_MCP_CONFIG: MCPConfig = {
shttp_servers: [],
};
-type SdkMcpServerConfig = Record<string, SettingsValue>;
+type SdkMcpServerConfig = Record<string, SettingsValue | MCPAuthCredential>;
+
+const MCP_AUTH_STRATEGIES = new Set([
+ "none",
+ "api_key",
+ "bearer",
+ "basic",
+ "header",
+ "oauth2",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringRecord(value: unknown): Record<string, string> | undefined {
+ if (!isRecord(value)) return undefined;
+ const entries = Object.entries(value).filter(
+ (entry): entry is [string, string] => typeof entry[1] === "string",
+ );
+ return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+function authCredential(value: unknown): MCPAuthCredential | undefined {
+ if (
+ !isRecord(value) ||
+ typeof value.strategy !== "string" ||
+ !MCP_AUTH_STRATEGIES.has(value.strategy)
+ ) {
+ return undefined;
+ }
+ return value as MCPAuthCredential;
+}
/**
* Normalize the SDK wire payload to a flat server map.
@@ -88,20 +121,77 @@ function apiKeyFromServerConfig(
if (headerApiKey) return headerApiKey;
const { auth } = serverConfig;
+ if (auth && typeof auth === "object" && !Array.isArray(auth)) {
+ const credential = auth as Record<string, unknown>;
+ if (
+ (credential.strategy === "api_key" || credential.strategy === "bearer") &&
+ typeof credential.value === "string"
+ ) {
+ return credential.value;
+ }
+ if (credential.strategy === "header") {
+ const authHeaders = credential.headers;
+ if (authHeaders && typeof authHeaders === "object") {
+ return apiKeyFromAuthorizationHeader(
+ (authHeaders as Record<string, unknown>).Authorization ??
+ (authHeaders as Record<string, unknown>).authorization,
+ );
+ }
+ }
+ }
return typeof auth === "string" && auth !== "oauth" ? auth : undefined;
}
-/**
- * Serialize an API key as an ``Authorization`` bearer header. The SDK only
- * redacts/encrypts ``headers`` (and ``env``), not ``auth``, so a key written
- * to ``auth`` would persist in plaintext β€” write the header form instead.
- */
-function getAuthorizationHeaders(apiKey: string | undefined) {
- if (!apiKey) return {};
+function authorizationHeader(
+ headers: Record<string, string> | undefined,
+): [string, string] | undefined {
+ return Object.entries(headers ?? {}).find(
+ ([key]) => key.toLowerCase() === "authorization",
+ );
+}
+
+function withApiKey(
+ auth: MCPAuthCredential | undefined,
+ apiKey: string,
+): MCPAuthCredential {
+ if (auth?.strategy === "api_key" || auth?.strategy === "bearer") {
+ return { ...auth, value: apiKey };
+ }
+ if (auth?.strategy === "header") {
+ const current = authorizationHeader(auth.headers ?? undefined);
+ if (current) {
+ const [key, value] = current;
+ const headerValue = /^Bearer\s+/i.test(value)
+ ? `Bearer ${apiKey}`
+ : apiKey;
+ return {
+ ...auth,
+ headers: { ...auth.headers, [key]: headerValue },
+ };
+ }
+ }
+ return { strategy: "bearer", value: apiKey };
+}
+
+function getRemoteSecretFields(server: MCPSSEServer | MCPSHTTPServer) {
+ let { auth, headers } = server;
+ if (server.api_key) {
+ const currentHeader = authorizationHeader(headers);
+ if (!auth && currentHeader) {
+ const [key, value] = currentHeader;
+ headers = {
+ ...headers,
+ [key]: /^Bearer\s+/i.test(value)
+ ? `Bearer ${server.api_key}`
+ : server.api_key,
+ };
+ } else {
+ auth = withApiKey(auth, server.api_key);
+ }
+ }
return {
- headers: {
- Authorization: `Bearer ${apiKey}`,
- },
+ ...(auth && { auth }),
+ ...(headers && { headers }),
};
}
@@ -169,6 +259,8 @@ export function parseMcpConfig(value: unknown): MCPConfig {
if (url) {
const transport = serverConfig.transport as string | undefined;
const apiKey = apiKeyFromServerConfig(serverConfig);
+ const auth = authCredential(serverConfig.auth);
+ const headers = stringRecord(serverConfig.headers);
if (transport === "sse") {
const server: MCPSSEServer = {
@@ -176,6 +268,8 @@ export function parseMcpConfig(value: unknown): MCPConfig {
url,
};
if (apiKey) server.api_key = apiKey;
+ if (auth) server.auth = auth;
+ if (headers) server.headers = headers;
sseServers.push(server);
} else {
const server: MCPSHTTPServer = {
@@ -183,6 +277,8 @@ export function parseMcpConfig(value: unknown): MCPConfig {
url,
};
if (apiKey) server.api_key = apiKey;
+ if (auth) server.auth = auth;
+ if (headers) server.headers = headers;
if (serverConfig.timeout != null) {
server.timeout = serverConfig.timeout as number;
}
@@ -233,7 +329,7 @@ export function toSdkMcpConfig(
server.url = entry;
} else {
server.url = entry.url;
- Object.assign(server, getAuthorizationHeaders(entry.api_key));
+ Object.assign(server, getRemoteSecretFields(entry));
}
server.transport = "sse";
@@ -251,7 +347,7 @@ export function toSdkMcpConfig(
server.url = entry;
} else {
server.url = entry.url;
- Object.assign(server, getAuthorizationHeaders(entry.api_key));
+ Object.assign(server, getRemoteSecretFields(entry));
if (entry.timeout != null) server.timeout = entry.timeout;
}
diff --git a/openhands/app_server/settings/settings_models.py b/openhands/app_server/settings/settings_models.py
index 9d8a1eaffe..478b96ea8f 100644
--- a/openhands/app_server/settings/settings_models.py
+++ b/openhands/app_server/settings/settings_models.py
@@ -12,6 +12,8 @@ from __future__ import annotations
import logging
import re
+from collections.abc import Mapping
+from copy import deepcopy
from enum import Enum
from typing import Annotated, Any, Sequence
@@ -34,6 +36,7 @@ from openhands.app_server.integrations.provider import ProviderToken
from openhands.app_server.integrations.service_types import ProviderType
from openhands.app_server.settings.llm_profiles import LLMProfiles
from openhands.app_server.utils.jsonpatch_compat import deep_merge
+from openhands.sdk.mcp.config import MCPServer, dump_mcp_config
from openhands.sdk.settings import (
ACPAgentSettings,
AgentSettingsConfig,
@@ -43,6 +46,7 @@ from openhands.sdk.settings import (
default_agent_settings,
validate_agent_settings,
)
+from openhands.sdk.utils.pydantic_secrets import REDACTED_SECRET_VALUE
logger = logging.getLogger(__name__)
@@ -273,6 +277,266 @@ def _coerce_dict_secrets(d: dict[str, Any]) -> dict[str, Any]:
return out
+_MISSING_SECRET = object()
+_MCP_SECRET_FIELDS = ('headers', 'env', 'auth')
+
+
+def _is_redacted_mcp_secret(value: object) -> bool:
+ if not isinstance(value, str):
+ return False
+ return value == REDACTED_SECRET_VALUE or bool(
+ re.fullmatch(
+ rf'Bearer\s+{re.escape(REDACTED_SECRET_VALUE)}',
+ value,
+ flags=re.IGNORECASE,
+ )
+ )
+
+
+def _has_redacted_mcp_secret(value: object) -> bool:
+ if _is_redacted_mcp_secret(value):
+ return True
+ if isinstance(value, Mapping):
+ return any(_has_redacted_mcp_secret(item) for item in value.values())
+ if isinstance(value, list):
+ return any(_has_redacted_mcp_secret(item) for item in value)
+ return False
+
+
+def _restore_redacted_secret(value: Any, existing: Any) -> Any:
+ if _is_redacted_mcp_secret(value):
+ if isinstance(existing, str) and not _is_redacted_mcp_secret(existing):
+ return existing
+ return _MISSING_SECRET
+ if isinstance(value, dict):
+ existing_dict = existing if isinstance(existing, Mapping) else {}
+ restored = {}
+ for key, item in value.items():
+ restored_item = _restore_redacted_secret(item, existing_dict.get(key))
+ if restored_item is not _MISSING_SECRET:
+ restored[key] = restored_item
+ return restored
+ return value
+
+
+def _is_authorization_header(key: object) -> bool:
+ return isinstance(key, str) and key.lower() == 'authorization'
+
+
+def _header_value(headers: object, key: object) -> object:
+ if not isinstance(headers, Mapping):
+ return None
+ for existing_key, value in headers.items():
+ if (
+ isinstance(key, str)
+ and isinstance(existing_key, str)
+ and existing_key.lower() == key.lower()
+ ):
+ return value
+ return None
+
+
+def _restore_submitted_mcp_headers(
+ incoming: object,
+ existing_server: Mapping[str, Any],
+) -> object:
+ if not isinstance(incoming, Mapping):
+ return incoming
+ existing_headers = existing_server.get('headers')
+ restored = (
+ dict(existing_headers)
+ if _has_redacted_mcp_secret(incoming) and isinstance(existing_headers, Mapping)
+ else {}
+ )
+ for key, value in incoming.items():
+ existing_value = _header_value(existing_headers, key)
+ for existing_key in tuple(restored):
+ if (
+ isinstance(existing_key, str)
+ and isinstance(key, str)
+ and existing_key.lower() == key.lower()
+ ):
+ restored.pop(existing_key)
+ if (
+ _is_authorization_header(key)
+ and _is_redacted_mcp_secret(value)
+ and existing_value is None
+ ):
+ continue
+ restored_value = _restore_redacted_secret(value, existing_value)
+ if restored_value is not _MISSING_SECRET:
+ restored[key] = restored_value
+ return restored
+
+
+def _restore_submitted_mcp_auth(value: object, existing: object) -> object:
+ if _has_redacted_mcp_secret(value) and existing is not None:
+ if isinstance(value, Mapping) and isinstance(existing, Mapping):
+ if value.get('strategy') != existing.get('strategy'):
+ return deepcopy(existing)
+ elif not isinstance(value, str) or not isinstance(existing, str):
+ return deepcopy(existing)
+ return _restore_redacted_secret(value, existing)
+
+
+def _restore_submitted_mcp_secrets(
+ incoming_server: dict[str, Any],
+ existing_server: Mapping[str, Any],
+ submitted_fields: tuple[str, ...],
+) -> None:
+ for field in submitted_fields:
+ existing_value = existing_server.get(field)
+ if field == 'headers':
+ restored = _restore_submitted_mcp_headers(
+ incoming_server[field],
+ existing_server,
+ )
+ elif field == 'auth':
+ restored = _restore_submitted_mcp_auth(
+ incoming_server[field], existing_value
+ )
+ else:
+ restored = _restore_redacted_secret(
+ incoming_server[field],
+ existing_value,
+ )
+ if restored is _MISSING_SECRET:
+ incoming_server.pop(field)
+ else:
+ incoming_server[field] = restored
+
+
+def _carry_omitted_mcp_secrets(
+ incoming_server: dict[str, Any],
+ existing_server: Mapping[str, Any],
+ submitted_fields: tuple[str, ...],
+) -> None:
+ if 'env' not in submitted_fields and existing_server.get('env') is not None:
+ incoming_server['env'] = existing_server['env']
+
+ if 'headers' not in submitted_fields:
+ existing_headers = existing_server.get('headers')
+ if isinstance(existing_headers, Mapping):
+ headers = dict(existing_headers)
+ if 'auth' in submitted_fields:
+ headers = {
+ key: value
+ for key, value in headers.items()
+ if not _is_authorization_header(key)
+ }
+ if headers:
+ incoming_server['headers'] = headers
+
+ if 'auth' not in submitted_fields and existing_server.get('auth') is not None:
+ submitted_headers = incoming_server.get('headers')
+ has_plain_authorization = isinstance(submitted_headers, Mapping) and any(
+ _is_authorization_header(key) and not _is_redacted_mcp_secret(value)
+ for key, value in submitted_headers.items()
+ )
+ if not has_plain_authorization:
+ incoming_server['auth'] = existing_server['auth']
+
+
+def _mcp_server_map(value: Any) -> dict[str, Any] | None:
+ if not isinstance(value, dict):
+ return None
+ servers = value.get('mcpServers', value)
+ return servers if isinstance(servers, dict) else None
+
+
+def _mcp_endpoint_identity(server: Mapping[str, Any]) -> tuple[Any, ...] | None:
+ url = server.get('url')
+ if isinstance(url, str) and url:
+ return ('url', url)
+ command = server.get('command')
+ if not isinstance(command, str) or not command:
+ return None
+ args = server.get('args')
+ # Bind environment secrets to the full process invocation.
+ return (
+ 'stdio',
+ command,
+ tuple(args) if isinstance(args, list) else (),
+ server.get('cwd'),
+ )
+
+
+def _matching_existing_mcp_server(
+ name: str,
+ incoming_server: Mapping[str, Any],
+ incoming_servers: Mapping[str, Any],
+ existing_servers: Mapping[str, Any],
+) -> Mapping[str, Any]:
+ incoming_endpoint = _mcp_endpoint_identity(incoming_server)
+ if incoming_endpoint is None:
+ return {}
+
+ named_server = existing_servers.get(name)
+ if isinstance(named_server, Mapping):
+ return (
+ named_server
+ if incoming_endpoint == _mcp_endpoint_identity(named_server)
+ else {}
+ )
+
+ candidates = [
+ server
+ for existing_name, server in existing_servers.items()
+ if existing_name not in incoming_servers
+ and isinstance(server, Mapping)
+ and incoming_endpoint == _mcp_endpoint_identity(server)
+ ]
+ competing_updates = sum(
+ 1
+ for incoming_name, server in incoming_servers.items()
+ if incoming_name not in existing_servers
+ and isinstance(server, Mapping)
+ and incoming_endpoint == _mcp_endpoint_identity(server)
+ )
+ return candidates[0] if len(candidates) == competing_updates == 1 else {}
+
+
+def _preserve_redacted_mcp_secrets(
+ value: Any,
+ existing: Mapping[str, MCPServer] | None,
+) -> Any:
+ incoming_value = deepcopy(value)
+ incoming_servers = _mcp_server_map(incoming_value)
+ if incoming_servers is None:
+ return incoming_value
+
+ existing = existing or {}
+ existing_dump = dump_mcp_config(
+ existing,
+ context={'expose_secrets': 'plaintext'},
+ )
+ for name, incoming_server in incoming_servers.items():
+ if not isinstance(name, str) or not isinstance(incoming_server, dict):
+ continue
+ existing_server = _matching_existing_mcp_server(
+ name,
+ incoming_server,
+ incoming_servers,
+ existing_dump,
+ )
+
+ submitted_fields = tuple(
+ field for field in _MCP_SECRET_FIELDS if field in incoming_server
+ )
+ _restore_submitted_mcp_secrets(
+ incoming_server,
+ existing_server,
+ submitted_fields,
+ )
+ _carry_omitted_mcp_secrets(
+ incoming_server,
+ existing_server,
+ submitted_fields,
+ )
+
+ return incoming_value
+
+
def _load_persisted_agent_settings(
data: Any,
) -> OpenHandsAgentSettings | ACPAgentSettings:
@@ -405,6 +669,7 @@ class Settings(BaseModel):
# not dump/reconstruct β€” ``store()`` also guards on
# ``active_agent_profile_id`` for reconstructed copies.
_resolved_view: bool = PrivateAttr(default=False)
+ _mcp_config_updated: bool = PrivateAttr(default=False)
# Marketplace registrations for plugin resolution
# Users can register multiple marketplaces with different auto-load behaviors
@@ -437,12 +702,20 @@ class Settings(BaseModel):
# user out of settings entirely if legacy stored data contained a duplicate.
def __init__(self, **data: Any):
+ raw_agent_settings = data.get('agent_settings')
+ mcp_config_updated = (
+ 'mcp_config' in raw_agent_settings
+ if isinstance(raw_agent_settings, Mapping)
+ else 'mcp_config'
+ in getattr(raw_agent_settings, 'model_fields_set', frozenset())
+ )
# Import Secrets here to avoid circular imports
from openhands.app_server.secrets.secrets_models import Secrets
if 'secrets_store' not in data or data['secrets_store'] is None:
data['secrets_store'] = Secrets()
super().__init__(**data)
+ self._mcp_config_updated = mcp_config_updated
@property
def llm_api_key_is_set(self) -> bool:
@@ -499,7 +772,14 @@ class Settings(BaseModel):
# ``mcp_config`` replaces wholesale rather than deep-merging, so
# hold it back from the variant-aware merge and apply it after.
replace_mcp_config = 'mcp_config' in agent_update
- mcp_config = coerced.pop('mcp_config', None) if replace_mcp_config else None
+ mcp_config = (
+ _preserve_redacted_mcp_secrets(
+ coerced.pop('mcp_config', None),
+ self.agent_settings.mcp_config,
+ )
+ if replace_mcp_config
+ else None
+ )
# The SDK owns the discriminated-union merge: replace on
# ``agent_kind`` change, deep-merge within a variant. Cross-kind
@@ -515,6 +795,8 @@ class Settings(BaseModel):
# Use object.__setattr__ to avoid validate_assignment
# side-effects on other fields.
object.__setattr__(self, 'agent_settings', new_settings)
+ if replace_mcp_config:
+ self._mcp_config_updated = True
conv_update = payload.get('conversation_settings_diff')
if isinstance(conv_update, dict):
diff --git a/tests/unit/storage/data_models/test_settings.py b/tests/unit/storage/data_models/test_settings.py
index 4bb48153bf..d74cff87a5 100644
--- a/tests/unit/storage/data_models/test_settings.py
+++ b/tests/unit/storage/data_models/test_settings.py
@@ -13,6 +13,7 @@ from openhands.app_server.settings.settings_models import (
)
from openhands.app_server.settings.settings_router import LITE_LLM_API_URL
from openhands.sdk.llm import LLM
+from openhands.sdk.mcp.config import dump_mcp_config
from openhands.sdk.settings import (
AGENT_SETTINGS_SCHEMA_VERSION,
ConversationSettings,
@@ -214,6 +215,7 @@ def test_settings_update_replaces_existing_mcp_servers():
'fresh': {
'transport': 'http',
'url': 'https://example.com/fresh',
+ 'tools': ['search'],
}
}
}
@@ -227,6 +229,396 @@ def test_settings_update_replaces_existing_mcp_servers():
assert mcp['fresh'].url == 'https://example.com/fresh'
+def _settings_with_mcp_auth(
+ url: str = 'https://integration.example.com/mcp',
+) -> Settings:
+ return Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'integration-hub': {
+ 'url': url,
+ 'headers': {'Authorization': 'Bearer real-key'},
+ }
+ }
+ )
+ )
+
+
+def test_settings_update_preserves_redacted_mcp_auth_for_same_endpoint():
+ settings = _settings_with_mcp_auth()
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'integration-hub': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': '**********'},
+ }
+ }
+ }
+ }
+ )
+
+ server = settings.agent_settings.mcp_config['integration-hub']
+ assert server.auth is not None
+ assert server.auth.to_http_headers() == {'Authorization': 'Bearer real-key'}
+
+
+def test_settings_update_preserves_redacted_mcp_header_for_same_endpoint():
+ settings = _settings_with_mcp_auth()
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'integration-hub': {
+ 'url': 'https://integration.example.com/mcp',
+ 'headers': {'Authorization': 'Bearer **********'},
+ }
+ }
+ }
+ }
+ )
+
+ server = settings.agent_settings.mcp_config['integration-hub']
+ assert server.auth is not None
+ assert server.auth.to_http_headers() == {'Authorization': 'Bearer real-key'}
+
+
+ 'auth',
+ (
+ {'strategy': 'api_key', 'value': 'real-key', 'header_name': 'X-API-Key'},
+ {'strategy': 'basic', 'username': 'user', 'password': 'real-key'},
+ {'strategy': 'header', 'headers': {'X-API-Key': 'real-key'}},
+ {
+ 'strategy': 'oauth2',
+ 'state': {'tokens': {'access_token': 'real-key'}},
+ },
+ ),
+)
+def test_settings_update_preserves_typed_auth_from_redacted_bearer(
+ auth: dict[str, object],
+):
+ settings = Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'server': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': auth,
+ }
+ }
+ )
+ )
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'server': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': '**********'},
+ }
+ }
+ }
+ }
+ )
+
+ dumped = dump_mcp_config(
+ settings.agent_settings.mcp_config or {},
+ context={'expose_secrets': 'plaintext'},
+ )
+ assert dumped['server']['auth'] == auth
+
+
+def test_settings_update_preserves_custom_headers_with_typed_auth():
+ settings = Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'server': {
+ 'url': 'https://integration.example.com/mcp',
+ 'headers': {'X-Tenant': 'tenant-secret'},
+ 'auth': {'strategy': 'bearer', 'value': 'real-key'},
+ }
+ }
+ )
+ )
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'server': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': {'strategy': 'bearer', 'value': '**********'},
+ }
+ }
+ }
+ }
+ )
+
+ dumped = dump_mcp_config(
+ settings.agent_settings.mcp_config or {},
+ context={'expose_secrets': 'plaintext'},
+ )
+ assert dumped['server']['headers'] == {'X-Tenant': 'tenant-secret'}
+ assert dumped['server']['auth'] == {'strategy': 'bearer', 'value': 'real-key'}
+
+
+ 'credential_update',
+ (
+ {},
+ {'auth': {'strategy': 'bearer', 'value': '**********'}},
+ {'headers': {'Authorization': 'Bearer **********'}},
+ ),
+)
+def test_settings_update_drops_mcp_auth_for_changed_endpoint(
+ credential_update: dict[str, object],
+):
+ settings = _settings_with_mcp_auth('https://old.example.com/mcp')
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'integration-hub': {
+ 'url': 'https://new.example.com/mcp',
+ **credential_update,
+ }
+ }
+ }
+ }
+ )
+
+ server = settings.agent_settings.mcp_config['integration-hub']
+ assert not server.headers
+ assert server.auth is None or server.auth.to_http_headers() == {}
+
+
+def test_settings_update_preserves_omitted_mcp_auth_for_same_endpoint():
+ settings = _settings_with_mcp_auth()
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'integration-hub': {
+ 'url': 'https://integration.example.com/mcp',
+ }
+ }
+ }
+ }
+ )
+
+ server = settings.agent_settings.mcp_config['integration-hub']
+ assert server.auth is not None
+ assert server.auth.to_http_headers() == {'Authorization': 'Bearer real-key'}
+
+
+def test_settings_update_clears_explicit_mcp_auth():
+ settings = _settings_with_mcp_auth()
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'integration-hub': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': None,
+ }
+ }
+ }
+ }
+ )
+
+ server = settings.agent_settings.mcp_config['integration-hub']
+ assert server.auth is None
+
+
+def test_settings_update_clears_auth_without_clearing_custom_headers():
+ settings = Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'server': {
+ 'url': 'https://integration.example.com/mcp',
+ 'headers': {'X-Tenant': 'tenant-secret'},
+ 'auth': {'strategy': 'bearer', 'value': 'real-key'},
+ }
+ }
+ )
+ )
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'server': {
+ 'url': 'https://integration.example.com/mcp',
+ 'auth': None,
+ }
+ }
+ }
+ }
+ )
+
+ dumped = dump_mcp_config(
+ settings.agent_settings.mcp_config or {},
+ context={'expose_secrets': 'plaintext'},
+ )
+ assert dumped['server']['headers'] == {'X-Tenant': 'tenant-secret'}
+ assert 'auth' not in dumped['server']
+
+
+def test_settings_update_preserves_redacted_mcp_env_for_same_command():
+ settings = Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'local': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': 'real-key'},
+ }
+ }
+ )
+ )
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'local': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': '**********'},
+ }
+ }
+ }
+ }
+ )
+
+ server = settings.agent_settings.mcp_config['local']
+ assert server.env is not None
+ assert server.env['API_KEY'].get_secret_value() == 'real-key'
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'local': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ 'env': {},
+ }
+ }
+ }
+ }
+ )
+
+ assert not settings.agent_settings.mcp_config['local'].env
+
+
+def test_settings_update_preserves_redacted_mcp_env_across_rename():
+ settings = Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'old-name': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': 'real-key'},
+ }
+ }
+ )
+ )
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'new-name': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': '**********'},
+ }
+ }
+ }
+ }
+ )
+
+ server = settings.agent_settings.mcp_config['new-name']
+ assert server.env is not None
+ assert server.env['API_KEY'].get_secret_value() == 'real-key'
+
+
+def test_settings_update_does_not_copy_mcp_env_to_duplicate_server():
+ settings = Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'original': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': 'real-key'},
+ }
+ }
+ )
+ )
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'original': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ },
+ 'duplicate': {
+ 'command': 'mcp-server',
+ 'args': ['--stdio'],
+ 'env': {'API_KEY': '**********'},
+ },
+ }
+ }
+ }
+ )
+
+ original = settings.agent_settings.mcp_config['original']
+ duplicate = settings.agent_settings.mcp_config['duplicate']
+ assert original.env is not None
+ assert original.env['API_KEY'].get_secret_value() == 'real-key'
+ assert not duplicate.env
+
+
+def test_settings_update_drops_redacted_mcp_env_when_args_change():
+ settings = Settings(
+ agent_settings=OpenHandsAgentSettings(
+ mcp_config={
+ 'local': {
+ 'command': 'npx',
+ 'args': ['first-package'],
+ 'env': {'API_KEY': 'real-key'},
+ }
+ }
+ )
+ )
+
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'mcp_config': {
+ 'local': {
+ 'command': 'npx',
+ 'args': ['different-package'],
+ 'env': {'API_KEY': '**********'},
+ }
+ }
+ }
+ }
+ )
+
+ assert not settings.agent_settings.mcp_config['local'].env
+
+
def test_settings_update_can_clear_mcp_config():
settings = Settings(
agent_settings=OpenHandsAgentSettings(