feat(mcp): add browser OAuth for remote servers (#5316)

docs/configuration.md

@@ -1971,15 +1971,52 @@ Add MCP servers to your `config.json`:
 }
 ```
 
-Two transport modes are supported:
+MCP servers can run locally over stdio or connect remotely over HTTP:
 
-| Mode | Config | Example |
+| Connection | Config | Example |
 |------|--------|---------|
 | **Stdio** | `command` + `args` | Local process via `npx` / `uvx` |
-| **HTTP** | `url` + `headers` (optional) | Remote endpoint (`https://mcp.example.com/sse`) |
+| **Streamable HTTP / SSE** | `url` + `headers` (optional) | Remote endpoint (`https://mcp.example.com/mcp`) |
+
+Remote HTTP servers may use browser OAuth instead of static headers. In the
+WebUI, open **Apps → MCP → Add MCP server**, choose **Custom**, select HTTP or
+SSE, and choose **OAuth** under **Authentication**. Save the server, then choose
+**Connect**. For manual configuration, add `auth: "oauth"` and open
+**Apps → MCP** to connect. Known presets such as Xmind, Notion, and Linear add
+the config automatically on first click.
+
+```json
+{
+  "tools": {
+    "mcpServers": {
+      "notion": {
+        "type": "streamableHttp",
+        "url": "https://mcp.notion.com/mcp",
+        "auth": "oauth"
+      }
+    }
+  }
+}
+```
+
+nanobot opens the server's authorization page and handles the callback through
+the gateway. The tools become available immediately when hot reload succeeds;
+otherwise the WebUI asks for a restart. OAuth tokens and dynamic client
+registration data are stored in the nanobot data directory under
+`auth/mcp.json`; they are not written to `config.json`. Removing the MCP server
+from Apps also removes its saved OAuth credentials. Normal gateway startup never
+opens a browser or registers a new OAuth client when credentials are
+missing—interactive authorization starts only after a user clicks **Connect**.
+
+For a remotely accessed WebUI, HTTPS is recommended. Configure
+`channels.websocket.publicWsUrl` with the browser-facing `wss://` endpoint so
+nanobot can register the matching HTTPS callback and finish automatically. A
+loopback WebUI may use HTTP. When a remote WebUI is served over plain HTTP,
+nanobot instead registers a localhost callback and asks you to paste the complete
+callback URL from the browser address bar after authorization.
 
 > [!IMPORTANT]
-> HTTP/SSE MCP URLs are validated before probing or connecting, and every outgoing MCP HTTP request is validated again before redirects are followed. `localhost`, `127.0.0.1`, RFC1918/private IPs, CGNAT/Tailscale ranges, link-local addresses, and cloud metadata endpoints are blocked by default. This can break previously working local or private HTTP MCP configs until the endpoint is explicitly allowed with `tools.ssrfWhitelist`, preferably with a single-host CIDR such as `127.0.0.1/32`, `::1/128`, or `192.168.1.50/32`. Stdio MCP servers are not affected.
+> HTTP/SSE MCP URLs are validated before probing or connecting, and every outgoing MCP HTTP request—including OAuth metadata, client registration, token exchange, and redirects—is validated again. `localhost`, `127.0.0.1`, RFC1918/private IPs, CGNAT/Tailscale ranges, link-local addresses, and cloud metadata endpoints are blocked by default. This can break previously working local or private HTTP MCP configs until the endpoint is explicitly allowed with `tools.ssrfWhitelist`, preferably with a single-host CIDR such as `127.0.0.1/32`, `::1/128`, or `192.168.1.50/32`. Stdio MCP servers are not affected.
 
 Use `toolTimeout` to override the default 30s per-call timeout for slow servers:
 

docs/guides/configure-mcp-tools.md

@@ -30,10 +30,15 @@ remote HTTP endpoint.
 For local interactive setup:
 
 1. Run `nanobot webui` and open **Apps**.
-2. Choose a known integration preset, or add a custom stdio, HTTP, or SSE server.
+2. Choose a known MCP server preset, or add a custom stdio, HTTP, or SSE server.
+   For a custom OAuth server, choose **OAuth** under **Authentication**, save it,
+   and click **Connect**. Presets such as Xmind, Notion, and Linear go straight to
+   **Connect**. Approve access in the browser window. HTTPS and localhost WebUIs
+   return automatically. From a remote plain-HTTP WebUI, copy the complete
+   localhost callback URL from the browser address bar and paste it into nanobot.
 3. Limit the enabled tools when the server exposes more than the task needs.
 4. Save and restart when prompted.
-5. Mention the integration with `@` in the next message and ask for a small test action.
+5. Mention the connected MCP server with `@` in the next message and ask for a small test action.
 
 For manual or deployment-managed config, add this to `~/.nanobot/config.json`:
 
@@ -58,12 +63,16 @@ Restart nanobot and ask a question that requires the MCP tool.
 - Prefer `enabledTools` over exposing every tool by default.
 - Use `toolTimeout` for slow MCP operations.
 - Use HTTP MCP only for endpoints you trust.
+- For deployment-managed OAuth servers, set `auth` to `oauth` and complete the
+  browser connection from **Apps → MCP**.
 - Keep MCP server commands stable and versioned in deployment docs or scripts.
 
 ## Security notes
 
 - Stdio MCP starts a local process; review the command before enabling it.
-- HTTP/SSE MCP uses nanobot's SSRF guard.
+- HTTP/SSE MCP uses nanobot's SSRF guard, including OAuth discovery, registration,
+  token exchange, and redirects.
+- OAuth credentials live in the nanobot data directory, not in `config.json`.
 - Allow private HTTP MCP hosts only with narrow `tools.ssrfWhitelist` CIDRs.
 - Do not place secrets in command arguments when environment variables or
   headers can be used.

docs/webui.md

@@ -204,8 +204,13 @@ turn. The default **Ready** view shows only tools that can be used immediately:
 - **Apps** are local command-line adapters that nanobot runs on your machine.
   Installing an adapter does not modify the native desktop or web app it
   connects to.
-- **Integrations** are MCP servers. Presets provide known configurations, and
-  the custom integration panel accepts stdio, HTTP, and SSE servers.
+- **MCP** lists Model Context Protocol servers. Presets provide known
+  configurations, and the **Add MCP server** panel accepts stdio, HTTP, and SSE
+  servers. Custom HTTP/SSE servers can use no authentication, OAuth, or request
+  headers. After saving an OAuth server, choose **Connect** to open its sign-in
+  page. Presets such as Xmind, Notion, and Linear already use OAuth. HTTPS and
+  localhost WebUIs return automatically; a remote plain-HTTP WebUI shows one
+  field for pasting the complete localhost callback URL.
 
 Apps intentionally does not list nanobot runtime support packages such as
 `api` or `bedrock`. Those packages enable providers, servers, or channels; they
@@ -226,8 +231,8 @@ endpoint and exposes `web_search` and `web_fetch` without requiring an API key.
 It is an optional integration and does not replace nanobot's built-in web search
 provider; mention `@parallel-search` when a turn should use it.
 
-After an App or integration is available, mention it from the composer with
-`@` to attach that tool to the next message.
+After an App or MCP server is available, mention it from the composer with `@`
+to attach that tool to the next message.
 
 ## Skills
 

nanobot/agent/tools/filesystem.py

@@ -827,7 +827,8 @@ class EditFileTool(_FsTool):
     def description(self) -> str:
         return (
             "Perform a small, exact replacement in one file by replacing "
-            "old_text with new_text. Use this for narrow text substitutions "
+            "old_text with new_text. When replacing text in an existing file, "
+            "old_text and new_text must be different. Use this for narrow text substitutions "
             "with old_text copied from read_file. For multi-file, structural, "
             "or generated code edits, prefer apply_patch. If old_text matches "
             "multiple times, provide more context or set occurrence, line_hint, "
@@ -862,9 +863,12 @@ class EditFileTool(_FsTool):
                 return ToolResult.error("Error: expected_replacements must be >= 1.")
 
             fp = self._resolve_write(path)
+            file_exists = fp.exists()
+            if file_exists and old_text == new_text:
+                return ToolResult.error("Error: new_text must be different from old_text.")
 
             # Create-file semantics: old_text='' + file doesn't exist → create
-            if not fp.exists():
+            if not file_exists:
                 if old_text == "":
                     fp.parent.mkdir(parents=True, exist_ok=True)
                     fp.write_text(new_text, encoding="utf-8")

nanobot/agent/tools/mcp.py

@@ -38,6 +38,7 @@ if TYPE_CHECKING:
     from mcp.types import Prompt, Resource
     from mcp.types import Tool as MCPToolDefinition
 
+    from nanobot.agent.tools.mcp_oauth import MCPOAuthHandlers
     from nanobot.config.schema import MCPServerConfig
 
 # Transient connection errors that warrant a single retry.
@@ -184,6 +185,25 @@ def _is_transient(exc: BaseException) -> bool:
     return type(exc).__name__ in _TRANSIENT_EXC_NAMES
 
 
+def _is_transient_connection_failure(exc: BaseException) -> bool:
+    if isinstance(exc, BaseExceptionGroup):
+        group = cast(BaseExceptionGroup[BaseException], exc)
+        return bool(group.exceptions) and all(
+            _is_transient_connection_failure(nested) for nested in group.exceptions
+        )
+    return isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)) or _is_transient(exc)
+
+
+def _log_mcp_connection_failure(name: str, exc: BaseException, hint: str = "") -> None:
+    if _is_transient_connection_failure(exc):
+        logger.warning("MCP server '{}': transient connection failure", name)
+        logger.opt(exception=exc).debug(
+            "MCP server '{}' transient connection failure details", name
+        )
+        return
+    logger.opt(exception=exc).error("MCP server '{}': failed to connect: {}", name, hint)
+
+
 def _is_session_terminated(exc: BaseException) -> bool:
     """Return True when the MCP SDK reports a dead client session."""
     if _is_transient(exc):
@@ -961,7 +981,10 @@ class MCPPromptWrapper(_MCPWrapperBase):
 
 
 async def connect_mcp_servers(
-    mcp_servers: "dict[str, MCPServerConfig]", registry: ToolRegistry
+    mcp_servers: "dict[str, MCPServerConfig]",
+    registry: ToolRegistry,
+    *,
+    oauth_handlers: Mapping[str, "MCPOAuthHandlers"] | None = None,
 ) -> dict[str, MCPConnection]:
     """Connect to configured MCP servers and register their tools, resources, prompts.
 
@@ -1001,6 +1024,29 @@ async def connect_mcp_servers(
                     )
                     return False
 
+            oauth_auth: httpx.Auth | None = None
+            if cfg.auth == "oauth":
+                if transport_type not in {"sse", "streamableHttp"}:
+                    logger.warning(
+                        "MCP server '{}': OAuth requires an SSE or Streamable HTTP transport",
+                        name,
+                    )
+                    return False
+                from nanobot.agent.tools.mcp_oauth import (
+                    MCPAuthorizationRequiredError,
+                    create_mcp_oauth_auth,
+                )
+
+                try:
+                    oauth_auth = await create_mcp_oauth_auth(
+                        name,
+                        cfg.url,
+                        (oauth_handlers or {}).get(name),
+                    )
+                except MCPAuthorizationRequiredError:
+                    logger.info("MCP server '{}': waiting for browser authorization", name)
+                    return False
+
             if transport_type == "stdio":
                 command, args, env = _normalize_windows_stdio_command(
                     cfg.command,
@@ -1038,22 +1084,30 @@ async def connect_mcp_servers(
                         **_pinned_transport_kwargs(),
                     )
 
+                sse_kwargs: dict[str, Any] = {
+                    "httpx_client_factory": httpx_client_factory,
+                }
+                if oauth_auth is not None:
+                    sse_kwargs["auth"] = oauth_auth
                 read, write = await server_stack.enter_async_context(
-                    sse_client(cfg.url, httpx_client_factory=httpx_client_factory)
+                    sse_client(cfg.url, **sse_kwargs)
                 )
             elif transport_type == "streamableHttp":
                 if not await _probe_http_url(cfg.url):
                     logger.warning("MCP server '{}': {} unreachable, skipping", name, _redact_url(cfg.url))
                     return False
 
+                http_client_kwargs: dict[str, Any] = {
+                    "headers": cfg.headers or None,
+                    "event_hooks": {"request": [_validate_mcp_request_url]},
+                    "follow_redirects": True,
+                    "timeout": httpx.Timeout(30.0, connect=10.0),
+                    **_pinned_transport_kwargs(),
+                }
+                if oauth_auth is not None:
+                    http_client_kwargs["auth"] = oauth_auth
                 http_client = await server_stack.enter_async_context(
-                    httpx.AsyncClient(
-                        headers=cfg.headers or None,
-                        event_hooks={"request": [_validate_mcp_request_url]},
-                        follow_redirects=True,
-                        timeout=httpx.Timeout(30.0, connect=10.0),
-                        **_pinned_transport_kwargs(),
-                    )
+                    httpx.AsyncClient(**http_client_kwargs)
                 )
                 read, write, _ = await server_stack.enter_async_context(
                     streamable_http_client(cfg.url, http_client=http_client)
@@ -1182,7 +1236,7 @@ async def connect_mcp_servers(
                     " Hint: this looks like stdio protocol pollution. Make sure the MCP server writes "
                     "only JSON-RPC to stdout and sends logs/debug output to stderr instead."
                 )
-            logger.exception("MCP server '{}': failed to connect: {}", name, hint)
+            _log_mcp_connection_failure(name, e, hint)
             return False
 
     async def connect_single_server(
@@ -1229,7 +1283,7 @@ async def connect_mcp_servers(
         try:
             result = await connect_single_server(name, cfg)
         except Exception as e:
-            logger.exception("MCP server '{}' connection failed: {}", name, e)
+            _log_mcp_connection_failure(name, e)
             continue
         if result[1] is not None:
             server_stacks[result[0]] = result[1]
@@ -1302,6 +1356,13 @@ async def reload_servers(state: Any, registry: ToolRegistry) -> dict[str, Any]:
         current_servers = dict(state._mcp_servers)
         current_names = set(current_servers)
         next_names = set(next_servers)
+        from nanobot.agent.tools.mcp_oauth import mcp_oauth_has_credentials
+
+        authorization_pending = {
+            name
+            for name, cfg in next_servers.items()
+            if cfg.auth == "oauth" and not mcp_oauth_has_credentials(name, cfg.url)
+        }
         removed = sorted(current_names - next_names)
         added = sorted(next_names - current_names)
         changed = sorted(
@@ -1319,9 +1380,13 @@ async def reload_servers(state: Any, registry: ToolRegistry) -> dict[str, Any]:
         retry_missing = sorted(
             name
             for name in next_names
-            if name not in state._mcp_stacks and name not in set(added) | set(changed)
+            if name not in state._mcp_stacks
+            and name not in set(added) | set(changed)
+            and name not in authorization_pending
+        )
+        to_connect_names = sorted(
+            (set(added) | set(changed) | set(retry_missing)) - authorization_pending
         )
-        to_connect_names = sorted(set(added) | set(changed) | set(retry_missing))
         to_connect = {name: next_servers[name] for name in to_connect_names}
         connected: dict[str, MCPConnection] = {}
         if to_connect:

nanobot/agent/tools/mcp_oauth.py

@@ -0,0 +1,401 @@
+"""OAuth support for remote MCP servers.
+
+This module intentionally owns MCP OAuth end to end. Provider OAuth has a
+different lifecycle and storage contract, so sharing a higher-level workflow
+would couple unrelated extension boundaries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import secrets
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypedDict, cast
+
+from filelock import FileLock
+from loguru import logger
+from mcp.client.auth import OAuthClientProvider
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+from pydantic import AnyHttpUrl, AnyUrl
+
+from nanobot.config.paths import get_data_dir
+from nanobot.utils.helpers import _write_text_atomic  # pyright: ignore[reportPrivateUsage]
+
+MCP_OAUTH_CALLBACK_PATH = "/auth/mcp/callback"
+_STORE_VERSION = 1
+_STORE_LOCK_TIMEOUT_S = 15
+_DEFAULT_REDIRECT_URI = f"http://127.0.0.1{MCP_OAUTH_CALLBACK_PATH}"
+_CLIENT_URI = AnyHttpUrl("https://github.com/HKUDS/nanobot")
+_LOGO_URI = AnyHttpUrl(
+    "https://raw.githubusercontent.com/HKUDS/nanobot/main/"
+    "webui/public/brand/nanobot_apple_touch.png"
+)
+
+
+class _StoredServer(TypedDict, total=False):
+    server_fingerprint: str
+    write_lease: str
+    tokens: dict[str, Any]
+    client_info: dict[str, Any]
+    redirect_uri: str
+
+
+class _CredentialStore(TypedDict):
+    version: int
+    servers: dict[str, _StoredServer]
+    generations: dict[str, str]
+
+
+class MCPAuthorizationRequiredError(RuntimeError):
+    """Raised when a background MCP connection needs interactive authorization."""
+
+
+@dataclass(frozen=True)
+class MCPOAuthHandlers:
+    """Browser callbacks supplied only for a user-initiated OAuth attempt."""
+
+    redirect_uri: str
+    redirect_handler: Callable[[str], Awaitable[None]]
+    callback_handler: Callable[[], Awaitable[tuple[str, str | None]]]
+    reset_credentials: bool = False
+
+
+def _store_path() -> Path:
+    return get_data_dir() / "auth" / "mcp.json"
+
+
+def _server_fingerprint(server_url: str) -> str:
+    return hashlib.sha256(server_url.strip().encode("utf-8")).hexdigest()
+
+
+def _empty_store() -> _CredentialStore:
+    return {"version": _STORE_VERSION, "servers": {}, "generations": {}}
+
+
+def _stored_server(value: object) -> _StoredServer | None:
+    if not isinstance(value, dict):
+        return None
+    raw = cast(dict[object, object], value)
+    entry: _StoredServer = {}
+    fingerprint = raw.get("server_fingerprint")
+    if isinstance(fingerprint, str):
+        entry["server_fingerprint"] = fingerprint
+    write_lease = raw.get("write_lease")
+    if isinstance(write_lease, str) and write_lease:
+        entry["write_lease"] = write_lease
+    redirect_uri = raw.get("redirect_uri")
+    if isinstance(redirect_uri, str):
+        entry["redirect_uri"] = redirect_uri
+    tokens = raw.get("tokens")
+    if isinstance(tokens, dict):
+        token_values = cast(dict[object, object], tokens)
+        if all(isinstance(key, str) for key in token_values):
+            entry["tokens"] = cast(dict[str, Any], token_values)
+    client_info = raw.get("client_info")
+    if isinstance(client_info, dict):
+        client_values = cast(dict[object, object], client_info)
+        if all(isinstance(key, str) for key in client_values):
+            entry["client_info"] = cast(dict[str, Any], client_values)
+    return entry
+
+
+def _read_store_unlocked(path: Path) -> _CredentialStore:
+    try:
+        raw = cast(object, json.loads(path.read_text(encoding="utf-8")))
+    except FileNotFoundError:
+        return _empty_store()
+    except (OSError, ValueError, TypeError) as exc:
+        logger.warning("Could not read MCP OAuth credentials: {}", type(exc).__name__)
+        return _empty_store()
+    if not isinstance(raw, dict):
+        return _empty_store()
+    payload = cast(dict[object, object], raw)
+    raw_servers = payload.get("servers")
+    if not isinstance(raw_servers, dict):
+        return _empty_store()
+    servers: dict[str, _StoredServer] = {}
+    for name, value in cast(dict[object, object], raw_servers).items():
+        entry = _stored_server(value)
+        if isinstance(name, str) and entry is not None:
+            servers[name] = entry
+    generations: dict[str, str] = {}
+    raw_generations = payload.get("generations")
+    if isinstance(raw_generations, dict):
+        for name, value in cast(dict[object, object], raw_generations).items():
+            if isinstance(name, str) and isinstance(value, str) and value:
+                generations[name] = value
+    return {
+        "version": _STORE_VERSION,
+        "servers": servers,
+        "generations": generations,
+    }
+
+
+def _with_store_lock(path: Path) -> FileLock:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return FileLock(str(path.with_suffix(".lock")), timeout=_STORE_LOCK_TIMEOUT_S)
+
+
+def _write_store_unlocked(path: Path, payload: _CredentialStore) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with suppress(OSError):
+        os.chmod(path.parent, 0o700)
+    _write_text_atomic(path, json.dumps(payload, indent=2, ensure_ascii=False))
+    with suppress(OSError):
+        os.chmod(path, 0o600)
+
+
+class MCPOAuthStorage:
+    """Persistent MCP SDK token storage, isolated by config name and server URL."""
+
+    def __init__(self, server_name: str, server_url: str) -> None:
+        self.server_name = server_name
+        self.server_fingerprint = _server_fingerprint(server_url)
+        self._observed_generation = self._read_generation_sync()
+        self._write_lease: str | None = None
+
+    def _read_generation_sync(self) -> str | None:
+        path = _store_path()
+        if not path.exists():
+            return None
+        # Writes replace the whole file atomically, so this observes either side
+        # of a concurrent deletion without blocking the async connection path.
+        return _read_store_unlocked(path)["generations"].get(self.server_name)
+
+    def _generation_is_current(self, payload: _CredentialStore) -> bool:
+        return payload["generations"].get(self.server_name) == self._observed_generation
+
+    def _entry_unlocked(self, payload: _CredentialStore) -> _StoredServer | None:
+        servers = payload["servers"]
+        entry = servers.get(self.server_name)
+        if entry is None or entry.get("server_fingerprint") != self.server_fingerprint:
+            return None
+        return entry
+
+    def _bind_entry_unlocked(
+        self,
+        payload: _CredentialStore,
+        *,
+        create: bool,
+    ) -> tuple[_StoredServer | None, bool]:
+        if not self._generation_is_current(payload):
+            return None, False
+        entry = self._entry_unlocked(payload)
+        if self._write_lease is not None:
+            if entry is None or entry.get("write_lease") != self._write_lease:
+                return None, False
+            return entry, False
+        if entry is None:
+            if not create:
+                return None, False
+            self._write_lease = secrets.token_urlsafe(24)
+            entry = _StoredServer(
+                server_fingerprint=self.server_fingerprint,
+                write_lease=self._write_lease,
+            )
+            payload["servers"][self.server_name] = entry
+            return entry, True
+        write_lease = entry.get("write_lease")
+        changed = not isinstance(write_lease, str) or not write_lease
+        if changed:
+            write_lease = secrets.token_urlsafe(24)
+            entry["write_lease"] = write_lease
+        self._write_lease = write_lease
+        return entry, changed
+
+    def _read_entry_sync(self) -> _StoredServer | None:
+        path = _store_path()
+        with _with_store_lock(path):
+            payload = _read_store_unlocked(path)
+            entry, changed = self._bind_entry_unlocked(payload, create=False)
+            if changed:
+                _write_store_unlocked(path, payload)
+            return entry
+
+    def _update_entry_sync(
+        self,
+        update: Callable[[_StoredServer], None],
+        *,
+        create: bool = True,
+        claim: bool = False,
+    ) -> bool:
+        path = _store_path()
+        with _with_store_lock(path):
+            payload = _read_store_unlocked(path)
+            if claim:
+                # A browser flow owns subsequent SDK writes until another flow
+                # claims the entry or the configured server is removed.
+                if not self._generation_is_current(payload):
+                    logger.info(
+                        "Ignored stale MCP OAuth credential claim for '{}'",
+                        self.server_name,
+                    )
+                    return False
+                entry = self._entry_unlocked(payload)
+                if entry is None:
+                    entry = _StoredServer(server_fingerprint=self.server_fingerprint)
+                    payload["servers"][self.server_name] = entry
+                self._write_lease = secrets.token_urlsafe(24)
+                entry["write_lease"] = self._write_lease
+            else:
+                entry, _ = self._bind_entry_unlocked(payload, create=create)
+                if entry is None:
+                    if self._write_lease is not None:
+                        logger.info(
+                            "Ignored stale MCP OAuth credential update for '{}'",
+                            self.server_name,
+                        )
+                    return False
+            update(entry)
+            payload["version"] = _STORE_VERSION
+            _write_store_unlocked(path, payload)
+            return True
+
+    async def get_tokens(self) -> OAuthToken | None:
+        entry = await asyncio.to_thread(self._read_entry_sync)
+        raw = entry.get("tokens") if entry is not None else None
+        if not isinstance(raw, dict):
+            return None
+        try:
+            return OAuthToken.model_validate(raw)
+        except (ValueError, TypeError):
+            logger.warning("Ignoring invalid MCP OAuth tokens for '{}'", self.server_name)
+            return None
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        raw = tokens.model_dump(mode="json", exclude_none=True)
+
+        def update(entry: _StoredServer) -> None:
+            entry["tokens"] = raw
+
+        await asyncio.to_thread(self._update_entry_sync, update)
+
+    async def clear_tokens(self) -> None:
+        def update(entry: _StoredServer) -> None:
+            entry.pop("tokens", None)
+
+        await asyncio.to_thread(self._update_entry_sync, update, create=False)
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        entry = await asyncio.to_thread(self._read_entry_sync)
+        raw = entry.get("client_info") if entry is not None else None
+        if not isinstance(raw, dict):
+            return None
+        try:
+            return OAuthClientInformationFull.model_validate(raw)
+        except (ValueError, TypeError):
+            logger.warning("Ignoring invalid MCP OAuth client info for '{}'", self.server_name)
+            return None
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        raw = client_info.model_dump(mode="json", exclude_none=True)
+
+        def update(entry: _StoredServer) -> None:
+            entry["client_info"] = raw
+
+        await asyncio.to_thread(self._update_entry_sync, update)
+
+    async def redirect_uri(self) -> str | None:
+        entry = await asyncio.to_thread(self._read_entry_sync)
+        value = entry.get("redirect_uri") if entry is not None else None
+        return value if isinstance(value, str) and value else None
+
+    async def prepare_redirect_uri(self, redirect_uri: str, *, reset: bool = False) -> None:
+        def update(entry: _StoredServer) -> None:
+            changed = entry.get("redirect_uri") != redirect_uri
+            if reset:
+                entry.pop("tokens", None)
+                entry.pop("client_info", None)
+            elif changed:
+                # Dynamic registrations bind a client to its redirect URI.
+                entry.pop("client_info", None)
+            entry["redirect_uri"] = redirect_uri
+
+        claimed = await asyncio.to_thread(self._update_entry_sync, update, claim=True)
+        if not claimed:
+            raise MCPAuthorizationRequiredError("MCP authorization was cancelled")
+
+    def has_credentials(self) -> bool:
+        entry = self._read_entry_sync()
+        raw_tokens = entry.get("tokens") if entry is not None else None
+        if not isinstance(raw_tokens, dict):
+            return False
+        tokens = cast(dict[str, object], raw_tokens)
+        access_token = tokens.get("access_token")
+        return isinstance(access_token, str) and bool(access_token)
+
+
+async def _missing_callback() -> tuple[str, str | None]:
+    raise MCPAuthorizationRequiredError("MCP server requires browser authorization")
+
+
+async def create_mcp_oauth_auth(
+    server_name: str,
+    server_url: str,
+    handlers: MCPOAuthHandlers | None = None,
+) -> OAuthClientProvider:
+    """Build the official MCP SDK OAuth provider for one configured server."""
+    storage = MCPOAuthStorage(server_name, server_url)
+    if handlers is not None:
+        await storage.prepare_redirect_uri(
+            handlers.redirect_uri,
+            reset=handlers.reset_credentials,
+        )
+        redirect_uri = handlers.redirect_uri
+        redirect_handler = handlers.redirect_handler
+        callback_handler = handlers.callback_handler
+    else:
+        if not await asyncio.to_thread(storage.has_credentials):
+            # Do not perform discovery or dynamic registration from a background
+            # startup. Interactive OAuth begins only after an explicit user action.
+            raise MCPAuthorizationRequiredError("MCP server requires browser authorization")
+        redirect_uri = await storage.redirect_uri() or _DEFAULT_REDIRECT_URI
+
+        async def authorization_required(_authorization_url: str) -> None:
+            await storage.clear_tokens()
+            raise MCPAuthorizationRequiredError("MCP server requires browser authorization")
+
+        redirect_handler = authorization_required
+        callback_handler = _missing_callback
+
+    metadata = OAuthClientMetadata(
+        redirect_uris=[AnyUrl(redirect_uri)],
+        token_endpoint_auth_method="none",
+        client_name="nanobot",
+        client_uri=_CLIENT_URI,
+        logo_uri=_LOGO_URI,
+        software_id="https://github.com/HKUDS/nanobot",
+    )
+    return OAuthClientProvider(
+        server_url,
+        metadata,
+        storage,
+        redirect_handler=redirect_handler,
+        callback_handler=callback_handler,
+        timeout=300,
+    )
+
+
+def mcp_oauth_has_credentials(server_name: str, server_url: str) -> bool:
+    """Return whether this exact configured MCP instance has an access token."""
+    return MCPOAuthStorage(server_name, server_url).has_credentials()
+
+
+def delete_mcp_oauth_credentials(server_name: str) -> bool:
+    """Delete credentials for one config name without touching other MCP instances."""
+    path = _store_path()
+    with _with_store_lock(path):
+        payload = _read_store_unlocked(path)
+        servers = payload["servers"]
+        removed = servers.pop(server_name, None) is not None
+        # Rotate even when no entry exists so a flow created before removal cannot
+        # claim the name later and resurrect credentials.
+        payload["generations"][server_name] = secrets.token_urlsafe(24)
+        _write_store_unlocked(path, payload)
+        return removed

nanobot/config/schema.py

@@ -373,6 +373,7 @@ class MCPServerConfig(Base):
     """MCP server connection configuration (stdio or HTTP)."""
 
     type: Literal["stdio", "sse", "streamableHttp"] | None = None  # auto-detected if omitted
+    auth: Literal["oauth"] | None = None  # Remote MCP OAuth; tokens are stored outside config
     command: str = ""  # Stdio: command to run (e.g. "npx")
     args: list[str] = Field(default_factory=list)  # Stdio: command arguments
     env: dict[str, str] = Field(default_factory=dict)  # Stdio: extra env vars

nanobot/webui/mcp_oauth_api.py

@@ -0,0 +1,415 @@
+"""Gateway-owned browser authorization flows for remote MCP servers."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import secrets
+import time
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import SplitResult, parse_qs, urlsplit, urlunsplit
+
+from nanobot.agent.tools.mcp import MCPConnection, connect_mcp_servers
+from nanobot.agent.tools.mcp_oauth import MCP_OAUTH_CALLBACK_PATH, MCPOAuthHandlers
+from nanobot.agent.tools.registry import ToolRegistry
+from nanobot.config.schema import MCPServerConfig
+from nanobot.security.network import validate_url_target
+from nanobot.webui.http_utils import is_loopback_host
+
+McpReload = Callable[[], Awaitable[dict[str, Any]]]
+_FLOW_TTL_S = 300
+_START_WAIT_S = 20
+_OAUTH_ERROR_RE = re.compile(r"^[a-zA-Z0-9_.-]{1,80}$")
+
+
+class McpOAuthError(Exception):
+    """Safe WebUI error for an MCP OAuth request."""
+
+    def __init__(self, message: str, status: int = 400) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+class _OAuthCallbackError(RuntimeError):
+    pass
+
+
+@dataclass
+class _McpOAuthFlow:
+    flow_id: str
+    name: str
+    cfg: MCPServerConfig
+    redirect_uri: str
+    manual_callback: bool
+    expires_at: float
+    authorization_ready: asyncio.Event = field(default_factory=asyncio.Event)
+    callback_result: asyncio.Future[tuple[str, str | None]] | None = None
+    task: asyncio.Task[bool] | None = None
+    authorization_url: str | None = None
+    state: str | None = None
+    callback_received: bool = False
+    error: str | None = None
+    reload_result: dict[str, Any] | None = None
+
+
+def _parse_mcp_oauth_redirect_uri(redirect_uri: str) -> tuple[str, SplitResult, int | None]:
+    cleaned = redirect_uri.strip()
+    parsed = urlsplit(cleaned)
+    try:
+        port = parsed.port
+    except ValueError as exc:
+        raise McpOAuthError("Invalid MCP OAuth callback URL") from exc
+    if (
+        not parsed.netloc
+        or not parsed.hostname
+        or parsed.path != MCP_OAUTH_CALLBACK_PATH
+        or parsed.query
+        or parsed.fragment
+        or parsed.username is not None
+        or parsed.password is not None
+    ):
+        raise McpOAuthError("Invalid MCP OAuth callback URL")
+    return cleaned, parsed, port
+
+
+def validate_mcp_oauth_redirect_uri(redirect_uri: str) -> str:
+    """Allow HTTPS callbacks, plus loopback HTTP for a local gateway."""
+    cleaned, parsed, _port = _parse_mcp_oauth_redirect_uri(redirect_uri)
+    if parsed.scheme == "https":
+        return cleaned
+    if parsed.scheme == "http" and is_loopback_host(parsed.netloc):
+        return cleaned
+    raise McpOAuthError("MCP OAuth callbacks must use HTTPS or localhost")
+
+
+def prepare_mcp_oauth_redirect_uri(redirect_uri: str) -> tuple[str, bool]:
+    """Use a pasteable loopback callback when a remote WebUI is served over HTTP."""
+    cleaned, parsed, port = _parse_mcp_oauth_redirect_uri(redirect_uri)
+    if parsed.scheme != "http" or is_loopback_host(parsed.netloc):
+        return validate_mcp_oauth_redirect_uri(cleaned), False
+
+    loopback = "127.0.0.1" if port is None else f"127.0.0.1:{port}"
+    manual_redirect_uri = urlunsplit(("http", loopback, parsed.path, "", ""))
+    return validate_mcp_oauth_redirect_uri(manual_redirect_uri), True
+
+
+class McpOAuthManager:
+    """Own short-lived browser flows while the gateway process is running."""
+
+    def __init__(self) -> None:
+        self._flows: dict[str, _McpOAuthFlow] = {}
+        self._states: dict[str, str] = {}
+
+    async def start(
+        self,
+        name: str,
+        cfg: MCPServerConfig,
+        redirect_uri: str,
+        *,
+        reload_mcp: McpReload,
+        reset_credentials: bool = False,
+    ) -> dict[str, Any]:
+        self._prune()
+        redirect_uri, manual_callback = prepare_mcp_oauth_redirect_uri(redirect_uri)
+        await self._cancel_name(name)
+
+        loop = asyncio.get_running_loop()
+        now = time.monotonic()
+        flow = _McpOAuthFlow(
+            flow_id=secrets.token_urlsafe(24),
+            name=name,
+            cfg=cfg,
+            redirect_uri=redirect_uri,
+            manual_callback=manual_callback,
+            expires_at=now + _FLOW_TTL_S,
+            callback_result=loop.create_future(),
+        )
+        self._flows[flow.flow_id] = flow
+        handlers = MCPOAuthHandlers(
+            redirect_uri=redirect_uri,
+            redirect_handler=lambda url: self._receive_authorization_url(flow, url),
+            callback_handler=lambda: self._wait_for_callback(flow),
+            reset_credentials=reset_credentials,
+        )
+        flow.task = asyncio.create_task(
+            self._connect_and_reload(flow, handlers, reload_mcp),
+            name=f"mcp-oauth:{name}",
+        )
+
+        ready_waiter = asyncio.create_task(flow.authorization_ready.wait())
+        try:
+            await asyncio.wait(
+                {ready_waiter, flow.task},
+                timeout=_START_WAIT_S,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+        finally:
+            ready_waiter.cancel()
+            with suppress(asyncio.CancelledError):
+                await ready_waiter
+        return self._payload(flow)
+
+    async def status(self, flow_id: str) -> dict[str, Any]:
+        self._prune()
+        flow = self._flow(flow_id)
+        return self._payload(flow)
+
+    def submit_callback(
+        self,
+        *,
+        state: str,
+        code: str | None,
+        error: str | None,
+    ) -> str:
+        self._prune()
+        flow_id = self._states.pop(state, None)
+        if flow_id is None:
+            raise McpOAuthError("This MCP authorization request has expired", status=410)
+        flow = self._flow(flow_id)
+        callback_result = flow.callback_result
+        if callback_result is None or callback_result.done():
+            raise McpOAuthError("This MCP authorization callback was already used", status=409)
+
+        flow.callback_received = True
+        if error:
+            safe_error = error if _OAUTH_ERROR_RE.fullmatch(error) else "authorization_failed"
+            flow.error = f"Authorization was not completed ({safe_error})."
+            callback_result.set_exception(_OAuthCallbackError(flow.error))
+            raise McpOAuthError(flow.error)
+        elif not code or len(code) > 8192:
+            flow.error = "The MCP server did not return an authorization code."
+            callback_result.set_exception(_OAuthCallbackError(flow.error))
+            raise McpOAuthError(flow.error)
+        else:
+            callback_result.set_result((code, state))
+        return flow.name
+
+    def submit_callback_url(self, *, flow_id: str, callback_url: str) -> dict[str, Any]:
+        """Complete a flow from a full browser callback URL pasted into the WebUI."""
+        self._prune()
+        flow = self._flow(flow_id)
+        parsed = urlsplit(callback_url.strip())
+        expected = urlsplit(flow.redirect_uri)
+        if (
+            not parsed.query
+            or parsed.fragment
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.scheme != expected.scheme
+            or parsed.netloc != expected.netloc
+            or parsed.path != expected.path
+        ):
+            raise McpOAuthError(
+                "Paste the complete callback URL from the browser address bar."
+            )
+        try:
+            query = parse_qs(parsed.query, keep_blank_values=True, max_num_fields=16)
+        except ValueError as exc:
+            raise McpOAuthError(
+                "Paste the complete callback URL from the browser address bar."
+            ) from exc
+
+        states = query.get("state", [])
+        state = states[0] if len(states) == 1 else ""
+        if not state or state != flow.state:
+            raise McpOAuthError(
+                "This callback belongs to a different or expired authorization request. "
+                "Start again.",
+                status=410,
+            )
+
+        codes = query.get("code", [])
+        errors = query.get("error", [])
+        if len(codes) > 1 or len(errors) > 1 or (codes and errors):
+            raise McpOAuthError(
+                "Paste the complete callback URL from the browser address bar."
+            )
+        code = codes[0] if len(codes) == 1 else None
+        error = errors[0] if len(errors) == 1 else None
+        if (not code and not error) or (code is not None and len(code) > 8192):
+            raise McpOAuthError(
+                "Paste the complete callback URL from the browser address bar."
+            )
+
+        self.submit_callback(state=state, code=code, error=error)
+        return self._payload(flow)
+
+    async def cancel(self, flow_id: str) -> dict[str, Any]:
+        self._prune()
+        flow = self._flow(flow_id)
+        await self._cancel_flow(flow)
+        return self._payload(flow)
+
+    async def _receive_authorization_url(
+        self,
+        flow: _McpOAuthFlow,
+        authorization_url: str,
+    ) -> None:
+        parsed = urlsplit(authorization_url)
+        if (
+            parsed.scheme != "https"
+            or not parsed.netloc
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.fragment
+        ):
+            flow.error = "The MCP server returned an unsafe authorization URL."
+            raise McpOAuthError(flow.error)
+        ok, _error = validate_url_target(authorization_url)
+        if not ok:
+            flow.error = "The MCP server returned an unsafe authorization URL."
+            raise McpOAuthError(flow.error)
+        states = parse_qs(parsed.query).get("state", [])
+        state = states[0] if len(states) == 1 else ""
+        if not state or len(state) > 512:
+            flow.error = "The MCP server returned an invalid authorization URL."
+            raise McpOAuthError(flow.error)
+        if state in self._states:
+            flow.error = "The MCP server reused an OAuth state value."
+            raise McpOAuthError(flow.error)
+        flow.authorization_url = authorization_url
+        flow.state = state
+        self._states[state] = flow.flow_id
+        flow.authorization_ready.set()
+
+    async def _wait_for_callback(self, flow: _McpOAuthFlow) -> tuple[str, str | None]:
+        callback_result = flow.callback_result
+        if callback_result is None:
+            raise _OAuthCallbackError("MCP OAuth callback is unavailable")
+        remaining = max(0.1, flow.expires_at - time.monotonic())
+        try:
+            return await asyncio.wait_for(asyncio.shield(callback_result), timeout=remaining)
+        except asyncio.TimeoutError as exc:
+            flow.error = "MCP authorization timed out."
+            raise _OAuthCallbackError(flow.error) from exc
+
+    async def _connect(self, flow: _McpOAuthFlow, handlers: MCPOAuthHandlers) -> bool:
+        connections: dict[str, MCPConnection] = {}
+        try:
+            connections = await connect_mcp_servers(
+                {flow.name: flow.cfg},
+                ToolRegistry(),
+                oauth_handlers={flow.name: handlers},
+            )
+            succeeded = flow.name in connections
+            if not succeeded and flow.error is None:
+                flow.error = "Could not complete the MCP OAuth connection."
+            return succeeded
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            if flow.error is None:
+                flow.error = "Could not complete the MCP OAuth connection."
+            return False
+        finally:
+            for connection in connections.values():
+                with suppress(Exception):
+                    await connection.aclose()
+
+    async def _connect_and_reload(
+        self,
+        flow: _McpOAuthFlow,
+        handlers: MCPOAuthHandlers,
+        reload_mcp: McpReload,
+    ) -> bool:
+        succeeded = await self._connect(flow, handlers)
+        if not succeeded:
+            return False
+        try:
+            flow.reload_result = await reload_mcp()
+            failed = flow.reload_result.get("failed")
+            if (
+                not flow.reload_result.get("ok")
+                and not flow.reload_result.get("requires_restart")
+                and isinstance(failed, list)
+                and flow.name in failed
+            ):
+                flow.reload_result = await reload_mcp()
+        except Exception:
+            flow.reload_result = {
+                "ok": False,
+                "message": "Signed in, but nanobot could not activate the MCP tools.",
+                "requires_restart": True,
+            }
+        return True
+
+    def _flow(self, flow_id: str) -> _McpOAuthFlow:
+        flow = self._flows.get(flow_id)
+        if flow is None:
+            raise McpOAuthError("Unknown or expired MCP OAuth flow", status=404)
+        return flow
+
+    def _payload(self, flow: _McpOAuthFlow) -> dict[str, Any]:
+        task = flow.task
+        connected = flow.reload_result.get("connected") if flow.reload_result is not None else None
+        if task is not None and task.cancelled():
+            status = "cancelled"
+        elif task is not None and task.done():
+            try:
+                succeeded = task.result()
+            except Exception:
+                succeeded = False
+            if not succeeded:
+                status = "failed"
+            elif flow.reload_result is None:
+                status = "authorized"
+            elif flow.reload_result.get("ok") or (
+                isinstance(connected, list) and flow.name in connected
+            ):
+                status = "connected"
+            else:
+                status = "authorized"
+        elif flow.callback_received:
+            status = "connecting"
+        elif flow.authorization_url:
+            status = "authorization_required"
+        else:
+            status = "starting"
+
+        payload: dict[str, Any] = {
+            "flow_id": flow.flow_id,
+            "name": flow.name,
+            "status": status,
+            "expires_in": max(0, int(flow.expires_at - time.monotonic())),
+        }
+        if flow.manual_callback:
+            payload["completion_input"] = "callback_url"
+        if flow.authorization_url and status == "authorization_required":
+            payload["authorization_url"] = flow.authorization_url
+        if flow.error:
+            payload["error"] = flow.error
+        if flow.reload_result is not None:
+            payload["hot_reload"] = flow.reload_result
+        return payload
+
+    async def _cancel_name(self, name: str) -> None:
+        for flow in list(self._flows.values()):
+            if flow.name == name and flow.task is not None and not flow.task.done():
+                await self._cancel_flow(flow)
+
+    async def _cancel_flow(self, flow: _McpOAuthFlow) -> None:
+        if flow.state:
+            self._states.pop(flow.state, None)
+        task = flow.task
+        if task is not None and not task.done():
+            task.cancel()
+            with suppress(BaseException):
+                await task
+
+    def _prune(self) -> None:
+        now = time.monotonic()
+        for flow_id, flow in list(self._flows.items()):
+            if flow.expires_at > now:
+                continue
+            if flow.state:
+                self._states.pop(flow.state, None)
+            if flow.task is not None and not flow.task.done():
+                flow.task.cancel()
+            callback_result = flow.callback_result
+            if callback_result is not None and not callback_result.done():
+                callback_result.cancel()
+            self._flows.pop(flow_id, None)

nanobot/webui/mcp_presets_api.py

@@ -16,6 +16,10 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, Mapping, cast
 
+from nanobot.agent.tools.mcp_oauth import (
+    delete_mcp_oauth_credentials,
+    mcp_oauth_has_credentials,
+)
 from nanobot.agent.tools.registry import ToolRegistry
 from nanobot.apps.protocol import app_manifest, compact_dict
 from nanobot.config.loader import load_config, resolve_config_env_vars, save_config
@@ -337,6 +341,63 @@ MCP_PRESETS: tuple[McpPreset, ...] = (
         ),
         note="Requires Figma Desktop Dev Mode MCP to be running locally.",
     ),
+    McpPreset(
+        name="xmind",
+        display_name="Xmind",
+        category="productivity",
+        description="Create, read, and edit cloud mind maps through Xmind.",
+        docs_url="https://xmind.com/user-guide/xmind-mcp",
+        transport="streamableHttp",
+        install_supported=True,
+        brand_domain="xmind.com",
+        brand_color="#F4B41A",
+        requires="Xmind account",
+        server=MCPServerConfig(
+            type="streamableHttp",
+            auth="oauth",
+            url="https://app.xmind.com/api/mcp",
+            tool_timeout=60,
+        ),
+        note="Connects securely in your browser with Xmind OAuth.",
+    ),
+    McpPreset(
+        name="notion",
+        display_name="Notion",
+        category="productivity",
+        description="Read and update your Notion workspace through Notion MCP.",
+        docs_url="https://developers.notion.com/guides/mcp/get-started-with-mcp",
+        transport="streamableHttp",
+        install_supported=True,
+        brand_domain="notion.so",
+        brand_color="#111111",
+        requires="Notion account",
+        server=MCPServerConfig(
+            type="streamableHttp",
+            auth="oauth",
+            url="https://mcp.notion.com/mcp",
+            tool_timeout=60,
+        ),
+        note="Connects securely in your browser with Notion OAuth.",
+    ),
+    McpPreset(
+        name="linear",
+        display_name="Linear",
+        category="productivity",
+        description="Find and manage Linear issues, projects, and comments.",
+        docs_url="https://linear.app/docs/mcp",
+        transport="streamableHttp",
+        install_supported=True,
+        brand_domain="linear.app",
+        brand_color="#5E6AD2",
+        requires="Linear account",
+        server=MCPServerConfig(
+            type="streamableHttp",
+            auth="oauth",
+            url="https://mcp.linear.app/mcp",
+            tool_timeout=60,
+        ),
+        note="Connects securely in your browser with Linear OAuth.",
+    ),
     McpPreset(
         name="github",
         display_name="GitHub",
@@ -657,6 +718,8 @@ def _status_for(preset: McpPreset, cfg: MCPServerConfig | None) -> str:
         return "not_installed" if preset.install_supported else "coming_soon"
     if any(field.required and not _field_configured(field, cfg) for field in preset.fields):
         return "missing_credentials"
+    if cfg.auth == "oauth" and not mcp_oauth_has_credentials(preset.name, cfg.url):
+        return "authorization_required"
     if cfg.command and not _command_available(cfg.command):
         return "missing_dependency"
     return "configured"
@@ -702,6 +765,7 @@ def _preset_manifest(preset: McpPreset, *, logo_url: str) -> dict[str, Any]:
         compact_dict({
             "type": "mcp",
             "transport": preset.transport,
+            "auth": server.auth if server and server.auth else None,
             "command": server.command if server and server.command else None,
             "args": list(server.args) if server and server.command else None,
             "url": _connection_summary(server) if server and server.url else None,
@@ -752,6 +816,7 @@ def _custom_manifest(name: str, cfg: MCPServerConfig) -> dict[str, Any]:
             compact_dict({
                 "type": "mcp",
                 "transport": transport,
+                "auth": cfg.auth,
                 "command": cfg.command or None,
                 "url": _connection_summary(cfg) if cfg.url else None,
             })
@@ -779,7 +844,7 @@ def _custom_manifest(name: str, cfg: MCPServerConfig) -> dict[str, Any]:
 def _preset_payload(preset: McpPreset, configured_servers: dict[str, MCPServerConfig]) -> dict[str, Any]:
     cfg = configured_servers.get(preset.name)
     status = _status_for(preset, cfg)
-    configured = cfg is not None and status not in {"missing_credentials"}
+    configured = cfg is not None and status not in {"missing_credentials", "authorization_required"}
     logo_url = _favicon_url(preset.brand_domain)
     return {
         "name": preset.name,
@@ -788,6 +853,7 @@ def _preset_payload(preset: McpPreset, configured_servers: dict[str, MCPServerCo
         "description": preset.description,
         "docs_url": preset.docs_url,
         "transport": preset.transport,
+        "auth": (cfg.auth if cfg is not None else (preset.server.auth if preset.server else None)),
         "requires": preset.requires,
         "note": preset.note,
         "install_supported": preset.install_supported,
@@ -814,7 +880,11 @@ def _custom_payload(
     transport = cfg.type
     if not transport:
         transport = "stdio" if cfg.command else ("sse" if cfg.url.rstrip("/").endswith("/sse") else "streamableHttp")
-    status = "missing_dependency" if cfg.command and not _command_available(cfg.command) else "configured"
+    if cfg.auth == "oauth" and not mcp_oauth_has_credentials(name, cfg.url):
+        status = "authorization_required"
+    else:
+        status = "missing_dependency" if cfg.command and not _command_available(cfg.command) else "configured"
+    configured = status != "authorization_required"
     return {
         "name": name,
         "display_name": name,
@@ -822,12 +892,13 @@ def _custom_payload(
         "description": "Custom MCP server from nanobot config.",
         "docs_url": "",
         "transport": transport,
+        "auth": cfg.auth,
         "requires": "",
         "note": "",
         "install_supported": True,
         "installed": True,
-        "configured": True,
-        "available": _config_available(cfg),
+        "configured": configured,
+        "available": configured and _config_available(cfg),
         "status": status,
         "logo_url": None,
         "brand_color": "#64748B",
@@ -1127,6 +1198,32 @@ def _normalize_transport(value: str | None, *, command: str = "", url: str = "")
     return normalized  # type: ignore[return-value]
 
 
+def _normalize_auth(
+    value: object,
+    *,
+    transport: Literal["stdio", "sse", "streamableHttp"],
+    url: str,
+    headers: Mapping[str, str],
+) -> Literal["oauth"] | None:
+    raw = str(value or "").strip().lower()
+    if not raw and url and not headers:
+        normalized_url = url.rstrip("/")
+        if any(
+            preset.server is not None
+            and preset.server.auth == "oauth"
+            and preset.server.url.rstrip("/") == normalized_url
+            for preset in MCP_PRESETS
+        ):
+            raw = "oauth"
+    if not raw:
+        return None
+    if raw != "oauth":
+        raise McpPresetError("unsupported MCP auth type")
+    if transport == "stdio":
+        raise McpPresetError("MCP OAuth requires a remote HTTP transport")
+    return "oauth"
+
+
 def _validated_server_name(name: str) -> str:
     if not name or _MCP_PRESET_NAME_RE.match(name) is None:
         raise McpPresetError("invalid MCP server name")
@@ -1142,6 +1239,13 @@ def _custom_server_from_query(query: QueryParams) -> tuple[str, MCPServerConfig]
         raise McpPresetError("stdio MCP servers require a command")
     if transport in {"sse", "streamableHttp"} and not url:
         raise McpPresetError("remote MCP servers require a URL")
+    headers = _parse_string_map(_query_first(query, "headers"))
+    auth = _normalize_auth(
+        _query_first(query, "auth"),
+        transport=transport,
+        url=url,
+        headers=headers,
+    )
     raw_timeout = (_query_first(query, "tool_timeout") or "").strip()
     tool_timeout = _DEFAULT_CUSTOM_TIMEOUT
     if raw_timeout:
@@ -1151,12 +1255,13 @@ def _custom_server_from_query(query: QueryParams) -> tuple[str, MCPServerConfig]
             raise McpPresetError("tool_timeout must be an integer") from exc
     cfg = MCPServerConfig(
         type=transport,
+        auth=auth,
         command=command if transport == "stdio" else "",
         args=_parse_string_list(_query_first(query, "args")),
         env=_parse_string_map(_query_first(query, "env")),
         cwd=(_query_first(query, "cwd") or "").strip() if transport == "stdio" else "",
         url=url if transport in {"sse", "streamableHttp"} else "",
-        headers=_parse_string_map(_query_first(query, "headers")),
+        headers=headers,
         tool_timeout=tool_timeout,
         enabled_tools=_parse_enabled_tools(_query_first(query, "enabled_tools")),
     )
@@ -1201,6 +1306,13 @@ def _mcp_server_config(name: str, raw: Any) -> tuple[str, MCPServerConfig]:
     headers = cast(dict[object, object], headers_value)
     if not all(isinstance(k, str) and isinstance(v, str) for k, v in headers.items()):
         raise McpPresetError(f"MCP server '{server_name}' headers must be a string object")
+    typed_headers = cast(dict[str, str], headers)
+    auth = _normalize_auth(
+        server.get("auth"),
+        transport=transport,
+        url=url,
+        headers=typed_headers,
+    )
     if not isinstance(enabled_tools_value, list):
         enabled_tools_value = ["*"]
     else:
@@ -1209,12 +1321,13 @@ def _mcp_server_config(name: str, raw: Any) -> tuple[str, MCPServerConfig]:
             enabled_tools_value = ["*"]
     return server_name, MCPServerConfig(
         type=transport,
+        auth=auth,
         command=command if transport == "stdio" else "",
         args=cast(list[str], args),
         env=cast(dict[str, str], env),
         cwd=cwd if transport == "stdio" else "",
         url=url if transport in {"sse", "streamableHttp"} else "",
-        headers=cast(dict[str, str], headers),
+        headers=typed_headers,
         tool_timeout=timeout_int,
         enabled_tools=cast(list[str], enabled_tools_value),
     )
@@ -1239,6 +1352,15 @@ def _import_mcp_servers(raw_json: str | None) -> dict[str, MCPServerConfig]:
     return out
 
 
+def _oauth_credentials_replaced(
+    previous: MCPServerConfig | None,
+    replacement: MCPServerConfig,
+) -> bool:
+    if previous is None or previous.auth != "oauth":
+        return False
+    return replacement.auth != "oauth" or replacement.url != previous.url
+
+
 def custom_mcp_action(
     action: str,
     query: QueryParams,
@@ -1248,8 +1370,11 @@ def custom_mcp_action(
     config = load_config(config_path) if config_path is not None else load_config()
     if action == "custom":
         name, cfg = _custom_server_from_query(query)
+        delete_credentials = _oauth_credentials_replaced(config.tools.mcp_servers.get(name), cfg)
         config.tools.mcp_servers[name] = cfg
         save_config(config, config_path)
+        if delete_credentials:
+            delete_mcp_oauth_credentials(name)
         payload = mcp_presets_payload(
             last_action=_server_action_message(action, name),
             config_path=config_path,
@@ -1259,8 +1384,15 @@ def custom_mcp_action(
 
     if action in {"import", "import-cursor"}:
         servers = _import_mcp_servers(_query_first(query, "config"))
+        delete_credentials = [
+            name
+            for name, cfg in servers.items()
+            if _oauth_credentials_replaced(config.tools.mcp_servers.get(name), cfg)
+        ]
         config.tools.mcp_servers.update(servers)
         save_config(config, config_path)
+        for name in delete_credentials:
+            delete_mcp_oauth_credentials(name)
         payload = mcp_presets_payload(
             last_action={
                 "ok": True,
@@ -1289,6 +1421,27 @@ def custom_mcp_action(
     raise McpPresetError(f"unknown MCP action '{action}'", status=404)
 
 
+def ensure_mcp_oauth_server(
+    query: QueryParams,
+    *,
+    config_path: Path | None = None,
+) -> tuple[str, MCPServerConfig]:
+    """Materialize an OAuth preset on first click and return its saved config."""
+    name = _validated_server_name((_query_first(query, "name") or "").strip())
+    config = load_config(config_path) if config_path is not None else load_config()
+    cfg = config.tools.mcp_servers.get(name)
+    if cfg is None:
+        preset = _preset_by_name(name)
+        if preset.server is None or preset.server.auth != "oauth":
+            raise McpPresetError("MCP server does not support browser authorization", status=409)
+        cfg = _materialize_server(preset, query, None)
+        config.tools.mcp_servers[name] = cfg
+        save_config(config, config_path)
+    if cfg.auth != "oauth" or cfg.type not in {"sse", "streamableHttp"} or not cfg.url:
+        raise McpPresetError("MCP server is not configured for OAuth", status=409)
+    return name, cfg
+
+
 def mcp_presets_action(
     action: str,
     query: QueryParams,
@@ -1328,6 +1481,7 @@ def mcp_presets_action(
                 cleanup_error = str(exc)
             del config.tools.mcp_servers[name]
             save_config(config, config_path)
+            delete_mcp_oauth_credentials(name)
         last_action = (
             _action_message(action, preset)
             if preset is not None

nanobot/webui/settings_capabilities.py

@@ -1,804 +0,0 @@
-"""Capability settings domain logic for Web, media, network, and API features."""
-
-from __future__ import annotations
-
-import asyncio
-import os
-import re
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Awaitable, Callable, TypedDict
-
-from nanobot.agent.tools.web import SEARCH_PROVIDER_OPTIONS
-from nanobot.api.runtime import ApiRuntime, ApiStartOptions
-from nanobot.audio.transcription import resolve_transcription_config
-from nanobot.audio.transcription_registry import (
-    resolve_transcription_provider,
-    transcription_provider_names,
-)
-from nanobot.config.schema import Config
-from nanobot.optional_features import (
-    OptionalFeatureError,
-    extra_installed,
-    optional_dependency_groups,
-)
-from nanobot.providers.image_generation import (
-    get_image_gen_provider,
-    image_gen_provider_names,
-)
-from nanobot.providers.registry import find_by_name
-from nanobot.security.network import is_loopback_host
-from nanobot.webui.settings_contracts import (
-    QueryParams,
-    SettingsRequest,
-    SettingsRouteResult,
-    WebUISettingsError,
-    parse_bool,
-    query_first,
-    query_first_alias,
-)
-from nanobot.webui.settings_models import (
-    OAuthStatusReader,
-    mask_secret_hint,
-    provider_configured_for_settings,
-)
-from nanobot.webui.workspaces import (
-    read_webui_default_access_mode,
-)
-
-if TYPE_CHECKING:
-    from nanobot.webui.settings_services import WebUISettingsServices
-
-SettingsOperation = Callable[..., dict[str, Any]]
-
-
-@dataclass(frozen=True)
-class CapabilitySettingsOperations:
-    update_web_search: SettingsOperation
-    update_api: SettingsOperation
-    update_image: SettingsOperation
-    update_transcription: SettingsOperation
-    update_network: SettingsOperation
-    nanobot_features_action: SettingsOperation
-    api_runtime: Callable[[], ApiRuntime]
-    reload_image: Callable[[], Awaitable[dict[str, Any]]]
-
-
-class CapabilitySettingsPayload(TypedDict):
-    web_search: dict[str, Any]
-    web: dict[str, Any]
-    api: dict[str, Any]
-    observability: dict[str, Any]
-    image_generation: dict[str, Any]
-    transcription: dict[str, Any]
-
-
-_WEB_SEARCH_PROVIDER_OPTIONS = SEARCH_PROVIDER_OPTIONS
-_WEB_SEARCH_PROVIDER_BY_NAME = {
-    provider["name"]: provider for provider in _WEB_SEARCH_PROVIDER_OPTIONS
-}
-_IMAGE_GENERATION_ASPECT_RATIOS = {
-    "1:1",
-    "3:4",
-    "9:16",
-    "4:3",
-    "16:9",
-    "3:2",
-    "2:3",
-    "21:9",
-}
-
-
-def _image_generation_provider_rows(
-    config: Config,
-    *,
-    oauth_status: OAuthStatusReader,
-) -> list[dict[str, Any]]:
-    rows: list[dict[str, Any]] = []
-    for name in image_gen_provider_names():
-        image_provider = get_image_gen_provider(name)
-        spec = find_by_name(name)
-        provider_config = getattr(config.providers, name, None)
-        configured = (
-            provider_configured_for_settings(spec, provider_config, oauth_status)
-            if spec is not None and provider_config is not None
-            else bool(getattr(provider_config, "api_key", None))
-        )
-        rows.append(
-            {
-                "name": name,
-                "label": spec.label if spec is not None else name,
-                "configured": configured,
-                "auth_type": "oauth" if spec is not None and spec.is_oauth else "api_key",
-                "api_key_hint": mask_secret_hint(getattr(provider_config, "api_key", None)),
-                "api_base": getattr(provider_config, "api_base", None),
-                "default_api_base": (
-                    spec.default_api_base if spec and spec.default_api_base else None
-                ),
-                "models": list(image_provider.model_options) if image_provider else [],
-                "default_model": (
-                    image_provider.model_options[0]
-                    if image_provider and image_provider.model_options
-                    else None
-                ),
-            }
-        )
-    return rows
-
-
-def _transcription_provider_rows(config: Config) -> list[dict[str, Any]]:
-    rows: list[dict[str, Any]] = []
-    for name in transcription_provider_names():
-        spec = find_by_name(name)
-        provider_config = getattr(config.providers, name, None)
-        rows.append(
-            {
-                "name": name,
-                "label": spec.label if spec is not None else name,
-                "configured": bool(getattr(provider_config, "api_key", None)),
-                "api_key_hint": mask_secret_hint(getattr(provider_config, "api_key", None)),
-                "api_base": getattr(provider_config, "api_base", None),
-                "default_api_base": (
-                    spec.default_api_base if spec and spec.default_api_base else None
-                ),
-            }
-        )
-    return rows
-
-
-def capability_settings_payload(
-    config: Config,
-    *,
-    oauth_status: OAuthStatusReader,
-) -> CapabilitySettingsPayload:
-    search_config = config.tools.web.search
-    image_config = config.tools.image_generation
-    transcription = resolve_transcription_config(config)
-    search_provider = (
-        search_config.provider
-        if search_config.provider in _WEB_SEARCH_PROVIDER_BY_NAME
-        else "duckduckgo"
-    )
-    image_providers = _image_generation_provider_rows(config, oauth_status=oauth_status)
-    selected_image_provider = next(
-        (
-            provider
-            for provider in image_providers
-            if provider["name"] == image_config.provider
-        ),
-        None,
-    )
-    return {
-        "web_search": {
-            "provider": search_provider,
-            "api_key_hint": mask_secret_hint(search_config.api_key),
-            "base_url": search_config.base_url or None,
-            "max_results": search_config.max_results,
-            "timeout": search_config.timeout,
-            "providers": list(_WEB_SEARCH_PROVIDER_OPTIONS),
-        },
-        "web": {
-            "enable": config.tools.web.enable,
-            "proxy": config.tools.web.proxy,
-            "user_agent": config.tools.web.user_agent,
-            "search": {
-                "max_results": search_config.max_results,
-                "timeout": search_config.timeout,
-            },
-            "fetch": {
-                "use_jina_reader": config.tools.web.fetch.use_jina_reader,
-            },
-        },
-        "api": {
-            "host": config.api.host,
-            "port": config.api.port,
-            "timeout": config.api.timeout,
-            "api_key_hint": mask_secret_hint(config.api.api_key),
-        },
-        "observability": {
-            "provider": "langfuse",
-            "configured": bool(
-                os.environ.get("LANGFUSE_SECRET_KEY")
-                and os.environ.get("LANGFUSE_PUBLIC_KEY")
-            ),
-            "base_url": os.environ.get("LANGFUSE_BASE_URL")
-            or "https://cloud.langfuse.com",
-        },
-        "image_generation": {
-            "enabled": image_config.enabled,
-            "provider": image_config.provider,
-            "provider_configured": bool(
-                selected_image_provider and selected_image_provider["configured"]
-            ),
-            "model": image_config.model,
-            "default_aspect_ratio": image_config.default_aspect_ratio,
-            "default_image_size": image_config.default_image_size,
-            "max_images_per_turn": image_config.max_images_per_turn,
-            "save_dir": image_config.save_dir,
-            "providers": image_providers,
-        },
-        "transcription": {
-            "enabled": transcription.enabled,
-            "provider": transcription.provider,
-            "provider_configured": transcription.configured,
-            "model": transcription.model,
-            "language": transcription.language,
-            "max_duration_sec": transcription.max_duration_sec,
-            "max_upload_mb": transcription.max_upload_mb,
-            "providers": _transcription_provider_rows(config),
-        },
-    }
-
-
-def update_network_safety_settings(
-    config: Config,
-    query: QueryParams,
-) -> tuple[bool, str | None]:
-    raw_allow = (
-        query_first_alias(
-            query,
-            "webui_allow_local_service_access",
-            "webuiAllowLocalServiceAccess",
-        )
-        or query_first_alias(
-            query,
-            "allow_local_preview_access",
-            "allowLocalPreviewAccess",
-        )
-    )
-    raw_default_access_mode = query_first_alias(
-        query,
-        "webui_default_access_mode",
-        "webuiDefaultAccessMode",
-    )
-    if raw_allow is None and raw_default_access_mode is None:
-        raise WebUISettingsError(
-            "webui_allow_local_service_access or webui_default_access_mode is required"
-        )
-
-    changed = False
-    if raw_allow is not None:
-        allow_local = parse_bool(raw_allow, "webui_allow_local_service_access")
-        if config.tools.webui_allow_local_service_access != allow_local:
-            config.tools.webui_allow_local_service_access = allow_local
-            changed = True
-
-    default_access_mode: str | None = None
-    if raw_default_access_mode is not None:
-        default_access_mode = raw_default_access_mode.strip().lower()
-        if default_access_mode == "restricted":
-            default_access_mode = "default"
-        if default_access_mode not in {"default", "full"}:
-            raise WebUISettingsError(
-                "webui_default_access_mode must be default or full"
-            )
-    return changed, default_access_mode
-
-
-def update_web_search_settings(config: Config, query: QueryParams) -> tuple[bool, bool]:
-    provider_name = (query_first(query, "provider") or "").strip().lower()
-    provider_option = _WEB_SEARCH_PROVIDER_BY_NAME.get(provider_name)
-    if provider_option is None:
-        raise WebUISettingsError("unknown web search provider")
-
-    search_config = config.tools.web.search
-    web_config = config.tools.web
-    previous_provider = search_config.provider
-    changed = False
-    restart_required = False
-
-    def set_search_value(attr: str, value: object) -> None:
-        nonlocal changed
-        if getattr(search_config, attr) != value:
-            setattr(search_config, attr, value)
-            changed = True
-
-    def set_fetch_value(attr: str, value: object) -> None:
-        nonlocal changed
-        if getattr(web_config.fetch, attr) != value:
-            setattr(web_config.fetch, attr, value)
-            changed = True
-
-    if search_config.provider != provider_name:
-        search_config.provider = provider_name
-        changed = True
-
-    credential = provider_option["credential"]
-    if credential == "none":
-        set_search_value("api_key", "")
-        set_search_value("base_url", "")
-    elif credential == "base_url":
-        base_url = query_first_alias(query, "base_url", "baseUrl")
-        base_url = base_url.strip() if base_url is not None else None
-        if not base_url and previous_provider == provider_name and search_config.base_url:
-            base_url = search_config.base_url
-        if not base_url:
-            raise WebUISettingsError("base_url is required")
-        set_search_value("base_url", base_url)
-        set_search_value("api_key", "")
-    elif credential in {"api_key", "optional_api_key"}:
-        raw_api_key = query_first_alias(query, "api_key", "apiKey")
-        api_key = raw_api_key.strip() if raw_api_key is not None else None
-        if api_key is None and previous_provider == provider_name and search_config.api_key:
-            api_key = search_config.api_key
-        if credential == "api_key" and not api_key:
-            raise WebUISettingsError("api_key is required")
-        set_search_value("api_key", api_key or "")
-        set_search_value("base_url", "")
-    else:
-        raise WebUISettingsError("unknown web search credential type")
-
-    max_results = query_first_alias(query, "max_results", "maxResults")
-    if max_results is not None:
-        try:
-            parsed = int(max_results)
-        except ValueError:
-            raise WebUISettingsError("max_results must be an integer") from None
-        if parsed < 1 or parsed > 10:
-            raise WebUISettingsError("max_results must be between 1 and 10")
-        set_search_value("max_results", parsed)
-
-    timeout = query_first(query, "timeout")
-    if timeout is not None:
-        try:
-            parsed_timeout = int(timeout)
-        except ValueError:
-            raise WebUISettingsError("timeout must be an integer") from None
-        if parsed_timeout < 1 or parsed_timeout > 120:
-            raise WebUISettingsError("timeout must be between 1 and 120")
-        set_search_value("timeout", parsed_timeout)
-
-    use_jina_reader = query_first_alias(query, "use_jina_reader", "useJinaReader")
-    if use_jina_reader is not None:
-        previous_jina_reader = web_config.fetch.use_jina_reader
-        set_fetch_value("use_jina_reader", parse_bool(use_jina_reader, "use_jina_reader"))
-        if web_config.fetch.use_jina_reader != previous_jina_reader:
-            restart_required = True
-    return changed, restart_required
-
-
-def update_api_settings(config: Config, query: QueryParams) -> None:
-    """Update the managed OpenAI-compatible API configuration."""
-    api = config.api
-    host = query_first(query, "host")
-    if host is not None:
-        host = host.strip()
-        if not host:
-            raise WebUISettingsError("host is required")
-        api.host = host
-
-    port = query_first(query, "port")
-    if port is not None:
-        try:
-            parsed_port = int(port)
-        except ValueError:
-            raise WebUISettingsError("port must be an integer") from None
-        if parsed_port < 1 or parsed_port > 65535:
-            raise WebUISettingsError("port must be between 1 and 65535")
-        api.port = parsed_port
-
-    timeout = query_first(query, "timeout")
-    if timeout is not None:
-        try:
-            parsed_timeout = float(timeout)
-        except ValueError:
-            raise WebUISettingsError("timeout must be a number") from None
-        if parsed_timeout < 1 or parsed_timeout > 3600:
-            raise WebUISettingsError("timeout must be between 1 and 3600")
-        api.timeout = parsed_timeout
-
-    api_key = query_first_alias(query, "api_key", "apiKey")
-    if api_key is not None:
-        api.api_key = api_key.strip()
-    if not is_loopback_host(api.host) and not api.api_key.strip():
-        raise WebUISettingsError(
-            "an API key is required when the API is available on the network"
-        )
-
-
-def update_image_generation_settings(
-    config: Config,
-    query: QueryParams,
-    *,
-    oauth_status: OAuthStatusReader,
-) -> bool:
-    image_config = config.tools.image_generation
-    changed = False
-
-    provider_name = query_first(query, "provider")
-    if provider_name is not None:
-        provider_name = provider_name.strip().lower()
-        if not provider_name:
-            raise WebUISettingsError("image generation provider is required")
-        if get_image_gen_provider(provider_name) is None:
-            raise WebUISettingsError("unknown image generation provider")
-        if image_config.provider != provider_name:
-            image_config.provider = provider_name
-            changed = True
-
-    enabled = query_first(query, "enabled")
-    if enabled is not None:
-        parsed_enabled = parse_bool(enabled, "enabled")
-        if image_config.enabled != parsed_enabled:
-            image_config.enabled = parsed_enabled
-            changed = True
-
-    model = query_first(query, "model")
-    if model is not None:
-        model = model.strip()
-        if not model:
-            raise WebUISettingsError("image generation model is required")
-        if len(model) > 200:
-            raise WebUISettingsError("image generation model is too long")
-        if image_config.model != model:
-            image_config.model = model
-            changed = True
-
-    default_aspect_ratio = query_first_alias(
-        query,
-        "default_aspect_ratio",
-        "defaultAspectRatio",
-    )
-    if default_aspect_ratio is not None:
-        default_aspect_ratio = default_aspect_ratio.strip()
-        if default_aspect_ratio not in _IMAGE_GENERATION_ASPECT_RATIOS:
-            raise WebUISettingsError("unsupported image generation aspect ratio")
-        if image_config.default_aspect_ratio != default_aspect_ratio:
-            image_config.default_aspect_ratio = default_aspect_ratio
-            changed = True
-
-    default_image_size = query_first_alias(
-        query,
-        "default_image_size",
-        "defaultImageSize",
-    )
-    if default_image_size is not None:
-        default_image_size = default_image_size.strip()
-        if not default_image_size:
-            raise WebUISettingsError("default image size is required")
-        if len(default_image_size) > 32 or not all(
-            char.isascii() and (char.isalnum() or char in {"x", "X", ":", "-", "_"})
-            for char in default_image_size
-        ):
-            raise WebUISettingsError("unsupported image generation size")
-        if image_config.default_image_size != default_image_size:
-            image_config.default_image_size = default_image_size
-            changed = True
-
-    max_images_per_turn = query_first_alias(
-        query,
-        "max_images_per_turn",
-        "maxImagesPerTurn",
-    )
-    if max_images_per_turn is not None:
-        try:
-            parsed_max = int(max_images_per_turn)
-        except ValueError:
-            raise WebUISettingsError("max_images_per_turn must be an integer") from None
-        if parsed_max < 1 or parsed_max > 8:
-            raise WebUISettingsError("max_images_per_turn must be between 1 and 8")
-        if image_config.max_images_per_turn != parsed_max:
-            image_config.max_images_per_turn = parsed_max
-            changed = True
-
-    if image_config.enabled:
-        selected_provider = next(
-            (
-                provider
-                for provider in _image_generation_provider_rows(
-                    config,
-                    oauth_status=oauth_status,
-                )
-                if provider["name"] == image_config.provider
-            ),
-            None,
-        )
-        if not selected_provider or not selected_provider["configured"]:
-            raise WebUISettingsError("image generation provider is not configured")
-    return changed
-
-
-def update_transcription_settings(config: Config, query: QueryParams) -> bool:
-    transcription = config.transcription
-    changed = False
-
-    enabled = query_first(query, "enabled")
-    if enabled is not None:
-        parsed_enabled = parse_bool(enabled, "enabled")
-        if transcription.enabled != parsed_enabled:
-            transcription.enabled = parsed_enabled
-            changed = True
-
-    provider = query_first(query, "provider")
-    if provider is not None:
-        provider = provider.strip().lower()
-        provider_spec = resolve_transcription_provider(provider)
-        if provider_spec is None:
-            raise WebUISettingsError("unknown transcription provider")
-        provider = provider_spec.name
-        if transcription.provider != provider:
-            transcription.provider = provider
-            changed = True
-
-    model = query_first(query, "model")
-    if model is not None:
-        model = model.strip() or None
-        if model is not None and len(model) > 200:
-            raise WebUISettingsError("transcription model is too long")
-        if transcription.model != model:
-            transcription.model = model
-            changed = True
-
-    language = query_first(query, "language")
-    if language is not None:
-        language = language.strip().lower() or None
-        if language is not None and not re.fullmatch(r"[a-z]{2,3}", language):
-            raise WebUISettingsError(
-                "transcription language must be 2-3 lowercase letters"
-            )
-        if transcription.language != language:
-            transcription.language = language
-            changed = True
-
-    max_duration_sec = query_first_alias(query, "max_duration_sec", "maxDurationSec")
-    if max_duration_sec is not None:
-        try:
-            parsed_duration = int(max_duration_sec)
-        except ValueError:
-            raise WebUISettingsError("max_duration_sec must be an integer") from None
-        if parsed_duration < 1 or parsed_duration > 600:
-            raise WebUISettingsError("max_duration_sec must be between 1 and 600")
-        if transcription.max_duration_sec != parsed_duration:
-            transcription.max_duration_sec = parsed_duration
-            changed = True
-
-    max_upload_mb = query_first_alias(query, "max_upload_mb", "maxUploadMb")
-    if max_upload_mb is not None:
-        try:
-            parsed_upload = int(max_upload_mb)
-        except ValueError:
-            raise WebUISettingsError("max_upload_mb must be an integer") from None
-        if parsed_upload < 1 or parsed_upload > 100:
-            raise WebUISettingsError("max_upload_mb must be between 1 and 100")
-        if transcription.max_upload_mb != parsed_upload:
-            transcription.max_upload_mb = parsed_upload
-            changed = True
-    return changed
-
-
-def network_safety_payload(config: Config) -> dict[str, Any]:
-    """Return the network-related fields embedded in the advanced DTO."""
-    return {
-        "webui_allow_local_service_access": config.tools.webui_allow_local_service_access,
-        "allow_local_preview_access": config.tools.webui_allow_local_service_access,
-        "webui_default_access_mode": read_webui_default_access_mode(),
-        "private_service_protection_enabled": True,
-        "ssrf_whitelist_count": len(config.tools.ssrf_whitelist),
-    }
-
-
-def masked_api_secret(value: str) -> str | None:
-    value = value.strip()
-    if not value:
-        return None
-    return f"{value[:3]}...{value[-4:]}" if len(value) > 8 else "configured"
-
-
-def api_runtime_message(message: str) -> str:
-    known = {
-        "api_exited_during_startup": "API server exited during startup. Check its log for details.",
-        "api_stop_timeout": "API server did not stop in time.",
-        "api_state_stale": "API server state was stale; try starting it again.",
-    }
-    if message in known:
-        return known[message]
-    if message.startswith("api_"):
-        return f"API server {message.removeprefix('api_').replace('_', ' ')}"
-    return message.replace("_", " ")
-
-
-def api_service_payload(
-    settings: WebUISettingsServices,
-    runtime: ApiRuntime,
-    *,
-    last_action: str | None = None,
-) -> dict[str, Any]:
-    config = settings.config.load()
-    status = runtime.status()
-    extras = optional_dependency_groups()
-    connect_host = (
-        "127.0.0.1" if config.api.host in {"0.0.0.0", "::"} else config.api.host
-    )
-    payload = {
-        "installed": extra_installed("api", extras.get("api")),
-        "running": status.running,
-        "managed": status.running,
-        "host": config.api.host,
-        "port": config.api.port,
-        "timeout": config.api.timeout,
-        "api_key_hint": masked_api_secret(config.api.api_key),
-        "endpoint": f"http://{connect_host}:{config.api.port}/v1",
-        "command": "nanobot serve",
-        "log_path": str(status.log_path),
-    }
-    if last_action:
-        payload["last_action"] = last_action
-    return payload
-
-
-class CapabilitySettingsHandler:
-    """Handle capability commands after transport authentication and decoding."""
-
-    def __init__(self, settings: WebUISettingsServices, logger: Any) -> None:
-        self.settings = settings
-        self.logger = logger
-
-    async def handle(
-        self,
-        action: str,
-        request: SettingsRequest,
-        operations: CapabilitySettingsOperations,
-    ) -> SettingsRouteResult:
-        if action == "api-status":
-            return SettingsRouteResult.success(
-                api_service_payload(self.settings, operations.api_runtime())
-            )
-        if action == "api-start":
-            return await self._start_api(request, operations)
-        if action == "api-stop":
-            return await self._stop_api(operations)
-
-        mutation = {
-            "web-search-update": (
-                operations.update_web_search,
-                "browser",
-                False,
-            ),
-            "transcription-update": (
-                operations.update_transcription,
-                None,
-                False,
-            ),
-            "network-update": (
-                operations.update_network,
-                "runtime",
-                False,
-            ),
-            "image-update": (
-                operations.update_image,
-                "image",
-                True,
-            ),
-        }.get(action)
-        if mutation is None:
-            return SettingsRouteResult.failure(404, "unknown settings action")
-
-        operation, section, apply_image_reload = mutation
-        try:
-            payload = self.settings.mutate(operation, request.query)
-        except WebUISettingsError as exc:
-            return SettingsRouteResult.failure(exc.status, exc.message)
-        if apply_image_reload:
-            payload, image_restart_cleared = await self.apply_image_runtime_change(
-                payload,
-                operations.reload_image,
-            )
-        else:
-            image_restart_cleared = False
-        return SettingsRouteResult.success(
-            payload,
-            decorate_restart=True,
-            restart_section=section,
-            clear_restart_section=("image" if image_restart_cleared else None),
-        )
-
-    async def apply_image_runtime_change(
-        self,
-        payload: dict[str, Any],
-        reload_image: Callable[[], Awaitable[dict[str, Any]]],
-    ) -> tuple[dict[str, Any], bool]:
-        """Hot-apply image settings, preserving restart fallback on failure."""
-        if not payload.get("requires_restart"):
-            return payload, False
-        try:
-            result = await reload_image()
-        except Exception:
-            self.logger.exception("failed to hot-reload image generation settings")
-            return payload, False
-
-        applied = bool(result.get("ok")) and not result.get("requires_restart")
-        updated = dict(payload)
-        updated["requires_restart"] = not applied
-        if not applied:
-            self.logger.warning(
-                "image generation settings were saved but require restart: {}",
-                result.get("message") or "hot reload failed",
-            )
-        return updated, applied
-
-    async def _start_api(
-        self,
-        request: SettingsRequest,
-        operations: CapabilitySettingsOperations,
-    ) -> SettingsRouteResult:
-        api_key = (request.payload or {}).get("api_key")
-        if api_key is not None and not isinstance(api_key, str):
-            return SettingsRouteResult.failure(
-                400,
-                "API service API key must be a string",
-            )
-        try:
-            await asyncio.to_thread(
-                self.settings.mutate,
-                operations.nanobot_features_action,
-                "enable",
-                {"name": ["api"]},
-                allow_install=self._allow_feature_package_install(request),
-            )
-            self.settings.mutate(operations.update_api, request.query)
-            config = self.settings.config.load()
-            runtime = operations.api_runtime()
-            options = ApiStartOptions(
-                host=config.api.host,
-                port=config.api.port,
-                workspace=str(config.workspace_path),
-                config_path=str(self.settings.config.path),
-            )
-            current = runtime.status()
-            result = await asyncio.to_thread(
-                runtime.restart if current.running else runtime.start_background,
-                options,
-            )
-            if not result.ok:
-                return SettingsRouteResult.failure(
-                    500,
-                    api_runtime_message(result.message),
-                )
-        except (WebUISettingsError, OptionalFeatureError) as exc:
-            return SettingsRouteResult.failure(
-                getattr(exc, "status", 400),
-                getattr(exc, "message", str(exc)),
-            )
-        except Exception as exc:
-            self.logger.exception("failed to start managed API service")
-            return SettingsRouteResult.failure(500, str(exc))
-        return SettingsRouteResult.success(
-            api_service_payload(
-                self.settings,
-                operations.api_runtime(),
-                last_action="started",
-            )
-        )
-
-    async def _stop_api(
-        self,
-        operations: CapabilitySettingsOperations,
-    ) -> SettingsRouteResult:
-        runtime = operations.api_runtime()
-        try:
-            result = await asyncio.to_thread(runtime.stop)
-        except Exception as exc:
-            self.logger.exception("failed to stop managed API service")
-            return SettingsRouteResult.failure(500, str(exc))
-        if not result.ok and result.message != "api_not_running":
-            return SettingsRouteResult.failure(
-                500,
-                api_runtime_message(result.message),
-            )
-        return SettingsRouteResult.success(
-            api_service_payload(
-                self.settings,
-                operations.api_runtime(),
-                last_action="stopped",
-            )
-        )
-
-    def _allow_feature_package_install(self, request: SettingsRequest) -> bool:
-        if request.local_browser:
-            return True
-        try:
-            return bool(
-                self.settings.config.load().tools.webui_allow_remote_package_install
-            )
-        except Exception:
-            self.logger.exception("failed to load remote package install policy")
-            return False

nanobot/webui/settings_contracts.py

@@ -1,82 +0,0 @@
-"""Stable request and error contracts shared by WebUI settings domains."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-
-QueryParams = dict[str, list[str]]
-
-
-@dataclass(frozen=True)
-class SettingsRequest:
-    """Transport-neutral input decoded by the settings route facade."""
-
-    query: QueryParams
-    payload: dict[str, Any] | None = None
-    local_browser: bool = False
-
-
-@dataclass(frozen=True)
-class SettingsRouteResult:
-    """Transport-neutral result returned by a settings domain handler."""
-
-    payload: dict[str, Any] | None = None
-    status: int = 200
-    error: str | None = None
-    decorate_restart: bool = False
-    restart_section: str | None = None
-    clear_restart_section: str | None = None
-    restart_payload_key: str | None = None
-
-    @classmethod
-    def success(
-        cls,
-        payload: dict[str, Any],
-        *,
-        decorate_restart: bool = False,
-        restart_section: str | None = None,
-        clear_restart_section: str | None = None,
-        restart_payload_key: str | None = None,
-    ) -> SettingsRouteResult:
-        return cls(
-            payload=payload,
-            decorate_restart=decorate_restart,
-            restart_section=restart_section,
-            clear_restart_section=clear_restart_section,
-            restart_payload_key=restart_payload_key,
-        )
-
-    @classmethod
-    def failure(cls, status: int, error: str) -> SettingsRouteResult:
-        return cls(status=status, error=error)
-
-
-class WebUISettingsError(ValueError):
-    """User-facing settings validation failure."""
-
-    def __init__(self, message: str, *, status: int = 400) -> None:
-        super().__init__(message)
-        self.message = message
-        self.status = status
-
-
-def query_first(query: QueryParams, key: str) -> str | None:
-    values = query.get(key)
-    return values[0] if values else None
-
-
-def query_first_alias(query: QueryParams, snake: str, camel: str) -> str | None:
-    value = query_first(query, snake)
-    return query_first(query, camel) if value is None else value
-
-
-def query_has_alias(query: QueryParams, snake: str, camel: str) -> bool:
-    return snake in query or camel in query
-
-
-def parse_bool(value: str, field: str) -> bool:
-    normalized = value.strip().lower()
-    if normalized not in {"1", "0", "true", "false", "yes", "no"}:
-        raise WebUISettingsError(f"{field} must be boolean")
-    return normalized in {"1", "true", "yes"}

nanobot/webui/settings_system.py

@@ -1,957 +0,0 @@
-"""System and channel settings domain logic."""
-
-from __future__ import annotations
-
-import asyncio
-import inspect
-import re
-import time
-from collections.abc import Callable, Iterable
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, TypedDict, cast
-from zoneinfo import ZoneInfo
-
-from nanobot.channels._setup import channel_setup_spec
-from nanobot.channels.connect import ChannelConnectError
-from nanobot.channels.contracts import (
-    RouteFieldType,
-    channel_instance_config,
-    channel_update_instance_config,
-)
-from nanobot.config.schema import Config
-from nanobot.optional_features import OptionalFeatureError, with_channel_runtime_status
-from nanobot.security.workspace_access import workspace_sandbox_status
-from nanobot.webui.settings_capabilities import network_safety_payload
-from nanobot.webui.settings_contracts import (
-    QueryParams,
-    SettingsRequest,
-    SettingsRouteResult,
-    WebUISettingsError,
-    query_first,
-    query_first_alias,
-)
-from nanobot.webui.token_usage import token_usage_payload
-
-if TYPE_CHECKING:
-    from nanobot.webui.settings_services import WebUISettingsServices
-
-LoadChannelPlugin = Callable[[str], Any]
-ListPendingPairings = Callable[[], Iterable[dict[str, Any]]]
-SettingsOperation = Callable[..., Any]
-
-
-@dataclass(frozen=True)
-class SystemSettingsOperations:
-    cli_apps_payload: SettingsOperation
-    cli_apps_action: SettingsOperation
-    nanobot_features_payload: SettingsOperation
-    nanobot_features_action: SettingsOperation
-    nanobot_feature_instance_target: SettingsOperation
-    validate_channel_config: SettingsOperation
-    load_channel_plugin: LoadChannelPlugin
-    list_pending: ListPendingPairings
-    approve_code: SettingsOperation
-    deny_code: SettingsOperation
-    mcp_presets_action: SettingsOperation
-    reload_mcp: SettingsOperation
-    check_for_update: SettingsOperation
-    channel_feature_action: SettingsOperation | None = None
-    channel_runtime_status: Callable[[], dict[str, Any]] | None = None
-
-
-class SystemSettingsPayload(TypedDict):
-    runtime: dict[str, Any]
-    usage: dict[str, Any]
-    advanced: dict[str, Any]
-    version: dict[str, Any]
-    docs: dict[str, Any]
-
-
-_DOCS_STABLE_VERSION_RE = re.compile(r"^\d+\.\d+\.\d+(?:\.post\d+)?$")
-_DOCS_LATEST_URL = "https://nanobot.wiki/docs/latest"
-_SKIP_FIELD = object()
-
-
-def docs_version(version: str) -> str:
-    """Map package versions to the matching public docs path."""
-    normalized = version.strip()
-    if _DOCS_STABLE_VERSION_RE.fullmatch(normalized):
-        return normalized
-    return "latest"
-
-
-def docs_payload(version: str) -> dict[str, Any]:
-    selected_version = docs_version(version)
-    base_url = f"https://nanobot.wiki/docs/{selected_version}"
-    return {
-        "version": selected_version,
-        "base_url": base_url,
-        "chat_apps_url": f"{base_url}/getting-started/chat-apps",
-        "latest_url": _DOCS_LATEST_URL,
-    }
-
-
-def system_settings_payload(
-    config: Config,
-    *,
-    config_path: Path,
-    version: str,
-) -> SystemSettingsPayload:
-    defaults = config.agents.defaults
-    exec_config = config.tools.exec
-    sandbox_status = workspace_sandbox_status(
-        restrict_to_workspace=config.tools.restrict_to_workspace,
-        workspace=config.workspace_path,
-    )
-    return {
-        "runtime": {
-            "config_path": str(config_path.expanduser()),
-            "workspace_path": str(config.workspace_path),
-            "gateway_host": config.gateway.host,
-            "gateway_port": config.gateway.port,
-            "heartbeat": {
-                "enabled": config.gateway.heartbeat.enabled,
-                "interval_s": config.gateway.heartbeat.interval_s,
-                "keep_recent_messages": config.gateway.heartbeat.keep_recent_messages,
-            },
-            "dream": {
-                "schedule": defaults.dream.describe_schedule(),
-            },
-            "unified_session": defaults.unified_session,
-        },
-        "usage": token_usage_payload(timezone_name=defaults.timezone),
-        "advanced": {
-            "restrict_to_workspace": config.tools.restrict_to_workspace,
-            "workspace_sandbox": sandbox_status.as_dict(),
-            **network_safety_payload(config),
-            "mcp_server_count": len(config.tools.mcp_servers),
-            "exec_enabled": exec_config.enable,
-            "exec_sandbox": exec_config.sandbox or None,
-            "exec_path_prepend_set": bool(exec_config.path_prepend),
-            "exec_path_append_set": bool(exec_config.path_append),
-        },
-        "version": {"current": version},
-        "docs": docs_payload(version),
-    }
-
-
-def settings_usage_payload(config: Config) -> dict[str, Any]:
-    """Return the lightweight token usage slice for Overview refreshes."""
-    return token_usage_payload(timezone_name=config.agents.defaults.timezone)
-
-
-def update_agent_system_settings(config: Config, query: QueryParams) -> tuple[bool, bool]:
-    defaults = config.agents.defaults
-    changed = False
-    restart_required = False
-
-    timezone = query_first(query, "timezone")
-    if timezone is not None:
-        timezone = timezone.strip()
-        if not timezone:
-            raise WebUISettingsError("timezone is required")
-        try:
-            ZoneInfo(timezone)
-        except Exception:
-            raise WebUISettingsError("invalid timezone") from None
-        timezone_changed = defaults.timezone != timezone
-        if timezone_changed or defaults.timezone_mode != "manual":
-            defaults.timezone = timezone
-            defaults.timezone_mode = "manual"
-            changed = True
-            restart_required = timezone_changed
-
-    tool_hint_max_length = query_first_alias(
-        query,
-        "tool_hint_max_length",
-        "toolHintMaxLength",
-    )
-    if tool_hint_max_length is not None:
-        try:
-            parsed = int(tool_hint_max_length)
-        except ValueError:
-            raise WebUISettingsError(
-                "tool_hint_max_length must be an integer"
-            ) from None
-        if parsed < 20 or parsed > 500:
-            raise WebUISettingsError(
-                "tool_hint_max_length must be between 20 and 500"
-            )
-        if defaults.tool_hint_max_length != parsed:
-            defaults.tool_hint_max_length = parsed
-            changed = True
-            restart_required = True
-    return changed, restart_required
-
-
-def save_channel_config_values(
-    config: Config,
-    name: str,
-    raw_values: dict[str, Any],
-    instance_id: str = "default",
-    *,
-    load_channel_plugin: LoadChannelPlugin,
-) -> list[str]:
-    if not name:
-        raise WebUISettingsError("missing channel name")
-    try:
-        plugin = load_channel_plugin(name)
-    except ImportError:
-        raise WebUISettingsError(f"unknown channel '{name}'", status=404) from None
-    setup_spec = channel_setup_spec(name, plugin=plugin)
-    if setup_spec is None:
-        raise WebUISettingsError(
-            f"channel '{name}' cannot be configured from WebUI",
-            status=404,
-        )
-    field_types = setup_spec.route_field_types
-    if not raw_values:
-        return []
-
-    section = getattr(config.channels, name, None)
-    channel_config = channel_instance_config(
-        plugin,
-        section,
-        instance_id=instance_id,
-    )
-    saved: list[str] = []
-    prefix = f"channels.{name}."
-    for raw_key, raw_value in raw_values.items():
-        if not raw_key:
-            raise WebUISettingsError(
-                "channel settings payload contains an invalid key"
-            )
-        field = raw_key[len(prefix) :] if raw_key.startswith(prefix) else raw_key
-        value_type = field_types.get(field)
-        if value_type is None:
-            raise WebUISettingsError(f"'{raw_key}' cannot be configured from WebUI")
-        value = coerce_channel_value(raw_key, raw_value, value_type)
-        if value is _SKIP_FIELD:
-            continue
-        assign_channel_config_value(channel_config, field, value)
-        saved.append(raw_key)
-
-    try:
-        updated_section = channel_update_instance_config(
-            plugin,
-            section,
-            channel_config,
-            instance_id=instance_id,
-        )
-    except ValueError as exc:
-        raise WebUISettingsError(
-            f"Invalid {name} configuration: {exc}",
-            status=400,
-        ) from exc
-    setattr(config.channels, name, updated_section)
-    return saved
-
-
-def coerce_channel_value(
-    raw_key: str,
-    raw_value: Any,
-    value_type: RouteFieldType,
-) -> Any:
-    if isinstance(value_type, tuple):
-        kind = value_type[0]
-        allowed = value_type[1]
-    else:
-        kind = value_type
-        allowed = None
-
-    if kind in {"string", "secret"}:
-        value = raw_value.strip() if isinstance(raw_value, str) else str(raw_value)
-        if kind == "secret" and not value:
-            return _SKIP_FIELD
-        return value
-
-    if kind == "list":
-        if raw_value is None:
-            return []
-        if isinstance(raw_value, str):
-            return [item.strip() for item in raw_value.split(",") if item.strip()]
-        if isinstance(raw_value, list):
-            return [
-                str(item).strip()
-                for item in cast(list[Any], raw_value)
-                if str(item).strip()
-            ]
-        raise WebUISettingsError(f"'{raw_key}' must be a comma-separated list")
-
-    if kind == "int":
-        if raw_value in (None, ""):
-            return _SKIP_FIELD
-        try:
-            return int(raw_value)
-        except (TypeError, ValueError) as exc:
-            raise WebUISettingsError(f"'{raw_key}' must be a number") from exc
-
-    if kind == "bool":
-        if isinstance(raw_value, bool):
-            return raw_value
-        value = str(raw_value).strip().lower()
-        if value in {"true", "1", "yes", "on"}:
-            return True
-        if value in {"false", "0", "no", "off"}:
-            return False
-        raise WebUISettingsError(f"'{raw_key}' must be true or false")
-
-    if kind == "enum":
-        value = raw_value.strip() if isinstance(raw_value, str) else str(raw_value)
-        if not value:
-            return _SKIP_FIELD
-        if allowed is None or value not in allowed:
-            options = ", ".join(sorted(allowed or ()))
-            raise WebUISettingsError(f"'{raw_key}' must be one of: {options}")
-        return value
-
-    raise WebUISettingsError(f"'{raw_key}' has an unsupported field type")
-
-
-def assign_channel_config_value(
-    channel_config: dict[str, Any],
-    field: str,
-    value: Any,
-) -> None:
-    target = channel_config
-    parts = field.split(".")
-    for part in parts[:-1]:
-        current: object = target.get(part)
-        if not isinstance(current, dict):
-            current = {}
-            target[part] = current
-        target = cast(dict[str, Any], current)
-    target[parts[-1]] = value
-
-
-def pairing_payload(
-    list_pending: ListPendingPairings,
-    last_action: dict[str, Any] | None = None,
-    *,
-    now: float | None = None,
-) -> dict[str, Any]:
-    current_time = time.time() if now is None else now
-    requests: list[dict[str, Any]] = []
-    for item in list_pending():
-        expires_at = float(item.get("expires_at", 0) or 0)
-        created_at = float(item.get("created_at", 0) or 0)
-        requests.append(
-            {
-                "code": str(item.get("code", "")),
-                "channel": str(item.get("channel", "")),
-                "sender_id": str(item.get("sender_id", "")),
-                "created_at_ms": int(created_at * 1000) if created_at else None,
-                "expires_at_ms": int(expires_at * 1000) if expires_at else None,
-                "expires_in_seconds": (
-                    max(0, int(expires_at - current_time)) if expires_at else None
-                ),
-            }
-        )
-    payload: dict[str, Any] = {"requests": requests}
-    if last_action is not None:
-        payload["last_action"] = last_action
-    return payload
-
-
-class SystemSettingsHandler:
-    """Handle channel and system commands behind a transport-neutral request DTO."""
-
-    def __init__(self, settings: WebUISettingsServices, logger: Any) -> None:
-        self.settings = settings
-        self.logger = logger
-        self._channel_connectors: dict[str, Any] = {}
-
-    async def handle(
-        self,
-        action: str,
-        request: SettingsRequest,
-        operations: SystemSettingsOperations,
-        *,
-        channel_name: str | None = None,
-        connect_action: str | None = None,
-    ) -> SettingsRouteResult:
-        if action == "cli-list":
-            return await self._cli_apps(request, operations)
-        if action.startswith("cli-"):
-            return await self._cli_apps_action(
-                request,
-                action.removeprefix("cli-"),
-                operations,
-            )
-        if action == "features-list":
-            return await self._features(operations)
-        if action in {"features-enable", "features-disable"}:
-            return await self._features_action(
-                request,
-                action.removeprefix("features-"),
-                operations,
-            )
-        if action == "channel-validate":
-            return await self._channel_validate(request, operations)
-        if action == "channel-configure":
-            return await self._channel_configure(request, operations)
-        if action == "channel-connect" and channel_name and connect_action:
-            return await self._channel_connect(
-                request,
-                channel_name,
-                connect_action,
-                operations,
-            )
-        if action == "pairing-list":
-            return SettingsRouteResult.success(pairing_payload(operations.list_pending))
-        if action in {"pairing-approve", "pairing-deny"}:
-            return self._pairing_action(
-                request,
-                action.removeprefix("pairing-"),
-                operations,
-            )
-        if action == "mcp-list":
-            return await self._mcp_presets(request, None, operations)
-        if action.startswith("mcp-"):
-            return await self._mcp_presets(
-                request,
-                action.removeprefix("mcp-"),
-                operations,
-            )
-        if action == "version-check":
-            return await self._version_check(operations)
-        return SettingsRouteResult.failure(404, "unknown settings action")
-
-    async def _cli_apps(
-        self,
-        request: SettingsRequest,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        installed_only = (query_first(request.query, "installed_only") or "").lower() in {
-            "1",
-            "true",
-            "yes",
-        }
-        try:
-            payload = await operations.cli_apps_payload(
-                installed_only=installed_only,
-                config_path=self.settings.config.path,
-            )
-        except Exception:
-            self.logger.exception("failed to load CLI Apps payload")
-            return SettingsRouteResult.failure(500, "failed to load CLI Apps")
-        return SettingsRouteResult.success(payload)
-
-    async def _cli_apps_action(
-        self,
-        request: SettingsRequest,
-        action: str,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        try:
-            payload = await asyncio.to_thread(
-                operations.cli_apps_action,
-                action,
-                request.query,
-                config_path=self.settings.config.path,
-            )
-        except WebUISettingsError as exc:
-            return SettingsRouteResult.failure(exc.status, exc.message)
-        except Exception as exc:
-            status = getattr(exc, "status", 500)
-            message = getattr(exc, "message", str(exc))
-            if status >= 500:
-                self.logger.exception("CLI Apps action '{}' failed", action)
-            return SettingsRouteResult.failure(status, message)
-        return SettingsRouteResult.success(payload)
-
-    async def _features(
-        self,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        try:
-            payload = await asyncio.to_thread(
-                operations.nanobot_features_payload,
-                config_path=self.settings.config.path,
-            )
-        except Exception:
-            self.logger.exception("failed to load nanobot features")
-            return SettingsRouteResult.failure(500, "failed to load nanobot features")
-        return SettingsRouteResult.success(
-            self._with_channel_runtime_status(payload, operations)
-        )
-
-    def _nanobot_features_payload(
-        self,
-        operations: SystemSettingsOperations,
-    ) -> dict[str, Any]:
-        return operations.nanobot_features_payload(config_path=self.settings.config.path)
-
-    def _nanobot_features_action(
-        self,
-        action: str,
-        query: QueryParams,
-        operations: SystemSettingsOperations,
-        *,
-        allow_install: bool = True,
-    ) -> dict[str, Any]:
-        return self.settings.mutate(
-            operations.nanobot_features_action,
-            action,
-            query,
-            allow_install=allow_install,
-        )
-
-    async def _features_action(
-        self,
-        request: SettingsRequest,
-        action: str,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        try:
-            payload = await asyncio.to_thread(
-                self._nanobot_features_action,
-                action,
-                request.query,
-                operations,
-                allow_install=(
-                    action != "enable"
-                    or self.allow_feature_package_install(request)
-                ),
-            )
-        except OptionalFeatureError as exc:
-            return SettingsRouteResult.failure(exc.status, exc.message)
-        except Exception as exc:
-            status = getattr(exc, "status", 500)
-            message = getattr(exc, "message", str(exc))
-            if status >= 500:
-                self.logger.exception(
-                    "nanobot feature action '{}' failed",
-                    action,
-                )
-            return SettingsRouteResult.failure(status, message)
-        payload = await self._apply_feature_runtime_change(
-            action,
-            request.query,
-            payload,
-            operations,
-        )
-        payload = self._with_channel_runtime_status(payload, operations)
-        return SettingsRouteResult.success(
-            payload,
-            decorate_restart=True,
-            restart_section="runtime",
-        )
-
-    def _with_channel_runtime_status(
-        self,
-        payload: dict[str, Any],
-        operations: SystemSettingsOperations,
-    ) -> dict[str, Any]:
-        if operations.channel_runtime_status is None:
-            return payload
-        try:
-            return with_channel_runtime_status(
-                payload,
-                operations.channel_runtime_status(),
-            )
-        except Exception:
-            self.logger.exception("failed to load channel runtime status")
-            return payload
-
-    async def _apply_feature_runtime_change(
-        self,
-        action: str,
-        query: QueryParams,
-        payload: dict[str, Any],
-        operations: SystemSettingsOperations,
-    ) -> dict[str, Any]:
-        if operations.channel_feature_action is None:
-            return payload
-        name = (query_first(query, "name") or "").strip()
-        if not name:
-            return payload
-        try:
-            instance_id = operations.nanobot_feature_instance_target(query)
-            result = operations.channel_feature_action(action, name, instance_id)
-            if inspect.isawaitable(result):
-                result = await result
-        except Exception as exc:
-            self.logger.exception("failed to apply channel '{}' without restart", name)
-            return self.feature_runtime_fallback(
-                payload,
-                message=(
-                    f"{name} channel config was saved, but hot reload failed: {exc}"
-                ),
-            )
-
-        if not isinstance(result, dict):
-            return payload
-        result = cast(dict[str, Any], result)
-        if not result.get("handled"):
-            return payload
-
-        updated = dict(payload)
-        updated["requires_restart"] = bool(result.get("requires_restart"))
-        message = result.get("message")
-        if isinstance(message, str) and message:
-            last_action = dict(updated.get("last_action") or {})
-            previous = last_action.get("message")
-            last_action["message"] = (
-                f"{previous}. {message}"
-                if isinstance(previous, str) and previous
-                else message
-            )
-            last_action["hot_reload"] = not updated["requires_restart"]
-            if "ok" in result:
-                last_action["ok"] = bool(result["ok"])
-            updated["last_action"] = last_action
-        return updated
-
-    @staticmethod
-    def feature_runtime_fallback(
-        payload: dict[str, Any],
-        *,
-        message: str,
-    ) -> dict[str, Any]:
-        updated = dict(payload)
-        updated["requires_restart"] = True
-        last_action = dict(updated.get("last_action") or {})
-        previous = last_action.get("message")
-        last_action["message"] = (
-            f"{previous}. {message}"
-            if isinstance(previous, str) and previous
-            else message
-        )
-        last_action["hot_reload"] = False
-        updated["last_action"] = last_action
-        return updated
-
-    async def _channel_configure(
-        self,
-        request: SettingsRequest,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        name = (query_first(request.query, "name") or "").strip()
-        instance_id = (
-            query_first(request.query, "instance_id") or "default"
-        ).strip()
-        enable = (query_first(request.query, "enable") or "").strip().lower() in {
-            "1",
-            "true",
-            "yes",
-        }
-        try:
-            saved = await asyncio.to_thread(
-                self._save_channel_config_values,
-                name,
-                self.parse_channel_values(request),
-                instance_id,
-                operations,
-            )
-        except WebUISettingsError as exc:
-            return SettingsRouteResult.failure(exc.status, exc.message)
-        except Exception:
-            self.logger.exception("failed to save channel '{}' settings", name)
-            return SettingsRouteResult.failure(500, "failed to save channel settings")
-
-        payload: dict[str, Any] = {
-            "name": name,
-            "saved": True,
-            "saved_keys": saved,
-        }
-        if not enable:
-            features = await asyncio.to_thread(
-                self._nanobot_features_payload,
-                operations,
-            )
-            payload["nanobot_features"] = self._with_channel_runtime_status(
-                features,
-                operations,
-            )
-            return SettingsRouteResult.success(
-                payload,
-                decorate_restart=True,
-                restart_section="runtime",
-                restart_payload_key="nanobot_features",
-            )
-
-        feature_query = {"name": [name]}
-        if instance_id:
-            feature_query["instance_id"] = [instance_id]
-        try:
-            features = await asyncio.to_thread(
-                self._nanobot_features_action,
-                "enable",
-                feature_query,
-                operations,
-                allow_install=self.allow_feature_package_install(request),
-            )
-        except OptionalFeatureError as exc:
-            return SettingsRouteResult.failure(
-                exc.status,
-                f"Settings saved, but {exc.message}",
-            )
-        except Exception as exc:
-            self.logger.exception(
-                "failed to enable channel '{}' after settings save",
-                name,
-            )
-            return SettingsRouteResult.failure(
-                500,
-                f"Settings saved, but enabling {name} failed: {exc}",
-            )
-
-        features = await self._apply_feature_runtime_change(
-            "enable",
-            feature_query,
-            features,
-            operations,
-        )
-        payload["nanobot_features"] = self._with_channel_runtime_status(
-            features,
-            operations,
-        )
-        return SettingsRouteResult.success(
-            payload,
-            decorate_restart=True,
-            restart_section="runtime",
-            restart_payload_key="nanobot_features",
-        )
-
-    async def _channel_validate(
-        self,
-        request: SettingsRequest,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        name = (query_first(request.query, "name") or "").strip()
-        instance_id = (
-            query_first(request.query, "instance_id") or "default"
-        ).strip()
-        try:
-            payload = await asyncio.to_thread(
-                operations.validate_channel_config,
-                name,
-                self.parse_channel_values(request),
-                instance_id=instance_id,
-            )
-        except WebUISettingsError as exc:
-            return SettingsRouteResult.failure(exc.status, exc.message)
-        except Exception:
-            self.logger.exception("failed to validate channel '{}' settings", name)
-            return SettingsRouteResult.failure(
-                500,
-                "failed to validate channel settings",
-            )
-        return SettingsRouteResult.success(payload)
-
-    @staticmethod
-    def parse_channel_values(request: SettingsRequest) -> dict[str, Any]:
-        if request.payload is None or "values" not in request.payload:
-            return {}
-        values = request.payload.get("values")
-        if not isinstance(values, dict):
-            raise WebUISettingsError(
-                "channel settings payload must be a JSON object"
-            )
-        return cast(dict[str, Any], values)
-
-    def _save_channel_config_values(
-        self,
-        name: str,
-        raw_values: dict[str, Any],
-        instance_id: str,
-        operations: SystemSettingsOperations,
-    ) -> list[str]:
-        return self.settings.config.update(
-            lambda config: save_channel_config_values(
-                config,
-                name,
-                raw_values,
-                instance_id,
-                load_channel_plugin=operations.load_channel_plugin,
-            )
-        )
-
-    async def _channel_connect(
-        self,
-        request: SettingsRequest,
-        channel_name: str,
-        action: str,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        try:
-            connector = self._channel_connectors.get(channel_name)
-            if connector is None:
-                plugin = operations.load_channel_plugin(channel_name)
-                connector = plugin.load_connector()
-                self._channel_connectors[channel_name] = connector
-        except ImportError:
-            return SettingsRouteResult.failure(
-                404,
-                f"channel '{channel_name}' does not support connect",
-            )
-
-        try:
-            payload = await connector.handle(action, request.query)
-        except ChannelConnectError as exc:
-            return SettingsRouteResult.failure(exc.status, exc.message)
-        except Exception:
-            self.logger.exception(
-                "failed to run {} WebUI connect action for {}",
-                action,
-                channel_name,
-            )
-            return SettingsRouteResult.failure(
-                500,
-                f"failed to {action} {channel_name} connection",
-            )
-
-        if payload.get("status") != "succeeded":
-            return SettingsRouteResult.success(payload)
-        payload = await self._with_channel_connect_success(
-            request,
-            channel_name,
-            payload,
-            operations,
-        )
-        return SettingsRouteResult.success(
-            payload,
-            decorate_restart=True,
-            restart_section="runtime",
-            restart_payload_key="nanobot_features",
-        )
-
-    async def _with_channel_connect_success(
-        self,
-        request: SettingsRequest,
-        channel_name: str,
-        payload: dict[str, Any],
-        operations: SystemSettingsOperations,
-    ) -> dict[str, Any]:
-        target = {"name": [channel_name]}
-        if payload.get("instance_id"):
-            target["instance_id"] = [str(payload["instance_id"])]
-        try:
-            features = await asyncio.to_thread(
-                self._nanobot_features_action,
-                "enable",
-                target,
-                operations,
-                allow_install=self.allow_feature_package_install(request),
-            )
-        except OptionalFeatureError as exc:
-            features = self.feature_runtime_fallback(
-                self._nanobot_features_payload(operations),
-                message=(
-                    f"{channel_name} connected, but enabling channel support failed: "
-                    f"{exc.message}"
-                ),
-            )
-        else:
-            features = await self._apply_feature_runtime_change(
-                "enable",
-                target,
-                features,
-                operations,
-            )
-        updated = dict(payload)
-        updated["nanobot_features"] = self._with_channel_runtime_status(
-            features,
-            operations,
-        )
-        return updated
-
-    def allow_feature_package_install(self, request: SettingsRequest) -> bool:
-        if request.local_browser:
-            return True
-        try:
-            return bool(
-                self.settings.config.load().tools.webui_allow_remote_package_install
-            )
-        except Exception:
-            self.logger.exception("failed to load remote package install policy")
-            return False
-
-    def _pairing_action(
-        self,
-        request: SettingsRequest,
-        action: str,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        code = (query_first(request.query, "code") or "").strip()
-        if not code:
-            return SettingsRouteResult.failure(400, "Missing pairing code")
-        if action == "approve":
-            result = operations.approve_code(code)
-            if result is None:
-                return SettingsRouteResult.failure(
-                    404,
-                    "Pairing code not found or expired",
-                )
-            channel, sender_id = result
-            return SettingsRouteResult.success(
-                pairing_payload(
-                    operations.list_pending,
-                    {
-                        "ok": True,
-                        "action": "approve",
-                        "message": f"Approved {sender_id} for {channel}",
-                        "channel": channel,
-                        "sender_id": sender_id,
-                        "code": code,
-                    },
-                )
-            )
-
-        if not operations.deny_code(code):
-            return SettingsRouteResult.failure(
-                404,
-                "Pairing code not found or expired",
-            )
-        return SettingsRouteResult.success(
-            pairing_payload(
-                operations.list_pending,
-                {
-                    "ok": True,
-                    "action": "deny",
-                    "message": f"Denied pairing code {code}",
-                    "code": code,
-                },
-            )
-        )
-
-    async def _mcp_presets(
-        self,
-        request: SettingsRequest,
-        action: str | None,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        try:
-            payload = await operations.mcp_presets_action(
-                action,
-                request.query,
-                reload_mcp=operations.reload_mcp,
-                config=self.settings.config,
-            )
-        except Exception as exc:
-            status = getattr(exc, "status", 500)
-            message = getattr(exc, "message", str(exc))
-            if status >= 500:
-                self.logger.exception(
-                    "MCP preset action '{}' failed",
-                    action or "list",
-                )
-            return SettingsRouteResult.failure(status, message)
-        return SettingsRouteResult.success(
-            payload,
-            decorate_restart=action is not None,
-            restart_section="runtime" if action is not None else None,
-        )
-
-    async def _version_check(
-        self,
-        operations: SystemSettingsOperations,
-    ) -> SettingsRouteResult:
-        try:
-            update_info = await asyncio.to_thread(operations.check_for_update)
-        except Exception:
-            self.logger.exception("version check failed")
-            return SettingsRouteResult.failure(500, "version check failed")
-        return SettingsRouteResult.success({"updateAvailable": update_info})

nanobot/webui/ws_http.py

@@ -17,7 +17,7 @@ import time
 from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
-from urllib.parse import quote, unquote
+from urllib.parse import quote, unquote, urlsplit, urlunsplit
 
 from loguru import logger
 from websockets.datastructures import Headers
@@ -166,6 +166,9 @@ _WEBUI_MUTATION_PATHS = {
     "settings.mcp.import": "/api/settings/mcp-presets/import",
     "settings.mcp.import_cursor": "/api/settings/mcp-presets/import-cursor",
     "settings.mcp.tools": "/api/settings/mcp-presets/tools",
+    "settings.mcp.oauth_start": "/api/settings/mcp-oauth/start",
+    "settings.mcp.oauth_complete": "/api/settings/mcp-oauth/complete",
+    "settings.mcp.oauth_cancel": "/api/settings/mcp-oauth/cancel",
 }
 
 _WEBUI_CHANNEL_CONNECT_ACTIONS = {
@@ -344,6 +347,7 @@ class GatewayHTTPHandler:
             runtime_capabilities=self._capabilities,
             channel_feature_action=channel_feature_action,
             channel_runtime_status=channel_runtime_status,
+            mcp_oauth_redirect_uri=self._mcp_oauth_redirect_uri,
         )
 
     def workspace_controls_available(self, connection: Any) -> bool:
@@ -617,6 +621,14 @@ class GatewayHTTPHandler:
         expected_path = _normalize_config_path(self.config.path)
         return f"{scheme}://{host}{expected_path}"
 
+    def _mcp_oauth_redirect_uri(self, request: WsRequest) -> str:
+        """Derive the browser callback from the same public origin as WebSocket bootstrap."""
+        from nanobot.agent.tools.mcp_oauth import MCP_OAUTH_CALLBACK_PATH
+
+        public_ws_url = urlsplit(self._bootstrap_ws_url(request))
+        scheme = "https" if public_ws_url.scheme == "wss" else "http"
+        return urlunsplit((scheme, public_ws_url.netloc, MCP_OAUTH_CALLBACK_PATH, "", ""))
+
     # -- Session routes -----------------------------------------------------
 
     async def _dispatch_session_routes(self, request: WsRequest, got: str) -> Response | None:

tests/agent/test_mcp_connection.py

@@ -406,6 +406,52 @@ async def test_reload_mcp_servers_retries_configured_server_without_live_stack(
     await loop.close_mcp()
 
 
+@pytest.mark.asyncio
+async def test_reload_mcp_servers_skips_oauth_server_waiting_for_authorization(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
+    config = load_config()
+    notion = MCPServerConfig(
+        type="streamableHttp",
+        auth="oauth",
+        url="https://mcp.notion.test/mcp",
+    )
+    linear = MCPServerConfig(
+        type="streamableHttp",
+        auth="oauth",
+        url="https://mcp.linear.test/mcp",
+    )
+    config.tools.mcp_servers.update({"notion": notion, "linear": linear})
+    save_config(config)
+
+    attempted: list[str] = []
+
+    async def _fake_connect(servers, _registry):
+        attempted.extend(servers)
+        stack = AsyncExitStack()
+        await stack.__aenter__()
+        return {"linear": stack}
+
+    monkeypatch.setattr("nanobot.agent.tools.mcp.connect_mcp_servers", _fake_connect)
+    monkeypatch.setattr(
+        "nanobot.agent.tools.mcp_oauth.mcp_oauth_has_credentials",
+        lambda name, _url: name == "linear",
+    )
+    loop = _make_loop(tmp_path, mcp_servers={"notion": notion})
+
+    result = await mcp_runtime.reload_servers(loop, loop.tools)
+
+    assert attempted == ["linear"]
+    assert result["ok"] is True
+    assert result["failed"] == []
+    assert result["retried"] == []
+    assert result["connected"] == ["linear"]
+    await loop.close_mcp()
+
+
 @pytest.mark.asyncio
 async def test_mcp_tool_reconnects_after_session_terminated(
     tmp_path,

tests/tools/test_filesystem_tools.py

@@ -133,6 +133,16 @@ class TestEditFileTool:
         assert "Successfully" in result
         assert f.read_text() == "hello earth"
 
+    @pytest.mark.asyncio
+    async def test_identical_replacement_returns_clear_error(self, tool, tmp_path):
+        f = tmp_path / "a.py"
+        f.write_text("hello world", encoding="utf-8")
+
+        result = await tool.execute(path=str(f), old_text="world", new_text="world")
+
+        assert result == "Error: new_text must be different from old_text."
+        assert f.read_text(encoding="utf-8") == "hello world"
+
     @pytest.mark.asyncio
     async def test_crlf_normalisation(self, tool, tmp_path):
         f = tmp_path / "crlf.py"

tests/tools/test_mcp_oauth.py

@@ -0,0 +1,325 @@
+from __future__ import annotations
+
+import json
+from urllib.parse import parse_qs, urlsplit
+
+import httpx
+import pytest
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+
+from nanobot.agent.tools.mcp_oauth import (
+    MCPAuthorizationRequiredError,
+    MCPOAuthHandlers,
+    MCPOAuthStorage,
+    create_mcp_oauth_auth,
+    delete_mcp_oauth_credentials,
+    mcp_oauth_has_credentials,
+)
+from nanobot.config.schema import MCPServerConfig
+
+
+def _use_data_dir(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("nanobot.agent.tools.mcp_oauth.get_data_dir", lambda: tmp_path)
+
+
+def test_mcp_server_config_accepts_explicit_oauth() -> None:
+    config = MCPServerConfig.model_validate({
+        "type": "streamableHttp",
+        "url": "https://mcp.example.com/mcp",
+        "auth": "oauth",
+    })
+
+    assert config.auth == "oauth"
+    assert config.model_dump(by_alias=True)["auth"] == "oauth"
+
+
+@pytest.mark.asyncio
+async def test_mcp_oauth_storage_isolates_name_and_server_url(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+    storage = MCPOAuthStorage("notion-work", "https://mcp.example.com/mcp")
+    tokens = OAuthToken(access_token="access-secret", refresh_token="refresh-secret")
+    client_info = OAuthClientInformationFull(
+        redirect_uris=["https://agent.example/auth/mcp/callback"],
+        client_id="client-id",
+        client_secret="client-secret",
+    )
+
+    await storage.prepare_redirect_uri("https://agent.example/auth/mcp/callback")
+    await storage.set_tokens(tokens)
+    await storage.set_client_info(client_info)
+
+    assert await storage.get_tokens() == tokens
+    assert await storage.get_client_info() == client_info
+    assert await storage.redirect_uri() == "https://agent.example/auth/mcp/callback"
+    assert mcp_oauth_has_credentials("notion-work", "https://mcp.example.com/mcp")
+    assert not mcp_oauth_has_credentials("notion-home", "https://mcp.example.com/mcp")
+    assert not mcp_oauth_has_credentials("notion-work", "https://other.example.com/mcp")
+
+    payload = json.loads((tmp_path / "auth" / "mcp.json").read_text(encoding="utf-8"))
+    assert "https://mcp.example.com/mcp" not in str(payload)
+    assert "access-secret" in str(payload)
+
+
+@pytest.mark.asyncio
+async def test_changed_redirect_uri_discards_dynamic_registration_but_keeps_tokens(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+    storage = MCPOAuthStorage("linear", "https://mcp.linear.example/mcp")
+    await storage.prepare_redirect_uri("https://old.example/auth/mcp/callback")
+    await storage.set_tokens(OAuthToken(access_token="access-secret"))
+    await storage.set_client_info(OAuthClientInformationFull(
+        redirect_uris=["https://old.example/auth/mcp/callback"],
+        client_id="old-client",
+    ))
+
+    await storage.prepare_redirect_uri("https://new.example/auth/mcp/callback")
+
+    assert await storage.get_tokens() is not None
+    assert await storage.get_client_info() is None
+
+
+@pytest.mark.asyncio
+async def test_reset_and_delete_credentials_are_scoped_to_one_server(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+    first = MCPOAuthStorage("first", "https://mcp.example.com/mcp")
+    second = MCPOAuthStorage("second", "https://mcp.example.com/mcp")
+    await first.set_tokens(OAuthToken(access_token="first-token"))
+    await second.set_tokens(OAuthToken(access_token="second-token"))
+
+    await first.prepare_redirect_uri(
+        "https://agent.example/auth/mcp/callback",
+        reset=True,
+    )
+
+    assert await first.get_tokens() is None
+    assert await second.get_tokens() is not None
+    assert delete_mcp_oauth_credentials("first")
+    assert not delete_mcp_oauth_credentials("first")
+    assert await second.get_tokens() is not None
+
+
+@pytest.mark.asyncio
+async def test_deleted_credentials_reject_late_writes_from_stale_oauth_flow(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+    server_url = "https://mcp.linear.example/mcp"
+    stale = MCPOAuthStorage("linear", server_url)
+    await stale.prepare_redirect_uri("https://old.example/auth/mcp/callback")
+
+    assert delete_mcp_oauth_credentials("linear")
+    await stale.set_tokens(OAuthToken(access_token="late-after-delete"))
+    assert not mcp_oauth_has_credentials("linear", server_url)
+
+    replacement = MCPOAuthStorage("linear", server_url)
+    await replacement.prepare_redirect_uri("https://new.example/auth/mcp/callback")
+    await stale.set_tokens(OAuthToken(access_token="late-after-replacement"))
+
+    assert not mcp_oauth_has_credentials("linear", server_url)
+    assert await replacement.get_tokens() is None
+
+    await replacement.set_tokens(OAuthToken(access_token="fresh-token"))
+    stored = await replacement.get_tokens()
+    assert stored is not None
+    assert stored.access_token == "fresh-token"
+
+
+@pytest.mark.asyncio
+async def test_delete_before_oauth_claim_rejects_late_credential_writes(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+    server_url = "https://mcp.linear.example/mcp"
+    stale = MCPOAuthStorage("linear", server_url)
+
+    assert not delete_mcp_oauth_credentials("linear")
+    with pytest.raises(MCPAuthorizationRequiredError, match="cancelled"):
+        await stale.prepare_redirect_uri("https://old.example/auth/mcp/callback")
+    await stale.set_tokens(OAuthToken(access_token="late-after-delete"))
+    assert not mcp_oauth_has_credentials("linear", server_url)
+
+    replacement = MCPOAuthStorage("linear", server_url)
+    await replacement.prepare_redirect_uri("https://new.example/auth/mcp/callback")
+    await replacement.set_tokens(OAuthToken(access_token="fresh-token"))
+    assert mcp_oauth_has_credentials("linear", server_url)
+
+
+@pytest.mark.asyncio
+async def test_create_mcp_oauth_auth_uses_browser_handlers_and_persists_redirect(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+
+    async def redirect(_url: str) -> None:
+        return None
+
+    async def callback() -> tuple[str, str | None]:
+        return "code", "state"
+
+    handlers = MCPOAuthHandlers(
+        redirect_uri="https://agent.example/auth/mcp/callback",
+        redirect_handler=redirect,
+        callback_handler=callback,
+    )
+
+    auth = await create_mcp_oauth_auth(
+        "xmind",
+        "https://app.xmind.example/api/mcp",
+        handlers,
+    )
+
+    assert str(auth.context.client_metadata.redirect_uris[0]) == (
+        "https://agent.example/auth/mcp/callback"
+    )
+    assert str(auth.context.client_metadata.client_uri) == "https://github.com/HKUDS/nanobot"
+    assert str(auth.context.client_metadata.logo_uri) == (
+        "https://raw.githubusercontent.com/HKUDS/nanobot/main/"
+        "webui/public/brand/nanobot_apple_touch.png"
+    )
+    assert auth.context.redirect_handler is redirect
+    assert auth.context.callback_handler is callback
+    storage = MCPOAuthStorage("xmind", "https://app.xmind.example/api/mcp")
+    assert await storage.redirect_uri() == "https://agent.example/auth/mcp/callback"
+
+
+@pytest.mark.asyncio
+async def test_background_authorization_without_tokens_stops_locally(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+
+    with pytest.raises(MCPAuthorizationRequiredError):
+        await create_mcp_oauth_auth("notion", "https://mcp.notion.example/mcp")
+
+    assert not (tmp_path / "auth" / "mcp.json").exists()
+
+
+@pytest.mark.asyncio
+async def test_background_authorization_request_clears_rejected_token(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+    server_url = "https://mcp.example.com/mcp"
+    storage = MCPOAuthStorage("notion", server_url)
+    client_info = OAuthClientInformationFull(
+        redirect_uris=["https://agent.example/auth/mcp/callback"],
+        client_id="registered-client",
+    )
+    await storage.set_tokens(OAuthToken(access_token="rejected-token"))
+    await storage.set_client_info(client_info)
+    auth = await create_mcp_oauth_auth("notion", server_url)
+
+    redirect_handler = auth.context.redirect_handler
+    assert redirect_handler is not None
+    with pytest.raises(MCPAuthorizationRequiredError):
+        await redirect_handler("https://accounts.example.com/authorize?state=state")
+
+    assert await storage.get_tokens() is None
+    assert await storage.get_client_info() == client_info
+
+
+@pytest.mark.asyncio
+async def test_official_mcp_sdk_completes_discovery_registration_and_token_exchange(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_data_dir(tmp_path, monkeypatch)
+    server_url = "https://mcp.example.com/mcp"
+    authorization_url = ""
+    requests: list[tuple[str, str]] = []
+
+    async def redirect(url: str) -> None:
+        nonlocal authorization_url
+        authorization_url = url
+
+    async def callback() -> tuple[str, str | None]:
+        state = parse_qs(urlsplit(authorization_url).query)["state"][0]
+        return "authorization-code", state
+
+    auth = await create_mcp_oauth_auth(
+        "company-mcp",
+        server_url,
+        MCPOAuthHandlers(
+            redirect_uri="https://agent.example/auth/mcp/callback",
+            redirect_handler=redirect,
+            callback_handler=callback,
+        ),
+    )
+
+    async def respond(request: httpx.Request) -> httpx.Response:
+        requests.append((request.method, str(request.url)))
+        if str(request.url) == server_url:
+            if request.headers.get("Authorization") == "Bearer access-token":
+                return httpx.Response(200, json={"ok": True})
+            return httpx.Response(
+                401,
+                headers={
+                    "WWW-Authenticate": (
+                        'Bearer resource_metadata="https://mcp.example.com/'
+                        '.well-known/oauth-protected-resource"'
+                    )
+                },
+            )
+        if request.url.path == "/.well-known/oauth-protected-resource":
+            return httpx.Response(200, json={
+                "resource": server_url,
+                "authorization_servers": ["https://auth.example.com"],
+            })
+        if request.url.path == "/.well-known/oauth-authorization-server":
+            return httpx.Response(200, json={
+                "issuer": "https://auth.example.com",
+                "authorization_endpoint": "https://auth.example.com/authorize",
+                "token_endpoint": "https://auth.example.com/token",
+                "registration_endpoint": "https://auth.example.com/register",
+                "response_types_supported": ["code"],
+                "code_challenge_methods_supported": ["S256"],
+            })
+        if request.url.path == "/register":
+            registration = json.loads(request.content)
+            assert registration["client_uri"] == "https://github.com/HKUDS/nanobot"
+            assert registration["logo_uri"].endswith(
+                "/webui/public/brand/nanobot_apple_touch.png"
+            )
+            return httpx.Response(201, json={
+                "client_id": "nanobot-client",
+                "redirect_uris": ["https://agent.example/auth/mcp/callback"],
+                "token_endpoint_auth_method": "none",
+            })
+        if request.url.path == "/token":
+            return httpx.Response(200, json={
+                "access_token": "access-token",
+                "refresh_token": "refresh-token",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+            })
+        return httpx.Response(404)
+
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(respond),
+        auth=auth,
+    ) as client:
+        response = await client.get(server_url)
+
+    assert response.status_code == 200
+    assert urlsplit(authorization_url)._replace(query="").geturl() == (
+        "https://auth.example.com/authorize"
+    )
+    assert ("POST", "https://auth.example.com/register") in requests
+    assert ("POST", "https://auth.example.com/token") in requests
+    stored = await MCPOAuthStorage("company-mcp", server_url).get_tokens()
+    assert stored is not None
+    assert stored.access_token == "access-token"
+    assert stored.refresh_token == "refresh-token"

tests/tools/test_mcp_tool.py

@@ -826,19 +826,23 @@ async def test_connect_mcp_servers_logs_stdio_pollution_hint(
 ) -> None:
     messages: list[str] = []
 
-    def _error(message: str, *args: object) -> None:
-        messages.append(message.format(*args))
-
     @asynccontextmanager
     async def _broken_stdio_client(_params: object):
         raise RuntimeError("Parse error: Unexpected token 'INFO' before JSON-RPC headers")
         yield  # pragma: no cover
 
     monkeypatch.setattr(sys.modules["mcp.client.stdio"], "stdio_client", _broken_stdio_client)
-    monkeypatch.setattr("nanobot.agent.tools.mcp.logger.exception", _error)
+    sink = mcp_mod.logger.add(
+        lambda message: messages.append(message.record["message"]), level="ERROR"
+    )
 
     registry = ToolRegistry()
-    stacks = await connect_mcp_servers({"gh": MCPServerConfig(command="github-mcp")}, registry)
+    try:
+        stacks = await connect_mcp_servers(
+            {"gh": MCPServerConfig(command="github-mcp")}, registry
+        )
+    finally:
+        mcp_mod.logger.remove(sink)
 
     assert stacks == {}
     assert messages
@@ -847,6 +851,36 @@ async def test_connect_mcp_servers_logs_stdio_pollution_hint(
     assert "stderr" in messages[-1]
 
 
+def test_transient_connection_group_logs_brief_warning_and_debug_trace() -> None:
+    records: list[dict] = []
+    sink = mcp_mod.logger.add(lambda message: records.append(message.record), level="DEBUG")
+    error = ExceptionGroup("transport failed", [httpx.ConnectError("")])
+    try:
+        mcp_mod._log_mcp_connection_failure("notion", error)
+    finally:
+        mcp_mod.logger.remove(sink)
+
+    warning = next(record for record in records if record["level"].name == "WARNING")
+    debug = next(record for record in records if record["level"].name == "DEBUG")
+    assert warning["exception"] is None
+    assert "transient connection failure" in warning["message"]
+    assert debug["exception"] is not None
+    assert not any(record["level"].name == "ERROR" for record in records)
+
+
+def test_unexpected_connection_failure_keeps_error_trace() -> None:
+    records: list[dict] = []
+    sink = mcp_mod.logger.add(lambda message: records.append(message.record), level="DEBUG")
+    try:
+        mcp_mod._log_mcp_connection_failure("notion", RuntimeError("boom"))
+    finally:
+        mcp_mod.logger.remove(sink)
+
+    error = next(record for record in records if record["level"].name == "ERROR")
+    assert error["exception"] is not None
+    assert not any(record["level"].name == "WARNING" for record in records)
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "config",
@@ -1210,6 +1244,129 @@ async def test_connect_mcp_servers_streamable_http_uses_finite_timeout(
     assert timeout.pool == 30.0
 
 
+@pytest.mark.parametrize("transport", ["sse", "streamableHttp"])
+@pytest.mark.asyncio
+async def test_connect_mcp_servers_attaches_oauth_to_remote_http_client(
+    transport: str,
+    fake_mcp_runtime: dict[str, object | None],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    fake_mcp_runtime["session"] = _make_fake_session(["demo"])
+    oauth_auth = object()
+    oauth_handlers = object()
+    captured: dict[str, object] = {}
+
+    async def _reachable(_url: str) -> bool:
+        return True
+
+    def _validate(_url: str) -> tuple[bool, str]:
+        return True, ""
+
+    async def _create_auth(name: str, url: str, handlers: object) -> object:
+        captured.update(name=name, url=url, handlers=handlers)
+        return oauth_auth
+
+    oauth_mod = ModuleType("nanobot.agent.tools.mcp_oauth")
+    oauth_mod.MCPAuthorizationRequiredError = RuntimeError  # type: ignore[attr-defined]
+    oauth_mod.create_mcp_oauth_auth = _create_auth  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "nanobot.agent.tools.mcp_oauth", oauth_mod)
+
+    class FakeAsyncClient:
+        def __init__(self, *args: object, **kwargs: object) -> None:
+            captured["client_kwargs"] = kwargs
+
+        async def __aenter__(self) -> object:
+            return self
+
+        async def __aexit__(self, exc_type: object, exc: object, tb: object) -> bool:
+            return False
+
+    @asynccontextmanager
+    async def _capturing_sse_client(
+        _url: str,
+        httpx_client_factory=None,
+        auth=None,
+    ):
+        captured["transport_auth"] = auth
+        yield object(), object()
+
+    @asynccontextmanager
+    async def _capturing_streamable_http_client(_url: str, http_client=None):
+        assert http_client is not None
+        yield object(), object(), object()
+
+    monkeypatch.setattr(mcp_mod, "validate_url_target", _validate)
+    monkeypatch.setattr(mcp_mod, "_probe_http_url", _reachable)
+    monkeypatch.setattr(mcp_mod.httpx, "AsyncClient", FakeAsyncClient)
+    monkeypatch.setattr(sys.modules["mcp.client.sse"], "sse_client", _capturing_sse_client)
+    monkeypatch.setattr(
+        sys.modules["mcp.client.streamable_http"],
+        "streamable_http_client",
+        _capturing_streamable_http_client,
+    )
+
+    url = "https://mcp.example.com/sse" if transport == "sse" else "https://mcp.example.com/mcp"
+    registry = ToolRegistry()
+    stacks = await connect_mcp_servers(
+        {"remote": MCPServerConfig(type=transport, url=url, auth="oauth")},
+        registry,
+        oauth_handlers={"remote": oauth_handlers},  # type: ignore[arg-type]
+    )
+    for stack in stacks.values():
+        await stack.aclose()
+
+    assert captured["name"] == "remote"
+    assert captured["url"] == url
+    assert captured["handlers"] is oauth_handlers
+    if transport == "sse":
+        assert captured["transport_auth"] is oauth_auth
+    else:
+        client_kwargs = captured["client_kwargs"]
+        assert isinstance(client_kwargs, dict)
+        assert client_kwargs["auth"] is oauth_auth
+        assert client_kwargs["event_hooks"] == {"request": [mcp_mod._validate_mcp_request_url]}
+
+
+@pytest.mark.asyncio
+async def test_connect_mcp_servers_skips_background_oauth_without_credentials(
+    fake_mcp_runtime: dict[str, object | None],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    class AuthorizationRequiredError(RuntimeError):
+        pass
+
+    async def _create_auth(*_args: object) -> object:
+        raise AuthorizationRequiredError
+
+    probe_called = False
+
+    async def _probe(_url: str) -> bool:
+        nonlocal probe_called
+        probe_called = True
+        return True
+
+    oauth_mod = ModuleType("nanobot.agent.tools.mcp_oauth")
+    oauth_mod.MCPAuthorizationRequiredError = AuthorizationRequiredError  # type: ignore[attr-defined]
+    oauth_mod.create_mcp_oauth_auth = _create_auth  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "nanobot.agent.tools.mcp_oauth", oauth_mod)
+    monkeypatch.setattr(mcp_mod, "validate_url_target", lambda _url: (True, ""))
+    monkeypatch.setattr(mcp_mod, "_probe_http_url", _probe)
+
+    stacks = await connect_mcp_servers(
+        {
+            "remote": MCPServerConfig(
+                type="streamableHttp",
+                url="https://mcp.example.com/mcp",
+                auth="oauth",
+            )
+        },
+        ToolRegistry(),
+    )
+
+    assert stacks == {}
+    assert not probe_called
+
+
 @pytest.mark.asyncio
 async def test_connect_mcp_servers_wraps_windows_stdio_launchers(
     fake_mcp_runtime: dict[str, object | None],

tests/webui/test_mcp_oauth_api.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from nanobot.config.schema import MCPServerConfig
+from nanobot.webui.mcp_oauth_api import (
+    McpOAuthError,
+    McpOAuthManager,
+    prepare_mcp_oauth_redirect_uri,
+    validate_mcp_oauth_redirect_uri,
+)
+
+
+class _Connection:
+    def __init__(self) -> None:
+        self.closed = False
+
+    async def aclose(self) -> None:
+        self.closed = True
+
+
+def _config() -> MCPServerConfig:
+    return MCPServerConfig(
+        type="streamableHttp",
+        auth="oauth",
+        url="https://mcp.example.com/mcp",
+    )
+
+
+@pytest.mark.asyncio
+async def test_browser_flow_retries_current_server_and_ignores_unrelated_reload_failure(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    manager = McpOAuthManager()
+    connection = _Connection()
+    received: dict[str, object] = {}
+    reload_calls = 0
+
+    monkeypatch.setattr(
+        "nanobot.webui.mcp_oauth_api.validate_url_target",
+        lambda _url: (True, ""),
+    )
+
+    async def connect(servers, _registry, *, oauth_handlers):
+        assert set(servers) == {"xmind"}
+        handlers = oauth_handlers["xmind"]
+        await handlers.redirect_handler(
+            "https://accounts.example.com/authorize?client_id=test&state=state-123"
+        )
+        received["callback"] = await handlers.callback_handler()
+        return {"xmind": connection}
+
+    async def reload_mcp() -> dict[str, object]:
+        nonlocal reload_calls
+        reload_calls += 1
+        if reload_calls == 1:
+            return {
+                "ok": False,
+                "requires_restart": False,
+                "failed": ["xmind"],
+            }
+        return {
+            "ok": False,
+            "requires_restart": False,
+            "connected": ["xmind"],
+            "failed": ["notion"],
+            "message": "MCP config reloaded, but some servers did not connect: notion",
+        }
+
+    monkeypatch.setattr("nanobot.webui.mcp_oauth_api.connect_mcp_servers", connect)
+
+    started = await manager.start(
+        "xmind",
+        _config(),
+        "https://agent.example.com/auth/mcp/callback",
+        reload_mcp=reload_mcp,
+    )
+
+    assert started["status"] == "authorization_required"
+    assert started["authorization_url"].startswith("https://accounts.example.com/authorize?")
+    manager.submit_callback(state="state-123", code="oauth-code", error=None)
+    with pytest.raises(McpOAuthError, match="expired"):
+        manager.submit_callback(state="state-123", code="replayed-code", error=None)
+
+    for _ in range(10):
+        await asyncio.sleep(0)
+        if reload_calls == 2:
+            break
+    assert reload_calls == 2
+
+    for _ in range(10):
+        first, second = await asyncio.gather(
+            manager.status(started["flow_id"]),
+            manager.status(started["flow_id"]),
+        )
+        if first["status"] == "connected":
+            break
+        await asyncio.sleep(0)
+
+    assert first["status"] == "connected"
+    assert second["status"] == "connected"
+    assert first["hot_reload"]["failed"] == ["notion"]
+    assert received["callback"] == ("oauth-code", "state-123")
+    assert reload_calls == 2
+    assert connection.closed is True
+
+
+@pytest.mark.asyncio
+async def test_remote_http_flow_accepts_a_pasted_loopback_callback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    manager = McpOAuthManager()
+    connection = _Connection()
+    received: dict[str, object] = {}
+
+    monkeypatch.setattr(
+        "nanobot.webui.mcp_oauth_api.validate_url_target",
+        lambda _url: (True, ""),
+    )
+
+    async def connect(_servers, _registry, *, oauth_handlers):
+        handlers = oauth_handlers["linear"]
+        received["redirect_uri"] = handlers.redirect_uri
+        await handlers.redirect_handler(
+            "https://accounts.example.com/authorize?client_id=test&state=manual-state"
+        )
+        received["callback"] = await handlers.callback_handler()
+        return {"linear": connection}
+
+    monkeypatch.setattr("nanobot.webui.mcp_oauth_api.connect_mcp_servers", connect)
+
+    started = await manager.start(
+        "linear",
+        _config(),
+        "http://192.0.2.10:8765/auth/mcp/callback",
+        reload_mcp=lambda: asyncio.sleep(
+            0,
+            result={"ok": True, "requires_restart": False},
+        ),
+    )
+
+    assert started["status"] == "authorization_required"
+    assert started["completion_input"] == "callback_url"
+    assert received["redirect_uri"] == "http://127.0.0.1:8765/auth/mcp/callback"
+
+    with pytest.raises(McpOAuthError, match="complete callback URL"):
+        manager.submit_callback_url(
+            flow_id=started["flow_id"],
+            callback_url=(
+                "http://127.0.0.1:8765/wrong?code=oauth-code&state=manual-state"
+            ),
+        )
+    with pytest.raises(McpOAuthError, match="different or expired"):
+        manager.submit_callback_url(
+            flow_id=started["flow_id"],
+            callback_url=(
+                "http://127.0.0.1:8765/auth/mcp/callback"
+                "?code=oauth-code&state=other-state"
+            ),
+        )
+
+    submitted = manager.submit_callback_url(
+        flow_id=started["flow_id"],
+        callback_url=(
+            "http://127.0.0.1:8765/auth/mcp/callback"
+            "?code=oauth-code&state=manual-state"
+        ),
+    )
+    assert submitted["status"] == "connecting"
+
+    for _ in range(20):
+        await asyncio.sleep(0)
+        result = await manager.status(started["flow_id"])
+        if result["status"] == "connected":
+            break
+
+    assert result["status"] == "connected"
+    assert result["completion_input"] == "callback_url"
+    assert received["callback"] == ("oauth-code", "manual-state")
+    assert connection.closed is True
+
+
+@pytest.mark.asyncio
+async def test_browser_flow_surfaces_provider_denial_without_callback_description(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    manager = McpOAuthManager()
+    monkeypatch.setattr(
+        "nanobot.webui.mcp_oauth_api.validate_url_target",
+        lambda _url: (True, ""),
+    )
+
+    async def connect(_servers, _registry, *, oauth_handlers):
+        handlers = oauth_handlers["notion"]
+        await handlers.redirect_handler("https://accounts.example.com/auth?state=deny-state")
+        await handlers.callback_handler()
+        return {}
+
+    monkeypatch.setattr("nanobot.webui.mcp_oauth_api.connect_mcp_servers", connect)
+    started = await manager.start(
+        "notion",
+        _config(),
+        "https://agent.example.com/auth/mcp/callback",
+        reload_mcp=lambda: asyncio.sleep(0, result={"ok": True}),
+    )
+
+    with pytest.raises(McpOAuthError, match="access_denied"):
+        manager.submit_callback(state="deny-state", code=None, error="access_denied")
+    for _ in range(10):
+        await asyncio.sleep(0)
+        result = await manager.status(started["flow_id"])
+        if result["status"] == "failed":
+            break
+
+    assert result["status"] == "failed"
+    assert result["error"] == "Authorization was not completed (access_denied)."
+
+
+@pytest.mark.parametrize(
+    ("authorization_url", "url_is_safe", "state"),
+    [
+        ("https://127.0.0.1/authorize?state=private-state", False, "private-state"),
+        ("http://accounts.example.com/authorize?state=http-state", True, "http-state"),
+    ],
+)
+@pytest.mark.asyncio
+async def test_browser_flow_blocks_unsafe_authorization_url(
+    monkeypatch: pytest.MonkeyPatch,
+    authorization_url: str,
+    url_is_safe: bool,
+    state: str,
+) -> None:
+    manager = McpOAuthManager()
+    monkeypatch.setattr(
+        "nanobot.webui.mcp_oauth_api.validate_url_target",
+        lambda _url: (url_is_safe, "private address"),
+    )
+
+    async def connect(_servers, _registry, *, oauth_handlers):
+        await oauth_handlers["linear"].redirect_handler(authorization_url)
+        return {}
+
+    monkeypatch.setattr("nanobot.webui.mcp_oauth_api.connect_mcp_servers", connect)
+
+    result = await manager.start(
+        "linear",
+        _config(),
+        "https://agent.example.com/auth/mcp/callback",
+        reload_mcp=lambda: asyncio.sleep(0, result={"ok": True}),
+    )
+
+    assert result["status"] == "failed"
+    assert result["error"] == "The MCP server returned an unsafe authorization URL."
+    with pytest.raises(McpOAuthError, match="expired"):
+        manager.submit_callback(state=state, code="code", error=None)
+
+
+def test_redirect_uri_requires_https_except_for_loopback() -> None:
+    assert validate_mcp_oauth_redirect_uri(
+        "https://agent.example.com/auth/mcp/callback"
+    ) == "https://agent.example.com/auth/mcp/callback"
+    assert validate_mcp_oauth_redirect_uri(
+        "http://127.0.0.1:8765/auth/mcp/callback"
+    ) == "http://127.0.0.1:8765/auth/mcp/callback"
+
+    with pytest.raises(McpOAuthError, match="HTTPS or localhost"):
+        validate_mcp_oauth_redirect_uri("http://192.0.2.10/auth/mcp/callback")
+    with pytest.raises(McpOAuthError, match="Invalid"):
+        validate_mcp_oauth_redirect_uri("https://agent.example.com/wrong")
+
+
+def test_remote_http_redirect_prepares_a_manual_loopback_callback() -> None:
+    assert prepare_mcp_oauth_redirect_uri(
+        "https://agent.example.com/auth/mcp/callback"
+    ) == ("https://agent.example.com/auth/mcp/callback", False)
+    assert prepare_mcp_oauth_redirect_uri(
+        "http://127.0.0.1:8765/auth/mcp/callback"
+    ) == ("http://127.0.0.1:8765/auth/mcp/callback", False)
+    assert prepare_mcp_oauth_redirect_uri(
+        "http://agent.example.com:9443/auth/mcp/callback"
+    ) == ("http://127.0.0.1:9443/auth/mcp/callback", True)

tests/webui/test_mcp_presets_api.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 import asyncio
 
 import pytest
+from mcp.shared.auth import OAuthToken
 
+from nanobot.agent.tools.mcp_oauth import MCPOAuthStorage, mcp_oauth_has_credentials
 from nanobot.config.loader import load_config
 from nanobot.webui.mcp_presets_api import (
     McpPresetError,
@@ -38,6 +40,9 @@ def test_mcp_presets_payload_lists_supported_cards(tmp_path, monkeypatch: pytest
         "aws-docs",
         "brave-search",
         "postman",
+        "xmind",
+        "notion",
+        "linear",
     }.issubset(names)
     browserbase = next(preset for preset in payload["presets"] if preset["name"] == "browserbase")
     assert browserbase["installed"] is False
@@ -55,6 +60,37 @@ def test_mcp_presets_payload_lists_supported_cards(tmp_path, monkeypatch: pytest
     assert manifest["trust"]["review_status"] == "builtin_preset"
 
 
+@pytest.mark.asyncio
+async def test_oauth_preset_is_one_click_configured_after_token_storage(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_config(tmp_path, monkeypatch)
+
+    payload = mcp_presets_action("enable", {"name": ["xmind"]})
+
+    row = next(item for item in payload["presets"] if item["name"] == "xmind")
+    assert row["installed"] is True
+    assert row["configured"] is False
+    assert row["status"] == "authorization_required"
+    assert row["transport"] == "streamableHttp"
+    assert row["auth"] == "oauth"
+    config = load_config()
+    cfg = config.tools.mcp_servers["xmind"]
+    assert cfg.type == "streamableHttp"
+    assert cfg.auth == "oauth"
+    assert cfg.url == "https://app.xmind.com/api/mcp"
+
+    await MCPOAuthStorage("xmind", cfg.url).set_tokens(OAuthToken(access_token="secret"))
+    connected = mcp_presets_payload()
+    row = next(item for item in connected["presets"] if item["name"] == "xmind")
+    assert row["configured"] is True
+    assert row["status"] == "configured"
+
+    mcp_presets_action("remove", {"name": ["xmind"]})
+    assert await MCPOAuthStorage("xmind", cfg.url).get_tokens() is None
+
+
 def test_enable_browserbase_writes_scrubbed_config_payload(
     tmp_path,
     monkeypatch: pytest.MonkeyPatch,
@@ -296,11 +332,11 @@ def test_test_mcp_preset_scrubs_connection_errors(
     assert "<redacted>" in payload["last_action"]["error"]
 
 
-def test_unlisted_oauth_placeholder_is_not_enabled(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+def test_unknown_oauth_placeholder_is_not_enabled(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
     _use_config(tmp_path, monkeypatch)
 
     with pytest.raises(McpPresetError) as exc:
-        mcp_presets_action("enable", {"name": ["linear"]})
+        mcp_presets_action("enable", {"name": ["asana"]})
 
     assert exc.value.status == 404
 
@@ -414,6 +450,72 @@ def test_import_mcp_config_and_tool_allowlist(
     assert load_config().tools.mcp_servers["docs"].enabled_tools == []
 
 
+def test_import_recognizes_known_and_explicit_oauth_servers(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_config(tmp_path, monkeypatch)
+
+    payload = custom_mcp_action(
+        "import",
+        {
+            "config": [
+                (
+                    '{"mcpServers":{'
+                    '"notion-work":{"url":"https://mcp.notion.com/mcp"},'
+                    '"company-mcp":{"url":"https://mcp.example.com/mcp","auth":"oauth"},'
+                    '"notion-pat":{"url":"https://mcp.notion.com/mcp",'
+                    '"headers":{"Authorization":"Bearer secret"}}'
+                    '}}'
+                )
+            ],
+        },
+    )
+
+    config = load_config()
+    assert config.tools.mcp_servers["notion-work"].auth == "oauth"
+    assert config.tools.mcp_servers["company-mcp"].auth == "oauth"
+    assert config.tools.mcp_servers["notion-pat"].auth is None
+    rows = {row["name"]: row for row in payload["presets"]}
+    assert rows["notion-work"]["status"] == "authorization_required"
+    assert rows["company-mcp"]["status"] == "authorization_required"
+    assert rows["notion-pat"]["status"] == "configured"
+    assert "Bearer secret" not in str(payload)
+
+
+@pytest.mark.asyncio
+async def test_replacing_oauth_config_removes_its_stored_credentials(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _use_config(tmp_path, monkeypatch)
+    server_url = "https://mcp.example.com/mcp"
+    custom_mcp_action(
+        "custom",
+        {
+            "name": ["company-mcp"],
+            "transport": ["streamableHttp"],
+            "url": [server_url],
+            "auth": ["oauth"],
+        },
+    )
+    await MCPOAuthStorage("company-mcp", server_url).set_tokens(
+        OAuthToken(access_token="secret")
+    )
+    assert mcp_oauth_has_credentials("company-mcp", server_url)
+
+    custom_mcp_action(
+        "custom",
+        {
+            "name": ["company-mcp"],
+            "transport": ["streamableHttp"],
+            "url": [server_url],
+        },
+    )
+
+    assert not mcp_oauth_has_credentials("company-mcp", server_url)
+
+
 def test_normalize_mcp_preset_mentions_accepts_configured_custom_server(
     tmp_path,
     monkeypatch: pytest.MonkeyPatch,

tests/webui/test_settings_capabilities.py

@@ -1,62 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-from nanobot.config.schema import Config
-from nanobot.webui.settings_capabilities import (
-    capability_settings_payload,
-    update_api_settings,
-    update_image_generation_settings,
-    update_network_safety_settings,
-    update_transcription_settings,
-    update_web_search_settings,
-)
-
-
-def _oauth_status(_spec: Any) -> dict[str, Any]:
-    return {"configured": False}
-
-
-def test_capability_domain_updates_representative_settings() -> None:
-    config = Config()
-    config.providers.openrouter.api_key = "sk-test"
-
-    web_changed, web_restart = update_web_search_settings(
-        config,
-        {
-            "provider": ["duckduckgo"],
-            "max_results": ["7"],
-            "use_jina_reader": ["false"],
-        },
-    )
-    update_api_settings(
-        config,
-        {"host": ["127.0.0.2"], "port": ["8900"], "timeout": ["90"]},
-    )
-    image_changed = update_image_generation_settings(
-        config,
-        {"enabled": ["true"], "provider": ["openrouter"]},
-        oauth_status=_oauth_status,
-    )
-    transcription_changed = update_transcription_settings(
-        config,
-        {"provider": ["openrouter"], "model": ["openai/whisper-large-v3"]},
-    )
-    network_changed, access_mode = update_network_safety_settings(
-        config,
-        {
-            "webui_allow_local_service_access": ["false"],
-            "webui_default_access_mode": ["restricted"],
-        },
-    )
-    payload = capability_settings_payload(config, oauth_status=_oauth_status)
-
-    assert (web_changed, web_restart) == (True, True)
-    assert image_changed is True
-    assert transcription_changed is True
-    assert (network_changed, access_mode) == (True, "default")
-    assert payload["web_search"]["max_results"] == 7
-    assert payload["api"]["host"] == "127.0.0.2"
-    assert payload["api"]["port"] == 8900
-    assert payload["image_generation"]["enabled"] is True
-    assert payload["transcription"]["provider"] == "openrouter"

tests/webui/test_settings_models.py

@@ -1,58 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-from nanobot.config.schema import Config
-from nanobot.webui.settings_models import (
-    model_settings_payload,
-    update_agent_model_settings,
-    update_provider_settings,
-)
-
-
-def _oauth_status(_spec: Any) -> dict[str, Any]:
-    return {
-        "configured": False,
-        "account": None,
-        "expires_at": None,
-        "login_supported": True,
-    }
-
-
-def test_model_domain_owns_dto_and_config_updates() -> None:
-    config = Config()
-    config.providers.openrouter.api_key = "sk-before"
-
-    agent_changed = update_agent_model_settings(
-        config,
-        {
-            "model": ["openai/gpt-5.4"],
-            "provider": ["openrouter"],
-            "context_window_tokens": ["200000"],
-        },
-        oauth_status=_oauth_status,
-    )
-    provider_changed, restart_required = update_provider_settings(
-        config,
-        {
-            "provider": ["openrouter"],
-            "api_key": ["sk-after"],
-        },
-    )
-    payload = model_settings_payload(config, oauth_status=_oauth_status)
-
-    assert agent_changed is True
-    assert provider_changed is True
-    assert restart_required is False
-    assert config.agents.defaults.model == "openai/gpt-5.4"
-    assert config.agents.defaults.provider == "openrouter"
-    assert config.agents.defaults.context_window_tokens == 200_000
-    assert config.providers.openrouter.api_key == "sk-after"
-    assert set(payload) == {
-        "agent",
-        "model_presets",
-        "model_call_order",
-        "model_call_order_editable",
-        "providers",
-    }
-    assert payload["agent"]["model"] == "openai/gpt-5.4"

tests/webui/test_settings_routes.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import json
 from types import SimpleNamespace
-from unittest.mock import MagicMock
+from unittest.mock import ANY, AsyncMock, MagicMock
 from urllib.parse import parse_qs, urlsplit
 
 import pytest
@@ -28,6 +28,7 @@ def _router(*, authorized: bool = True) -> WebUISettingsRouter:
         ),
         runtime_surface="browser",
         runtime_capabilities={},
+        mcp_oauth_redirect_uri=lambda _request: "https://gateway.example/auth/mcp/callback",
     )
 
 
@@ -39,6 +40,121 @@ def _mutation_request(path: str, payload: dict[str, object]) -> SimpleNamespace:
     return request
 
 
+@pytest.mark.asyncio
+async def test_mcp_oauth_start_uses_gateway_callback_and_requires_api_auth(monkeypatch) -> None:
+    config = SimpleNamespace(
+        type="streamableHttp",
+        auth="oauth",
+        url="https://app.xmind.com/api/mcp",
+    )
+    monkeypatch.setattr(
+        "nanobot.webui.settings_routes.ensure_mcp_oauth_server",
+        lambda _query, *, config_path=None: ("xmind", config),
+    )
+    router = _router()
+    start = AsyncMock(return_value={
+        "status": "authorization_required",
+        "flow_id": "flow-123",
+        "name": "xmind",
+        "authorization_url": "https://xmind.example/authorize?state=state-123",
+    })
+    router._mcp_oauth = SimpleNamespace(start=start)
+    request = _mutation_request(
+        "/api/settings/mcp-oauth/start",
+        {"name": "xmind"},
+    )
+
+    response = await router.dispatch(None, request, "/api/settings/mcp-oauth/start")
+
+    assert response is not None
+    assert response.status_code == 200
+    assert json.loads(response.body)["flow_id"] == "flow-123"
+    start.assert_awaited_once_with(
+        "xmind",
+        config,
+        "https://gateway.example/auth/mcp/callback",
+        reload_mcp=ANY,
+        reset_credentials=False,
+    )
+
+    denied = _router(authorized=False)
+    denied_response = await denied.dispatch(None, request, "/api/settings/mcp-oauth/start")
+    assert denied_response is not None
+    assert denied_response.status_code == 401
+
+    failed = _router()
+    failed._mcp_oauth = SimpleNamespace(
+        start=AsyncMock(side_effect=RuntimeError("upstream secret response"))
+    )
+    failed_response = await failed.dispatch(None, request, "/api/settings/mcp-oauth/start")
+    assert failed_response is not None
+    assert failed_response.status_code == 500
+    assert json.loads(failed_response.body) == {"error": "MCP OAuth start failed"}
+    assert b"upstream secret response" not in failed_response.body
+
+
+@pytest.mark.asyncio
+async def test_mcp_oauth_callback_is_state_authenticated_and_returns_close_page() -> None:
+    router = _router(authorized=False)
+    submit = MagicMock(return_value="xmind")
+    router._mcp_oauth = SimpleNamespace(submit_callback=submit)
+    request = SimpleNamespace(
+        path="/auth/mcp/callback?code=oauth-code&state=state-123",
+        headers=Headers(),
+    )
+
+    response = await router.dispatch(None, request, "/auth/mcp/callback")
+
+    assert response is not None
+    assert response.status_code == 200
+    assert response.headers["Content-Type"] == "text/html; charset=utf-8"
+    assert response.headers["Cache-Control"] == "no-store"
+    assert "frame-ancestors 'none'" in response.headers["Content-Security-Policy"]
+    assert b"window.close" in response.body
+    assert b"Authorization received" in response.body
+    assert b"oauth-code" not in response.body
+    submit.assert_called_once_with(state="state-123", code="oauth-code", error=None)
+
+
+@pytest.mark.asyncio
+async def test_mcp_oauth_manual_completion_reads_websocket_payload() -> None:
+    callback_url = (
+        "http://127.0.0.1:8765/auth/mcp/callback?code=oauth-code&state=state-123"
+    )
+    router = _router()
+    submit = MagicMock(
+        return_value={
+            "flow_id": "flow-123",
+            "name": "linear",
+            "status": "connecting",
+            "expires_in": 299,
+            "completion_input": "callback_url",
+        }
+    )
+    router._mcp_oauth = SimpleNamespace(submit_callback_url=submit)
+    request = _mutation_request(
+        "/api/settings/mcp-oauth/complete",
+        {"flow_id": "flow-123", "callback_url": callback_url},
+    )
+
+    response = await router.dispatch(None, request, "/api/settings/mcp-oauth/complete")
+
+    assert response is not None
+    assert response.status_code == 200
+    assert json.loads(response.body)["status"] == "connecting"
+    assert b"oauth-code" not in response.body
+    submit.assert_called_once_with(flow_id="flow-123", callback_url=callback_url)
+
+    denied = _router(authorized=False)
+    denied_response = await denied.dispatch(
+        None,
+        request,
+        "/api/settings/mcp-oauth/complete",
+    )
+    assert denied_response is not None
+    assert denied_response.status_code == 401
+
+
 @pytest.mark.parametrize(
     ("provider", "authorization_response"),
     [

tests/webui/test_settings_system.py

@@ -1,44 +0,0 @@
-from __future__ import annotations
-
-from nanobot.config.schema import Config
-from nanobot.webui.settings_system import (
-    coerce_channel_value,
-    system_settings_payload,
-    update_agent_system_settings,
-)
-
-
-def test_system_domain_owns_runtime_dto_and_agent_updates(tmp_path) -> None:
-    config = Config()
-
-    changed, restart_required = update_agent_system_settings(
-        config,
-        {
-            "timezone": ["Asia/Shanghai"],
-            "tool_hint_max_length": ["120"],
-        },
-    )
-    payload = system_settings_payload(
-        config,
-        config_path=tmp_path / "config.json",
-        version="0.3.0",
-    )
-
-    assert changed is True
-    assert restart_required is True
-    assert config.agents.defaults.timezone == "Asia/Shanghai"
-    assert config.agents.defaults.timezone_mode == "manual"
-    assert config.agents.defaults.tool_hint_max_length == 120
-    assert payload["runtime"]["config_path"] == str(tmp_path / "config.json")
-    assert payload["version"] == {"current": "0.3.0"}
-    assert payload["docs"]["version"] == "0.3.0"
-    assert set(payload) == {"runtime", "usage", "advanced", "version", "docs"}
-
-
-def test_system_domain_validates_channel_field_values() -> None:
-    assert coerce_channel_value("allow_from", "alice, bob", "list") == [
-        "alice",
-        "bob",
-    ]
-    assert coerce_channel_value("enabled", "yes", "bool") is True
-    assert coerce_channel_value("port", "8765", "int") == 8765

tests/webui/test_ws_http_oauth.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import cast
+
+from websockets.datastructures import Headers
+from websockets.http11 import Request as WsRequest
+
+from nanobot.channels.websocket.runtime import WebSocketConfig
+from nanobot.webui.ws_http import GatewayHTTPHandler
+
+
+def _handler(config: WebSocketConfig) -> GatewayHTTPHandler:
+    handler = object.__new__(GatewayHTTPHandler)
+    handler.config = config
+    return handler
+
+
+def _request(**headers: str) -> WsRequest:
+    return cast(WsRequest, SimpleNamespace(headers=Headers(headers)))
+
+
+def test_mcp_oauth_callback_uses_configured_public_websocket_origin() -> None:
+    handler = _handler(WebSocketConfig(path="/ws", public_ws_url="wss://agent.example/ws"))
+
+    redirect_uri = handler._mcp_oauth_redirect_uri(_request(Host="ignored.example"))
+
+    assert redirect_uri == "https://agent.example/auth/mcp/callback"
+
+
+def test_mcp_oauth_callback_uses_safe_forwarded_request_origin() -> None:
+    handler = _handler(WebSocketConfig(path="/ws", host="127.0.0.1", port=8765))
+
+    redirect_uri = handler._mcp_oauth_redirect_uri(
+        _request(Host="nanobot.example:9443", **{"X-Forwarded-Proto": "https"})
+    )
+
+    assert redirect_uri == "https://nanobot.example:9443/auth/mcp/callback"

webui/src/i18n/locales/en/common.json

@@ -319,8 +319,8 @@
       "filterInstalled": "Enabled",
       "filterNotInstalled": "Not enabled",
       "searchPlaceholder": "Search MCP presets",
-      "moreOptions": "Add integration",
-      "moreOptionsSubtitle": "Connect a custom tool server or import an existing configuration.",
+      "moreOptions": "Add MCP server",
+      "moreOptionsSubtitle": "Connect a custom MCP server or import an existing configuration.",
       "customTitle": "Custom MCP",
       "customSubtitle": "Add any stdio, HTTP, or SSE MCP server.",
       "customAction": "Custom",
@@ -328,9 +328,14 @@
       "serverName": "Server name",
       "serverUrl": "URL",
       "transport": "Transport",
+      "authentication": "Authentication",
+      "authNone": "None",
+      "authHeaders": "Headers",
       "command": "Command",
       "args": "Args JSON",
       "headers": "Headers JSON",
+      "oauthAfterSave": "Save the server, then select Connect to sign in.",
+      "headersHelp": "Add the request headers used by this server.",
       "env": "Env JSON",
       "timeout": "Tool timeout",
       "advancedOptions": "Advanced options",
@@ -357,6 +362,21 @@
       "keepExisting": "Leave blank to keep existing",
       "statusConfigured": "Configured",
       "statusMissingCredentials": "Needs key",
+      "connectingAccount": "Connecting {{name}}",
+      "connectingLabel": "Connecting…",
+      "continueSignIn": "Continue sign-in",
+      "preparingSignIn": "Preparing secure sign-in…",
+      "openSignInToContinue": "Open the sign-in page to continue.",
+      "finishSignInInBrowser": "Finish signing in in the browser window.",
+      "manualCallbackRequired": "Finish signing in, then paste the callback URL into nanobot.",
+      "manualCallbackHelp": "After approving access, the localhost page will not load. Copy its full URL from the address bar and paste it here.",
+      "finishingConnection": "Finishing connection…",
+      "activatingTools": "Activating tools…",
+      "connected": "Connected.",
+      "connectionFailed": "Connection failed.",
+      "connectionCancelled": "Connection cancelled.",
+      "reloadFailed": "Signed in, but nanobot could not connect the tools. Try restarting nanobot.",
+      "oauthFailed": "Unable to connect. Try signing in again.",
       "statusMissingDependency": "Needs dependency",
       "statusComingSoon": "Coming soon",
       "comingSoon": "Coming soon",
@@ -584,27 +604,28 @@
     "apps": {
       "description": "Add tools to nanobot, then @ them in chat.",
       "cliLabel": "App",
-      "mcpLabel": "Integration",
+      "mcpLabel": "MCP",
       "channelLabel": "Channel",
       "featureLabel": "Feature",
       "filterAll": "Ready",
       "filterPlugins": "Plugins",
       "filterCli": "Apps",
-      "filterMcp": "Integrations",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} ready",
-      "caption": "{{cli}} apps · {{mcp}} integrations",
+      "caption": "{{cli}} apps · {{mcp}} MCP tools",
       "searchPlaceholder": "Search tools",
       "featured": "Tools",
+      "mcpTools": "MCP tools",
       "loading": "Loading Apps...",
       "empty": "No tools match your search.",
       "emptyApps": "No apps available.",
-      "emptyIntegrations": "No integrations available.",
+      "emptyIntegrations": "No MCP tools available.",
       "emptyReady": "No tools are ready yet.",
       "clearSearch": "Clear search",
       "browseApps": "Browse apps",
-      "browseIntegrations": "Browse integrations",
-      "emptyIntegrationsHint": "Add a custom integration below.",
-      "restartRequired": "Restart nanobot to apply updated apps and integrations."
+      "browseIntegrations": "Browse MCP tools",
+      "emptyIntegrationsHint": "Add a custom MCP server below.",
+      "restartRequired": "Restart nanobot to apply updated apps and MCP tools."
     },
     "channels": {
       "description": "Connect chat apps, email, and WebUI to nanobot.",

webui/src/i18n/locales/es/common.json

@@ -504,8 +504,8 @@
       "filterInstalled": "Habilitados",
       "filterNotInstalled": "No habilitados",
       "searchPlaceholder": "Buscar preajustes MCP",
-      "moreOptions": "Más opciones de MCP",
-      "moreOptionsSubtitle": "Añade un servidor personalizado o importa mcp.json.",
+      "moreOptions": "Añadir servidor MCP",
+      "moreOptionsSubtitle": "Conecta un servidor MCP personalizado o importa una configuración existente.",
       "customTitle": "MCP personalizado",
       "customSubtitle": "Añade cualquier servidor MCP stdio, HTTP o SSE.",
       "customAction": "Personalizado",
@@ -513,9 +513,14 @@
       "serverName": "Nombre del servidor",
       "serverUrl": "URL",
       "transport": "Transporte",
+      "authentication": "Autenticación",
+      "authNone": "Ninguna",
+      "authHeaders": "Encabezados",
       "command": "Comando",
       "args": "Argumentos JSON",
       "headers": "Encabezados JSON",
+      "oauthAfterSave": "Guarda el servidor y selecciona Conectar para iniciar sesión.",
+      "headersHelp": "Añade los encabezados de solicitud que utiliza este servidor.",
       "env": "Entorno JSON",
       "timeout": "Tiempo límite de herramienta",
       "advancedOptions": "Opciones avanzadas",
@@ -542,6 +547,21 @@
       "keepExisting": "Déjalo en blanco para conservar el valor actual",
       "statusConfigured": "Configurado",
       "statusMissingCredentials": "Necesita clave",
+      "connectingAccount": "Conectando {{name}}",
+      "connectingLabel": "Conectando…",
+      "continueSignIn": "Continuar inicio de sesión",
+      "preparingSignIn": "Preparando un inicio de sesión seguro…",
+      "openSignInToContinue": "Abre la página de inicio de sesión para continuar.",
+      "finishSignInInBrowser": "Termina de iniciar sesión en la ventana del navegador.",
+      "manualCallbackRequired": "Termina de iniciar sesión y pega la URL de devolución en nanobot.",
+      "manualCallbackHelp": "Después de aprobar el acceso, la página de localhost no se cargará. Copia la URL completa de la barra de direcciones y pégala aquí.",
+      "finishingConnection": "Finalizando la conexión…",
+      "activatingTools": "Activando herramientas…",
+      "connected": "Conectado.",
+      "connectionFailed": "Error de conexión.",
+      "connectionCancelled": "Conexión cancelada.",
+      "reloadFailed": "Has iniciado sesión, pero nanobot no pudo conectar las herramientas. Prueba a reiniciar nanobot.",
+      "oauthFailed": "No se pudo conectar. Intenta iniciar sesión de nuevo.",
       "statusMissingDependency": "Necesita dependencia",
       "statusComingSoon": "Próximamente",
       "comingSoon": "Próximamente",
@@ -571,27 +591,28 @@
     "apps": {
       "description": "Añade herramientas a nanobot y luego úsalas con @ en el chat.",
       "cliLabel": "Aplicación",
-      "mcpLabel": "Integración",
+      "mcpLabel": "MCP",
       "channelLabel": "Canal",
       "featureLabel": "Función",
       "filterAll": "Listo",
       "filterPlugins": "Complementos",
       "filterCli": "Aplicaciones",
-      "filterMcp": "Integraciones",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} listos",
-      "caption": "{{cli}} aplicaciones · {{mcp}} integraciones",
+      "caption": "{{cli}} aplicaciones · {{mcp}} herramientas MCP",
       "searchPlaceholder": "Buscar aplicaciones",
       "featured": "Herramientas",
+      "mcpTools": "Herramientas MCP",
       "loading": "Cargando aplicaciones...",
       "empty": "Ninguna herramienta coincide con tu búsqueda.",
       "emptyApps": "No hay aplicaciones disponibles.",
-      "emptyIntegrations": "No hay integraciones disponibles.",
+      "emptyIntegrations": "No hay herramientas MCP disponibles.",
       "emptyReady": "Todavía no hay herramientas listas.",
       "clearSearch": "Borrar búsqueda",
       "browseApps": "Explorar aplicaciones",
-      "browseIntegrations": "Explorar integraciones",
-      "emptyIntegrationsHint": "Añade una integración personalizada abajo.",
-      "restartRequired": "Reinicia nanobot para aplicar las aplicaciones y funciones actualizadas."
+      "browseIntegrations": "Explorar herramientas MCP",
+      "emptyIntegrationsHint": "Añade un servidor MCP personalizado abajo.",
+      "restartRequired": "Reinicia nanobot para aplicar las aplicaciones y herramientas MCP actualizadas."
     },
     "channels": {
       "description": "Conecta nanobot con aplicaciones de chat. Instalar el soporte solo añade el paquete de integración; la mayoría de canales aún necesitan tokens o configuración del espacio de trabajo.",

webui/src/i18n/locales/fr/common.json

@@ -504,8 +504,8 @@
       "filterInstalled": "Activés",
       "filterNotInstalled": "Non activés",
       "searchPlaceholder": "Rechercher des préréglages MCP",
-      "moreOptions": "Plus d'options MCP",
-      "moreOptionsSubtitle": "Ajoutez un serveur personnalisé ou importez mcp.json.",
+      "moreOptions": "Ajouter un serveur MCP",
+      "moreOptionsSubtitle": "Connectez un serveur MCP personnalisé ou importez une configuration existante.",
       "customTitle": "MCP personnalisé",
       "customSubtitle": "Ajoutez n'importe quel serveur MCP stdio, HTTP ou SSE.",
       "customAction": "Personnalisé",
@@ -513,9 +513,14 @@
       "serverName": "Nom du serveur",
       "serverUrl": "URL",
       "transport": "Transport",
+      "authentication": "Authentification",
+      "authNone": "Aucune",
+      "authHeaders": "En-têtes",
       "command": "Commande",
       "args": "Arguments JSON",
       "headers": "En-têtes JSON",
+      "oauthAfterSave": "Enregistrez le serveur, puis sélectionnez Se connecter pour vous identifier.",
+      "headersHelp": "Ajoutez les en-têtes de requête utilisés par ce serveur.",
       "env": "Environnement JSON",
       "timeout": "Délai d'outil",
       "advancedOptions": "Options avancées",
@@ -542,6 +547,21 @@
       "keepExisting": "Laissez vide pour conserver la valeur actuelle",
       "statusConfigured": "Configuré",
       "statusMissingCredentials": "Clé requise",
+      "connectingAccount": "Connexion à {{name}}",
+      "connectingLabel": "Connexion…",
+      "continueSignIn": "Continuer la connexion",
+      "preparingSignIn": "Préparation d’une connexion sécurisée…",
+      "openSignInToContinue": "Ouvrez la page de connexion pour continuer.",
+      "finishSignInInBrowser": "Terminez la connexion dans la fenêtre du navigateur.",
+      "manualCallbackRequired": "Terminez la connexion, puis collez l’URL de rappel dans nanobot.",
+      "manualCallbackHelp": "Après avoir autorisé l’accès, la page localhost ne se chargera pas. Copiez son URL complète depuis la barre d’adresse et collez-la ici.",
+      "finishingConnection": "Finalisation de la connexion…",
+      "activatingTools": "Activation des outils…",
+      "connected": "Connecté.",
+      "connectionFailed": "Échec de la connexion.",
+      "connectionCancelled": "Connexion annulée.",
+      "reloadFailed": "Connexion réussie, mais nanobot n’a pas pu activer les outils. Essayez de redémarrer nanobot.",
+      "oauthFailed": "Connexion impossible. Essayez de vous reconnecter.",
       "statusMissingDependency": "Dépendance requise",
       "statusComingSoon": "Bientôt disponible",
       "comingSoon": "Bientôt disponible",
@@ -570,27 +590,28 @@
     "apps": {
       "description": "Ajoutez des outils à nanobot, puis utilisez-les avec @ dans le chat.",
       "cliLabel": "Application",
-      "mcpLabel": "Intégration",
+      "mcpLabel": "MCP",
       "channelLabel": "Canal",
       "featureLabel": "Fonction",
       "filterAll": "Prêts",
       "filterPlugins": "Extensions",
       "filterCli": "Applications",
-      "filterMcp": "Intégrations",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} prêts",
-      "caption": "{{cli}} applications · {{mcp}} intégrations",
+      "caption": "{{cli}} applications · {{mcp}} outils MCP",
       "searchPlaceholder": "Rechercher des applications",
       "featured": "Outils",
+      "mcpTools": "Outils MCP",
       "loading": "Chargement des applications...",
       "empty": "Aucun outil ne correspond à votre recherche.",
       "emptyApps": "Aucune application disponible.",
-      "emptyIntegrations": "Aucune intégration disponible.",
+      "emptyIntegrations": "Aucun outil MCP disponible.",
       "emptyReady": "Aucun outil n’est encore prêt.",
       "clearSearch": "Effacer la recherche",
       "browseApps": "Parcourir les applications",
-      "browseIntegrations": "Parcourir les intégrations",
-      "emptyIntegrationsHint": "Ajoutez une intégration personnalisée ci-dessous.",
-      "restartRequired": "Redémarrez nanobot pour appliquer les applications et fonctions mises à jour."
+      "browseIntegrations": "Parcourir les outils MCP",
+      "emptyIntegrationsHint": "Ajoutez un serveur MCP personnalisé ci-dessous.",
+      "restartRequired": "Redémarrez nanobot pour appliquer les applications et outils MCP mis à jour."
     },
     "channels": {
       "description": "Connectez nanobot aux applications de discussion. L'installation du support ajoute seulement le paquet d'intégration ; la plupart des canaux nécessitent encore des jetons ou des réglages d'espace de travail.",

webui/src/i18n/locales/id/common.json

@@ -504,8 +504,8 @@
       "filterInstalled": "Aktif",
       "filterNotInstalled": "Tidak aktif",
       "searchPlaceholder": "Cari prasetel MCP",
-      "moreOptions": "Opsi MCP lainnya",
-      "moreOptionsSubtitle": "Tambahkan server khusus atau impor mcp.json.",
+      "moreOptions": "Tambahkan server MCP",
+      "moreOptionsSubtitle": "Hubungkan server MCP khusus atau impor konfigurasi yang ada.",
       "customTitle": "MCP khusus",
       "customSubtitle": "Tambahkan server MCP stdio, HTTP, atau SSE apa pun.",
       "customAction": "Khusus",
@@ -513,9 +513,14 @@
       "serverName": "Nama server",
       "serverUrl": "URL",
       "transport": "Transport",
+      "authentication": "Autentikasi",
+      "authNone": "Tidak ada",
+      "authHeaders": "Header",
       "command": "Perintah",
       "args": "Argumen JSON",
       "headers": "Header JSON",
+      "oauthAfterSave": "Simpan server, lalu pilih Hubungkan untuk masuk.",
+      "headersHelp": "Tambahkan header permintaan yang digunakan server ini.",
       "env": "Lingkungan JSON",
       "timeout": "Batas waktu alat",
       "advancedOptions": "Opsi lanjutan",
@@ -542,6 +547,21 @@
       "keepExisting": "Biarkan kosong untuk mempertahankan nilai saat ini",
       "statusConfigured": "Terkonfigurasi",
       "statusMissingCredentials": "Butuh kunci",
+      "connectingAccount": "Menghubungkan {{name}}",
+      "connectingLabel": "Menghubungkan…",
+      "continueSignIn": "Lanjutkan masuk",
+      "preparingSignIn": "Menyiapkan proses masuk yang aman…",
+      "openSignInToContinue": "Buka halaman masuk untuk melanjutkan.",
+      "finishSignInInBrowser": "Selesaikan proses masuk di jendela browser.",
+      "manualCallbackRequired": "Selesaikan proses masuk, lalu tempel URL callback ke nanobot.",
+      "manualCallbackHelp": "Setelah menyetujui akses, halaman localhost tidak akan terbuka. Salin URL lengkap dari bilah alamat lalu tempel di sini.",
+      "finishingConnection": "Menyelesaikan koneksi…",
+      "activatingTools": "Mengaktifkan alat…",
+      "connected": "Terhubung.",
+      "connectionFailed": "Koneksi gagal.",
+      "connectionCancelled": "Koneksi dibatalkan.",
+      "reloadFailed": "Anda sudah masuk, tetapi nanobot tidak dapat menghubungkan alat. Coba mulai ulang nanobot.",
+      "oauthFailed": "Tidak dapat terhubung. Coba masuk lagi.",
       "statusMissingDependency": "Butuh dependensi",
       "statusComingSoon": "Segera hadir",
       "comingSoon": "Segera hadir",
@@ -570,27 +590,28 @@
     "apps": {
       "description": "Tambahkan alat ke nanobot, lalu gunakan dengan @ di chat.",
       "cliLabel": "Aplikasi",
-      "mcpLabel": "Integrasi",
+      "mcpLabel": "MCP",
       "channelLabel": "Kanal",
       "featureLabel": "Fitur",
       "filterAll": "Siap",
       "filterPlugins": "Plugin",
       "filterCli": "Aplikasi",
-      "filterMcp": "Integrasi",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} siap",
-      "caption": "{{cli}} aplikasi · {{mcp}} integrasi",
+      "caption": "{{cli}} aplikasi · {{mcp}} alat MCP",
       "searchPlaceholder": "Cari aplikasi",
       "featured": "Alat",
+      "mcpTools": "Alat MCP",
       "loading": "Memuat aplikasi...",
       "empty": "Tidak ada alat yang cocok dengan pencarian Anda.",
       "emptyApps": "Tidak ada aplikasi yang tersedia.",
-      "emptyIntegrations": "Tidak ada integrasi yang tersedia.",
+      "emptyIntegrations": "Tidak ada alat MCP yang tersedia.",
       "emptyReady": "Belum ada alat yang siap.",
       "clearSearch": "Hapus pencarian",
       "browseApps": "Jelajahi aplikasi",
-      "browseIntegrations": "Jelajahi integrasi",
-      "emptyIntegrationsHint": "Tambahkan integrasi khusus di bawah.",
-      "restartRequired": "Mulai ulang nanobot untuk menerapkan aplikasi dan fitur yang diperbarui."
+      "browseIntegrations": "Jelajahi alat MCP",
+      "emptyIntegrationsHint": "Tambahkan server MCP khusus di bawah.",
+      "restartRequired": "Mulai ulang nanobot untuk menerapkan aplikasi dan alat MCP yang diperbarui."
     },
     "channels": {
       "description": "Hubungkan nanobot ke aplikasi chat. Memasang dukungan hanya menambahkan paket integrasi; sebagian besar kanal tetap memerlukan token atau pengaturan ruang kerja.",

webui/src/i18n/locales/ja/common.json

@@ -504,8 +504,8 @@
       "filterInstalled": "有効",
       "filterNotInstalled": "未有効",
       "searchPlaceholder": "MCP プリセットを検索",
-      "moreOptions": "その他の MCP オプション",
-      "moreOptionsSubtitle": "カスタムサーバーを追加するか mcp.json をインポートします。",
+      "moreOptions": "MCP サーバーを追加",
+      "moreOptionsSubtitle": "カスタム MCP サーバーを接続するか、既存の設定をインポートします。",
       "customTitle": "カスタム MCP",
       "customSubtitle": "任意の stdio、HTTP、SSE MCP サーバーを追加します。",
       "customAction": "カスタム",
@@ -513,9 +513,14 @@
       "serverName": "サーバー名",
       "serverUrl": "URL",
       "transport": "トランスポート",
+      "authentication": "認証",
+      "authNone": "なし",
+      "authHeaders": "ヘッダー",
       "command": "コマンド",
       "args": "引数 JSON",
       "headers": "ヘッダー JSON",
+      "oauthAfterSave": "サーバーを保存してから、［接続］を選択してサインインします。",
+      "headersHelp": "このサーバーで使用するリクエストヘッダーを追加します。",
       "env": "環境変数 JSON",
       "timeout": "ツールのタイムアウト",
       "advancedOptions": "詳細オプション",
@@ -542,6 +547,21 @@
       "keepExisting": "既存の値を維持するには空欄のままにします",
       "statusConfigured": "設定済み",
       "statusMissingCredentials": "キーが必要",
+      "connectingAccount": "{{name}} に接続しています",
+      "connectingLabel": "接続中…",
+      "continueSignIn": "サインインを続ける",
+      "preparingSignIn": "安全なサインインを準備しています…",
+      "openSignInToContinue": "サインインページを開いて続行してください。",
+      "finishSignInInBrowser": "ブラウザウィンドウでサインインを完了してください。",
+      "manualCallbackRequired": "サインインを完了し、コールバック URL を nanobot に貼り付けてください。",
+      "manualCallbackHelp": "アクセスを承認すると localhost ページは開きません。アドレスバーから完全な URL をコピーして、ここに貼り付けてください。",
+      "finishingConnection": "接続を完了しています…",
+      "activatingTools": "ツールを有効にしています…",
+      "connected": "接続しました。",
+      "connectionFailed": "接続に失敗しました。",
+      "connectionCancelled": "接続をキャンセルしました。",
+      "reloadFailed": "サインインしましたが、nanobot はツールに接続できませんでした。nanobot を再起動してください。",
+      "oauthFailed": "接続できません。もう一度サインインしてください。",
       "statusMissingDependency": "依存関係が必要",
       "statusComingSoon": "近日公開",
       "comingSoon": "近日公開",
@@ -570,27 +590,28 @@
     "apps": {
       "description": "nanobot にツールを追加し、チャットで @ を付けて使用できます。",
       "cliLabel": "アプリ",
-      "mcpLabel": "連携",
+      "mcpLabel": "MCP",
       "channelLabel": "チャンネル",
       "featureLabel": "機能",
       "filterAll": "使用可能",
       "filterPlugins": "プラグイン",
       "filterCli": "アプリ",
-      "filterMcp": "連携",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} 件使用可能",
-      "caption": "アプリ {{cli}} 件 · 連携 {{mcp}} 件",
+      "caption": "アプリ {{cli}} 件 · MCP ツール {{mcp}} 件",
       "searchPlaceholder": "アプリを検索",
       "featured": "ツール",
+      "mcpTools": "MCP ツール",
       "loading": "アプリを読み込み中...",
       "empty": "検索条件に一致するツールはありません。",
       "emptyApps": "利用できるアプリはありません。",
-      "emptyIntegrations": "利用できる連携はありません。",
+      "emptyIntegrations": "利用できる MCP ツールはありません。",
       "emptyReady": "使用可能なツールはまだありません。",
       "clearSearch": "検索をクリア",
       "browseApps": "アプリを見る",
-      "browseIntegrations": "連携を見る",
-      "emptyIntegrationsHint": "下からカスタム連携を追加できます。",
-      "restartRequired": "更新したアプリと機能を反映するには nanobot を再起動してください。"
+      "browseIntegrations": "MCP ツールを見る",
+      "emptyIntegrationsHint": "下からカスタム MCP サーバーを追加できます。",
+      "restartRequired": "更新したアプリと MCP ツールを反映するには nanobot を再起動してください。"
     },
     "channels": {
       "description": "nanobot をチャットアプリに接続します。サポートのインストールは統合パッケージを追加するだけで、多くのチャンネルでは引き続きトークンやワークスペース設定が必要です。",

webui/src/i18n/locales/ko/common.json

@@ -504,8 +504,8 @@
       "filterInstalled": "활성화됨",
       "filterNotInstalled": "비활성",
       "searchPlaceholder": "MCP 프리셋 검색",
-      "moreOptions": "추가 MCP 옵션",
-      "moreOptionsSubtitle": "사용자 지정 서버를 추가하거나 mcp.json을 가져옵니다.",
+      "moreOptions": "MCP 서버 추가",
+      "moreOptionsSubtitle": "사용자 지정 MCP 서버를 연결하거나 기존 구성을 가져옵니다.",
       "customTitle": "사용자 지정 MCP",
       "customSubtitle": "stdio, HTTP 또는 SSE MCP 서버를 추가합니다.",
       "customAction": "사용자 지정",
@@ -513,9 +513,14 @@
       "serverName": "서버 이름",
       "serverUrl": "URL",
       "transport": "전송 방식",
+      "authentication": "인증",
+      "authNone": "없음",
+      "authHeaders": "헤더",
       "command": "명령",
       "args": "인자 JSON",
       "headers": "헤더 JSON",
+      "oauthAfterSave": "서버를 저장한 다음 연결을 선택하여 로그인하세요.",
+      "headersHelp": "이 서버에서 사용하는 요청 헤더를 추가하세요.",
       "env": "환경 변수 JSON",
       "timeout": "도구 제한 시간",
       "advancedOptions": "고급 옵션",
@@ -542,6 +547,21 @@
       "keepExisting": "기존 값을 유지하려면 비워 두세요",
       "statusConfigured": "구성됨",
       "statusMissingCredentials": "키 필요",
+      "connectingAccount": "{{name}} 연결 중",
+      "connectingLabel": "연결 중…",
+      "continueSignIn": "로그인 계속",
+      "preparingSignIn": "안전한 로그인을 준비하는 중…",
+      "openSignInToContinue": "계속하려면 로그인 페이지를 여세요.",
+      "finishSignInInBrowser": "브라우저 창에서 로그인을 완료하세요.",
+      "manualCallbackRequired": "로그인을 완료한 다음 콜백 URL을 nanobot에 붙여 넣으세요.",
+      "manualCallbackHelp": "접근을 승인하면 localhost 페이지가 열리지 않습니다. 주소 표시줄에서 전체 URL을 복사해 여기에 붙여 넣으세요.",
+      "finishingConnection": "연결을 마무리하는 중…",
+      "activatingTools": "도구를 활성화하는 중…",
+      "connected": "연결됨.",
+      "connectionFailed": "연결에 실패했습니다.",
+      "connectionCancelled": "연결을 취소했습니다.",
+      "reloadFailed": "로그인했지만 nanobot에서 도구를 연결하지 못했습니다. nanobot을 다시 시작해 보세요.",
+      "oauthFailed": "연결할 수 없습니다. 다시 로그인해 보세요.",
       "statusMissingDependency": "의존성 필요",
       "statusComingSoon": "곧 제공",
       "comingSoon": "곧 제공",
@@ -570,27 +590,28 @@
     "apps": {
       "description": "nanobot에 도구를 추가한 뒤 채팅에서 @로 사용하세요.",
       "cliLabel": "앱",
-      "mcpLabel": "연동",
+      "mcpLabel": "MCP",
       "channelLabel": "채널",
       "featureLabel": "기능",
       "filterAll": "사용 가능",
       "filterPlugins": "플러그인",
       "filterCli": "앱",
-      "filterMcp": "연동",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}}개 사용 가능",
-      "caption": "앱 {{cli}}개 · 연동 {{mcp}}개",
+      "caption": "앱 {{cli}}개 · MCP 도구 {{mcp}}개",
       "searchPlaceholder": "앱 검색",
       "featured": "도구",
+      "mcpTools": "MCP 도구",
       "loading": "앱을 불러오는 중...",
       "empty": "검색과 일치하는 도구가 없습니다.",
       "emptyApps": "사용 가능한 앱이 없습니다.",
-      "emptyIntegrations": "사용 가능한 연동이 없습니다.",
+      "emptyIntegrations": "사용 가능한 MCP 도구가 없습니다.",
       "emptyReady": "아직 준비된 도구가 없습니다.",
       "clearSearch": "검색 지우기",
       "browseApps": "앱 둘러보기",
-      "browseIntegrations": "연동 둘러보기",
-      "emptyIntegrationsHint": "아래에서 사용자 지정 연동을 추가하세요.",
-      "restartRequired": "업데이트된 앱과 기능을 적용하려면 nanobot을 다시 시작하세요."
+      "browseIntegrations": "MCP 도구 둘러보기",
+      "emptyIntegrationsHint": "아래에서 사용자 지정 MCP 서버를 추가하세요.",
+      "restartRequired": "업데이트된 앱과 MCP 도구를 적용하려면 nanobot을 다시 시작하세요."
     },
     "channels": {
       "description": "nanobot을 채팅 앱에 연결합니다. 지원 설치는 통합 패키지만 추가하며, 대부분의 채널은 여전히 토큰이나 워크스페이스 설정이 필요합니다.",

webui/src/i18n/locales/pt-BR/common.json

@@ -319,8 +319,8 @@
       "filterInstalled": "Habilitadas",
       "filterNotInstalled": "Não habilitadas",
       "searchPlaceholder": "Buscar predefinições MCP",
-      "moreOptions": "Adicionar integração",
-      "moreOptionsSubtitle": "Conecte um servidor de ferramentas personalizado ou importe uma configuração existente.",
+      "moreOptions": "Adicionar servidor MCP",
+      "moreOptionsSubtitle": "Conecte um servidor MCP personalizado ou importe uma configuração existente.",
       "customTitle": "MCP personalizado",
       "customSubtitle": "Adicione qualquer servidor MCP stdio, HTTP ou SSE.",
       "customAction": "Personalizado",
@@ -328,9 +328,14 @@
       "serverName": "Nome do servidor",
       "serverUrl": "URL",
       "transport": "Transporte",
+      "authentication": "Autenticação",
+      "authNone": "Nenhuma",
+      "authHeaders": "Cabeçalhos",
       "command": "Comando",
       "args": "Argumentos JSON",
       "headers": "Cabeçalhos JSON",
+      "oauthAfterSave": "Salve o servidor e selecione Conectar para entrar.",
+      "headersHelp": "Adicione os cabeçalhos de solicitação usados por este servidor.",
       "env": "Ambiente JSON",
       "timeout": "Tempo limite da ferramenta",
       "advancedOptions": "Opções avançadas",
@@ -357,6 +362,21 @@
       "keepExisting": "Deixe em branco para manter o valor atual",
       "statusConfigured": "Configurado",
       "statusMissingCredentials": "Precisa de chave",
+      "connectingAccount": "Conectando {{name}}",
+      "connectingLabel": "Conectando…",
+      "continueSignIn": "Continuar login",
+      "preparingSignIn": "Preparando login seguro…",
+      "openSignInToContinue": "Abra a página de login para continuar.",
+      "finishSignInInBrowser": "Conclua o login na janela do navegador.",
+      "manualCallbackRequired": "Conclua o login e cole a URL de callback no nanobot.",
+      "manualCallbackHelp": "Depois de autorizar o acesso, a página localhost não será carregada. Copie a URL completa da barra de endereços e cole-a aqui.",
+      "finishingConnection": "Finalizando conexão…",
+      "activatingTools": "Ativando ferramentas…",
+      "connected": "Conectado.",
+      "connectionFailed": "Falha na conexão.",
+      "connectionCancelled": "Conexão cancelada.",
+      "reloadFailed": "Login concluído, mas o nanobot não conseguiu conectar as ferramentas. Tente reiniciar o nanobot.",
+      "oauthFailed": "Não foi possível conectar. Tente fazer login novamente.",
       "statusMissingDependency": "Precisa de dependência",
       "statusComingSoon": "Em breve",
       "comingSoon": "Em breve",
@@ -584,27 +604,28 @@
     "apps": {
       "description": "Adicione ferramentas ao nanobot e mencione-as com @ na conversa.",
       "cliLabel": "Aplicativo",
-      "mcpLabel": "Integração",
+      "mcpLabel": "MCP",
       "channelLabel": "Canal",
       "featureLabel": "Recurso",
       "filterAll": "Prontos",
       "filterPlugins": "Complementos",
       "filterCli": "Aplicativos",
-      "filterMcp": "Integrações",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} prontos",
-      "caption": "{{cli}} aplicativos · {{mcp}} integrações",
+      "caption": "{{cli}} aplicativos · {{mcp}} ferramentas MCP",
       "searchPlaceholder": "Buscar ferramentas",
       "featured": "Ferramentas",
+      "mcpTools": "Ferramentas MCP",
       "loading": "Carregando aplicativos...",
       "empty": "Nenhuma ferramenta corresponde à sua busca.",
       "emptyApps": "Nenhum aplicativo disponível.",
-      "emptyIntegrations": "Nenhuma integração disponível.",
+      "emptyIntegrations": "Nenhuma ferramenta MCP disponível.",
       "emptyReady": "Ainda não há ferramentas prontas.",
       "clearSearch": "Limpar busca",
       "browseApps": "Explorar aplicativos",
-      "browseIntegrations": "Explorar integrações",
-      "emptyIntegrationsHint": "Adicione uma integração personalizada abaixo.",
-      "restartRequired": "Reinicie o nanobot para aplicar os aplicativos e integrações atualizados."
+      "browseIntegrations": "Explorar ferramentas MCP",
+      "emptyIntegrationsHint": "Adicione um servidor MCP personalizado abaixo.",
+      "restartRequired": "Reinicie o nanobot para aplicar os aplicativos e ferramentas MCP atualizados."
     },
     "channels": {
       "description": "Conecte aplicativos de chat, e-mail e WebUI ao nanobot.",

webui/src/i18n/locales/vi/common.json

@@ -504,8 +504,8 @@
       "filterInstalled": "Đã bật",
       "filterNotInstalled": "Chưa bật",
       "searchPlaceholder": "Tìm cấu hình đặt trước MCP",
-      "moreOptions": "Tùy chọn MCP khác",
-      "moreOptionsSubtitle": "Thêm máy chủ tùy chỉnh hoặc nhập mcp.json.",
+      "moreOptions": "Thêm máy chủ MCP",
+      "moreOptionsSubtitle": "Kết nối máy chủ MCP tùy chỉnh hoặc nhập cấu hình hiện có.",
       "customTitle": "MCP tùy chỉnh",
       "customSubtitle": "Thêm bất kỳ máy chủ MCP stdio, HTTP hoặc SSE nào.",
       "customAction": "Tùy chỉnh",
@@ -513,9 +513,14 @@
       "serverName": "Tên máy chủ",
       "serverUrl": "URL",
       "transport": "Giao thức truyền",
+      "authentication": "Xác thực",
+      "authNone": "Không có",
+      "authHeaders": "Header",
       "command": "Lệnh",
       "args": "Đối số JSON",
       "headers": "Header JSON",
+      "oauthAfterSave": "Lưu máy chủ, sau đó chọn Kết nối để đăng nhập.",
+      "headersHelp": "Thêm các header yêu cầu mà máy chủ này sử dụng.",
       "env": "Môi trường JSON",
       "timeout": "Thời gian chờ công cụ",
       "advancedOptions": "Tùy chọn nâng cao",
@@ -542,6 +547,21 @@
       "keepExisting": "Để trống để giữ giá trị hiện tại",
       "statusConfigured": "Đã cấu hình",
       "statusMissingCredentials": "Cần khóa",
+      "connectingAccount": "Đang kết nối {{name}}",
+      "connectingLabel": "Đang kết nối…",
+      "continueSignIn": "Tiếp tục đăng nhập",
+      "preparingSignIn": "Đang chuẩn bị đăng nhập an toàn…",
+      "openSignInToContinue": "Mở trang đăng nhập để tiếp tục.",
+      "finishSignInInBrowser": "Hoàn tất đăng nhập trong cửa sổ trình duyệt.",
+      "manualCallbackRequired": "Hoàn tất đăng nhập, rồi dán URL callback vào nanobot.",
+      "manualCallbackHelp": "Sau khi phê duyệt quyền truy cập, trang localhost sẽ không tải được. Hãy sao chép URL đầy đủ từ thanh địa chỉ và dán vào đây.",
+      "finishingConnection": "Đang hoàn tất kết nối…",
+      "activatingTools": "Đang kích hoạt công cụ…",
+      "connected": "Đã kết nối.",
+      "connectionFailed": "Kết nối thất bại.",
+      "connectionCancelled": "Đã hủy kết nối.",
+      "reloadFailed": "Đã đăng nhập nhưng nanobot không thể kết nối các công cụ. Hãy thử khởi động lại nanobot.",
+      "oauthFailed": "Không thể kết nối. Hãy thử đăng nhập lại.",
       "statusMissingDependency": "Cần phụ thuộc",
       "statusComingSoon": "Sắp ra mắt",
       "comingSoon": "Sắp ra mắt",
@@ -570,27 +590,28 @@
     "apps": {
       "description": "Thêm công cụ vào nanobot, sau đó dùng @ trong cuộc trò chuyện.",
       "cliLabel": "Ứng dụng",
-      "mcpLabel": "Tích hợp",
+      "mcpLabel": "MCP",
       "channelLabel": "Kênh",
       "featureLabel": "Tính năng",
       "filterAll": "Sẵn sàng",
       "filterPlugins": "Plugin",
       "filterCli": "Ứng dụng",
-      "filterMcp": "Tích hợp",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} sẵn sàng",
-      "caption": "{{cli}} ứng dụng · {{mcp}} tích hợp",
+      "caption": "{{cli}} ứng dụng · {{mcp}} công cụ MCP",
       "searchPlaceholder": "Tìm ứng dụng",
       "featured": "Công cụ",
+      "mcpTools": "Công cụ MCP",
       "loading": "Đang tải ứng dụng...",
       "empty": "Không có công cụ phù hợp với tìm kiếm của bạn.",
       "emptyApps": "Không có ứng dụng nào.",
-      "emptyIntegrations": "Không có tích hợp nào.",
+      "emptyIntegrations": "Không có công cụ MCP nào.",
       "emptyReady": "Chưa có công cụ nào sẵn sàng.",
       "clearSearch": "Xóa tìm kiếm",
       "browseApps": "Xem ứng dụng",
-      "browseIntegrations": "Xem tích hợp",
-      "emptyIntegrationsHint": "Thêm tích hợp tùy chỉnh ở bên dưới.",
-      "restartRequired": "Khởi động lại nanobot để áp dụng ứng dụng và tính năng đã cập nhật."
+      "browseIntegrations": "Xem công cụ MCP",
+      "emptyIntegrationsHint": "Thêm máy chủ MCP tùy chỉnh ở bên dưới.",
+      "restartRequired": "Khởi động lại nanobot để áp dụng ứng dụng và công cụ MCP đã cập nhật."
     },
     "channels": {
       "description": "Kết nối nanobot với các ứng dụng chat. Cài đặt hỗ trợ chỉ thêm gói tích hợp; hầu hết kênh vẫn cần token hoặc cấu hình không gian làm việc.",

webui/src/i18n/locales/zh-CN/common.json

@@ -319,8 +319,8 @@
       "filterInstalled": "已启用",
       "filterNotInstalled": "未启用",
       "searchPlaceholder": "搜索 MCP 预设",
-      "moreOptions": "添加集成",
-      "moreOptionsSubtitle": "连接自定义工具服务，或导入已有配置。",
+      "moreOptions": "添加 MCP 服务",
+      "moreOptionsSubtitle": "连接自定义 MCP 服务，或导入已有配置。",
       "customTitle": "自定义 MCP",
       "customSubtitle": "添加任意 stdio、HTTP 或 SSE MCP 服务。",
       "customAction": "自定义",
@@ -328,9 +328,14 @@
       "serverName": "服务名",
       "serverUrl": "URL",
       "transport": "传输方式",
+      "authentication": "身份验证",
+      "authNone": "无",
+      "authHeaders": "请求头",
       "command": "命令",
       "args": "Args JSON",
-      "headers": "Headers JSON",
+      "headers": "请求头 JSON",
+      "oauthAfterSave": "保存服务器后，选择“连接”以完成登录。",
+      "headersHelp": "添加此服务器要求的请求头。",
       "env": "Env JSON",
       "timeout": "工具超时",
       "advancedOptions": "高级选项",
@@ -357,6 +362,21 @@
       "keepExisting": "留空则保留当前值",
       "statusConfigured": "已配置",
       "statusMissingCredentials": "需要密钥",
+      "connectingAccount": "正在连接 {{name}}",
+      "connectingLabel": "正在连接…",
+      "continueSignIn": "继续登录",
+      "preparingSignIn": "正在准备安全登录…",
+      "openSignInToContinue": "打开登录页面以继续。",
+      "finishSignInInBrowser": "请在浏览器窗口中完成登录。",
+      "manualCallbackRequired": "完成登录后，将回调 URL 粘贴到 nanobot。",
+      "manualCallbackHelp": "授权后，localhost 页面将无法打开。请复制地址栏中的完整 URL 并粘贴到这里。",
+      "finishingConnection": "正在完成连接…",
+      "activatingTools": "正在启用工具…",
+      "connected": "已连接。",
+      "connectionFailed": "连接失败。",
+      "connectionCancelled": "已取消连接。",
+      "reloadFailed": "已登录，但 nanobot 无法连接这些工具。请尝试重启 nanobot。",
+      "oauthFailed": "无法连接，请重新登录。",
       "statusMissingDependency": "缺少依赖",
       "statusComingSoon": "暂不支持",
       "comingSoon": "即将推出",
@@ -584,27 +604,28 @@
     "apps": {
       "description": "将工具接入 nanobot，然后在对话中通过 @ 调用。",
       "cliLabel": "应用",
-      "mcpLabel": "集成",
+      "mcpLabel": "MCP",
       "channelLabel": "渠道",
       "featureLabel": "能力",
       "filterAll": "可用",
       "filterPlugins": "插件",
       "filterCli": "应用",
-      "filterMcp": "集成",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} 个可用",
-      "caption": "{{cli}} 个应用 · {{mcp}} 个集成",
+      "caption": "{{cli}} 个应用 · {{mcp}} 个 MCP 工具",
       "searchPlaceholder": "搜索工具",
       "featured": "工具",
+      "mcpTools": "MCP 工具",
       "loading": "正在加载应用...",
       "empty": "没有与搜索条件匹配的工具。",
       "emptyApps": "暂无可用应用。",
-      "emptyIntegrations": "暂无可用集成。",
+      "emptyIntegrations": "暂无可用 MCP 工具。",
       "emptyReady": "还没有就绪的工具。",
       "clearSearch": "清除搜索",
       "browseApps": "浏览应用",
-      "browseIntegrations": "浏览集成",
-      "emptyIntegrationsHint": "可在下方添加自定义集成。",
-      "restartRequired": "重启 nanobot 以应用更新后的应用和集成。"
+      "browseIntegrations": "浏览 MCP 工具",
+      "emptyIntegrationsHint": "可在下方添加自定义 MCP 服务器。",
+      "restartRequired": "重启 nanobot 以应用更新后的应用和 MCP 工具。"
     },
     "channels": {
       "description": "把聊天应用、邮箱和 WebUI 连接到 nanobot。",

webui/src/i18n/locales/zh-TW/common.json

@@ -504,8 +504,8 @@
       "filterInstalled": "已啟用",
       "filterNotInstalled": "未啟用",
       "searchPlaceholder": "搜尋 MCP 預設",
-      "moreOptions": "新增整合",
-      "moreOptionsSubtitle": "連線自訂工具伺服器，或匯入現有設定。",
+      "moreOptions": "新增 MCP 服務",
+      "moreOptionsSubtitle": "連線自訂 MCP 服務，或匯入現有設定。",
       "customTitle": "自訂 MCP",
       "customSubtitle": "新增任何 stdio、HTTP 或 SSE MCP 伺服器。",
       "customAction": "自訂",
@@ -513,9 +513,14 @@
       "serverName": "伺服器名稱",
       "serverUrl": "URL",
       "transport": "傳輸方式",
+      "authentication": "驗證方式",
+      "authNone": "無",
+      "authHeaders": "請求標頭",
       "command": "指令",
       "args": "Args JSON",
-      "headers": "Headers JSON",
+      "headers": "請求標頭 JSON",
+      "oauthAfterSave": "儲存伺服器後，選擇「連線」以登入。",
+      "headersHelp": "新增此伺服器使用的請求標頭。",
       "env": "Env JSON",
       "timeout": "工具逾時",
       "advancedOptions": "進階選項",
@@ -542,6 +547,21 @@
       "keepExisting": "留空以保留目前值",
       "statusConfigured": "已設定",
       "statusMissingCredentials": "需要金鑰",
+      "connectingAccount": "正在連接 {{name}}",
+      "connectingLabel": "正在連線…",
+      "continueSignIn": "繼續登入",
+      "preparingSignIn": "正在準備安全登入…",
+      "openSignInToContinue": "開啟登入頁面以繼續。",
+      "finishSignInInBrowser": "請在瀏覽器視窗中完成登入。",
+      "manualCallbackRequired": "完成登入後，將回呼 URL 貼到 nanobot。",
+      "manualCallbackHelp": "授權後，localhost 頁面將無法開啟。請複製網址列中的完整 URL 並貼到這裡。",
+      "finishingConnection": "正在完成連線…",
+      "activatingTools": "正在啟用工具…",
+      "connected": "已連線。",
+      "connectionFailed": "連線失敗。",
+      "connectionCancelled": "已取消連線。",
+      "reloadFailed": "已登入，但 nanobot 無法連接這些工具。請嘗試重新啟動 nanobot。",
+      "oauthFailed": "無法連線，請重新登入。",
       "statusMissingDependency": "需要相依項",
       "statusComingSoon": "即將推出",
       "comingSoon": "即將推出",
@@ -570,27 +590,28 @@
     "apps": {
       "description": "將工具新增至 nanobot，再於聊天中使用 @ 指定工具。",
       "cliLabel": "應用程式",
-      "mcpLabel": "整合",
+      "mcpLabel": "MCP",
       "channelLabel": "通訊管道",
       "featureLabel": "功能",
       "filterAll": "就緒",
       "filterPlugins": "外掛程式",
       "filterCli": "應用程式",
-      "filterMcp": "整合",
+      "filterMcp": "MCP",
       "enabledSummary": "{{count}} 個就緒",
-      "caption": "{{cli}} 個應用程式 · {{mcp}} 個整合服務",
+      "caption": "{{cli}} 個應用程式 · {{mcp}} 個 MCP 工具",
       "searchPlaceholder": "搜尋工具",
       "featured": "工具",
+      "mcpTools": "MCP 工具",
       "loading": "正在載入應用程式…",
       "empty": "沒有符合搜尋條件的工具。",
       "emptyApps": "沒有可用的應用程式。",
-      "emptyIntegrations": "沒有可用的整合服務。",
+      "emptyIntegrations": "沒有可用的 MCP 工具。",
       "emptyReady": "尚無就緒的工具。",
       "clearSearch": "清除搜尋",
       "browseApps": "瀏覽應用程式",
-      "browseIntegrations": "瀏覽整合服務",
-      "emptyIntegrationsHint": "可在下方新增自訂整合服務。",
-      "restartRequired": "重新啟動 nanobot 以套用更新後的應用程式與整合服務。"
+      "browseIntegrations": "瀏覽 MCP 工具",
+      "emptyIntegrationsHint": "可在下方新增自訂 MCP 伺服器。",
+      "restartRequired": "重新啟動 nanobot 以套用更新後的應用程式與 MCP 工具。"
     },
     "channels": {
       "description": "將聊天應用程式、電子郵件與 WebUI 連線至 nanobot。",

webui/src/lib/api.ts

@@ -10,6 +10,7 @@ import type {
   FilePreviewPayload,
   ImageGenerationSettingsUpdate,
   McpPresetsPayload,
+  McpOAuthFlowPayload,
   MarketplaceProvider,
   NanobotFeaturesPayload,
   ModelConfigurationCreate,
@@ -97,7 +98,19 @@ async function request<T>(
   );
   if (!res.ok) {
     const text = typeof res.text === "function" ? (await res.text()).trim() : "";
-    throw new ApiError(res.status, text || `HTTP ${res.status}`);
+    let message = text;
+    if (text.startsWith("{")) {
+      try {
+        const payload: unknown = JSON.parse(text);
+        if (payload && typeof payload === "object") {
+          const error = (payload as { error?: unknown }).error;
+          if (typeof error === "string" && error.trim()) message = error.trim();
+        }
+      } catch {
+        // Preserve non-JSON error bodies exactly as returned by the gateway.
+      }
+    }
+    throw new ApiError(res.status, message || `HTTP ${res.status}`);
   }
   const contentType = res.headers?.get?.("content-type") ?? "";
   if (contentType && !contentType.toLowerCase().includes("application/json")) {
@@ -686,6 +699,56 @@ export async function fetchMcpPresets(
   );
 }
 
+export async function startMcpOAuth(
+  transport: WebUIMutationTransport,
+  name: string,
+  reset: boolean = false,
+): Promise<McpOAuthFlowPayload> {
+  return mutation<McpOAuthFlowPayload>(
+    transport,
+    "settings.mcp.oauth_start",
+    { name, ...(reset ? { reset: true } : {}) },
+    30_000,
+  );
+}
+
+export async function fetchMcpOAuthStatus(
+  token: string,
+  flowId: string,
+  base: string = "",
+): Promise<McpOAuthFlowPayload> {
+  const query = new URLSearchParams({ flow_id: flowId });
+  return request<McpOAuthFlowPayload>(
+    `${base}/api/settings/mcp-oauth/status?${query}`,
+    token,
+    undefined,
+    API_READ_TIMEOUT_MS,
+  );
+}
+
+export async function completeMcpOAuth(
+  transport: WebUIMutationTransport,
+  flowId: string,
+  callbackUrl: string,
+): Promise<McpOAuthFlowPayload> {
+  return mutation<McpOAuthFlowPayload>(
+    transport,
+    "settings.mcp.oauth_complete",
+    { flow_id: flowId, callback_url: callbackUrl },
+  );
+}
+
+export async function cancelMcpOAuth(
+  transport: WebUIMutationTransport,
+  flowId: string,
+): Promise<McpOAuthFlowPayload> {
+  return mutation<McpOAuthFlowPayload>(
+    transport,
+    "settings.mcp.oauth_cancel",
+    { flow_id: flowId },
+  );
+}
+
 export async function fetchProviderModels(
   token: string,
   provider: string,

webui/src/lib/types.ts

@@ -956,6 +956,7 @@ export interface McpPresetInfo {
   description: string;
   docs_url: string;
   transport: "stdio" | "streamableHttp" | "sse" | "oauth" | string;
+  auth?: "oauth" | null;
   requires: string;
   note: string;
   install_supported: boolean;
@@ -976,6 +977,30 @@ export interface McpPresetInfo {
   manifest?: AppManifest;
 }
 
+export type McpOAuthFlowStatus =
+  | "starting"
+  | "authorization_required"
+  | "connecting"
+  | "authorized"
+  | "connected"
+  | "failed"
+  | "cancelled";
+
+export interface McpOAuthFlowPayload {
+  flow_id: string;
+  name: string;
+  status: McpOAuthFlowStatus;
+  expires_in: number;
+  authorization_url?: string;
+  completion_input?: "callback_url";
+  error?: string;
+  hot_reload?: {
+    ok: boolean;
+    message?: string;
+    requires_restart?: boolean;
+  };
+}
+
 export interface McpPresetsPayload {
   presets: McpPresetInfo[];
   installed_count: number;

webui/src/tests/api.test.ts

@@ -1,7 +1,9 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
+  cancelMcpOAuth,
   configureChannel,
+  completeMcpOAuth,
   completeProviderOAuth,
   createModelConfiguration,
   createProviderSettings,
@@ -14,6 +16,7 @@ import {
   fetchApiService,
   fetchCliApps,
   fetchInstalledCliApps,
+  fetchMcpOAuthStatus,
   fetchMcpPresets,
   fetchMarketplaceSkillTrends,
   fetchNanobotFeatures,
@@ -41,6 +44,7 @@ import {
   saveCustomMcpServer,
   searchMarketplaceSkills,
   startApiService,
+  startMcpOAuth,
   stopApiService,
   cancelChannelConnect,
   pollChannelConnect,
@@ -545,6 +549,23 @@ describe("webui API helpers", () => {
     });
   });
 
+  it("extracts user-facing messages from JSON API errors", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 400,
+        headers: new Headers({ "content-type": "application/json" }),
+        text: async () => JSON.stringify({ error: "Paste the complete callback URL." }),
+      }),
+    );
+
+    await expect(fetchMcpOAuthStatus("tok", "flow-123")).rejects.toMatchObject({
+      status: 400,
+      message: "Paste the complete callback URL.",
+    });
+  });
+
   it("times out when an API request never responds", async () => {
     vi.useFakeTimers();
     vi.stubGlobal("fetch", vi.fn(() => new Promise<Response>(() => {})));
@@ -882,6 +903,35 @@ describe("webui API helpers", () => {
       { name: "browserbase", browserbase_api_key: "bb_live_test" },
       20_000,
     );
+
+    await startMcpOAuth(mutationTransport, "notion", true);
+    expect(requestMutation).toHaveBeenCalledWith(
+      "settings.mcp.oauth_start",
+      { name: "notion", reset: true },
+      30_000,
+    );
+
+    await fetchMcpOAuthStatus("tok", "flow-123");
+    expect(fetch).toHaveBeenCalledWith(
+      "/api/settings/mcp-oauth/status?flow_id=flow-123",
+      expect.objectContaining({ headers: { Authorization: "Bearer tok" } }),
+    );
+
+    const callbackUrl =
+      "http://127.0.0.1:8765/auth/mcp/callback?code=secret&state=state-123";
+    await completeMcpOAuth(mutationTransport, "flow-123", callbackUrl);
+    expect(requestMutation).toHaveBeenCalledWith(
+      "settings.mcp.oauth_complete",
+      { flow_id: "flow-123", callback_url: callbackUrl },
+      20_000,
+    );
+
+    await cancelMcpOAuth(mutationTransport, "flow-123");
+    expect(requestMutation).toHaveBeenCalledWith(
+      "settings.mcp.oauth_cancel",
+      { flow_id: "flow-123" },
+      20_000,
+    );
   });
 
   it("serializes custom MCP, mcp.json import, and tool allowlist actions", async () => {
@@ -899,6 +949,19 @@ describe("webui API helpers", () => {
       20_000,
     );
 
+    const oauthCustom = {
+      name: "company-mcp",
+      transport: "streamableHttp",
+      url: "https://mcp.example.com/mcp",
+      auth: "oauth",
+    };
+    await saveCustomMcpServer(mutationTransport, oauthCustom);
+    expect(requestMutation).toHaveBeenLastCalledWith(
+      "settings.mcp.custom",
+      oauthCustom,
+      20_000,
+    );
+
     await importMcpConfig(
       mutationTransport,
       '{"mcpServers":{"docs":{"command":"npx"}}}',

webui/src/tests/i18n.test.tsx

@@ -75,6 +75,18 @@ const LOCALIZED_SETTINGS_COPY_KEYS = [
   "settings.apps.description",
   "settings.apps.caption",
   "settings.apps.restartRequired",
+  "settings.mcp.connectingAccount",
+  "settings.mcp.continueSignIn",
+  "settings.mcp.preparingSignIn",
+  "settings.mcp.openSignInToContinue",
+  "settings.mcp.finishSignInInBrowser",
+  "settings.mcp.finishingConnection",
+  "settings.mcp.activatingTools",
+  "settings.mcp.connected",
+  "settings.mcp.connectionFailed",
+  "settings.mcp.connectionCancelled",
+  "settings.mcp.reloadFailed",
+  "settings.mcp.oauthFailed",
   "settings.skills.views",
   "settings.skills.installedTab",
   "settings.skills.discoverTab",

webui/src/tests/settings-view.test.tsx

@@ -334,6 +334,29 @@ const installedAnyGen = {
   skill_installed: true,
 };
 
+const xmindMcpPreset = {
+  name: "xmind",
+  display_name: "Xmind",
+  category: "productivity",
+  description: "Create, read, and edit cloud mind maps through Xmind.",
+  docs_url: "https://xmind.com/user-guide/xmind-mcp",
+  transport: "streamableHttp",
+  auth: "oauth" as const,
+  requires: "Xmind account",
+  note: "Connects securely in your browser with Xmind OAuth.",
+  install_supported: true,
+  installed: false,
+  configured: false,
+  available: false,
+  status: "not_installed",
+  logo_url: null,
+  brand_color: "#F4B41A",
+  required_fields: [],
+  connection_summary: "",
+  enabled_tools: ["*"],
+  source: "preset",
+};
+
 function renderSettingsView(
   options: {
     initialSection?:
@@ -652,6 +675,534 @@ describe("SettingsView Apps catalog", () => {
     expect(screen.queryByText("Uninstalled CLI for AnyGen.")).not.toBeInTheDocument();
   });
 
+  it("connects an OAuth MCP from the Apps catalog without manual callback input", async () => {
+    let connected = false;
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/settings") return jsonResponse(settingsPayload());
+      if (url === "/api/settings/cli-apps") {
+        return jsonResponse({ apps: [], installed_count: 0 });
+      }
+      if (url === "/api/settings/mcp-presets") {
+        return jsonResponse({
+          presets: [connected
+            ? {
+              ...xmindMcpPreset,
+              installed: true,
+              configured: true,
+              available: true,
+              status: "configured",
+              connection_summary: "https://app.xmind.com/api/mcp",
+            }
+            : xmindMcpPreset],
+          installed_count: connected ? 1 : 0,
+        });
+      }
+      if (url === "/api/settings/mcp-oauth/status?flow_id=flow-123") {
+        connected = true;
+        return jsonResponse({
+          flow_id: "flow-123",
+          name: "xmind",
+          status: "connected",
+          expires_in: 295,
+          hot_reload: {
+            ok: false,
+            requires_restart: false,
+            connected: ["xmind"],
+            failed: ["notion"],
+            message: "MCP config reloaded, but some servers did not connect: notion",
+          },
+        });
+      }
+      return { ok: false, status: 404, text: async () => "Not found" } as Response;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    requestMutationMock.mockImplementation(async (action: string) => {
+      if (action === "settings.mcp.oauth_start") {
+        return {
+          flow_id: "flow-123",
+          name: "xmind",
+          status: "authorization_required",
+          expires_in: 300,
+          authorization_url: "https://accounts.xmind.test/authorize?state=state-123",
+        };
+      }
+      return settingsPayload();
+    });
+    const replace = vi.fn();
+    const popup = {
+      opener: window,
+      closed: false,
+      location: { replace },
+      document: { title: "", body: { textContent: "" } },
+      focus: vi.fn(),
+      close: vi.fn(),
+    };
+    const open = vi.fn(() => popup);
+    vi.stubGlobal("open", open);
+
+    renderSettingsView({ initialSection: "apps" });
+    fireEvent.click(await screen.findByRole("button", { name: "MCP" }));
+    expect(screen.getByText("MCP tools")).toBeInTheDocument();
+    const connectButton = await screen.findByRole("button", { name: "Connect Xmind" });
+    expect(connectButton).toHaveTextContent("Connect");
+    fireEvent.click(connectButton);
+
+    expect(open).toHaveBeenCalledWith(
+      "about:blank",
+      "nanobot-mcp-oauth",
+      "popup,width=560,height=720,resizable=yes,scrollbars=yes",
+    );
+    await waitFor(() => expect(replace).toHaveBeenCalledWith(
+      "https://accounts.xmind.test/authorize?state=state-123",
+    ));
+    expect(popup.opener).toBeNull();
+    expect(screen.queryByRole("textbox", { name: /authorization/i })).not.toBeInTheDocument();
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Finish signing in in the browser window.",
+    );
+    expect(screen.getByRole("button", { name: "Connecting Xmind" })).toHaveTextContent(
+      "Connecting…",
+    );
+    expect(screen.getByRole("button", { name: "Cancel" })).toBeInTheDocument();
+
+    expect(await screen.findByRole("button", { name: "Xmind: Configured" }, { timeout: 2500 }))
+      .toHaveTextContent("Configured");
+    expect(screen.queryByRole("button", { name: "Cancel" })).not.toBeInTheDocument();
+    expect(screen.queryByText("Xmind connected.")).not.toBeInTheDocument();
+    expect(screen.queryByText(/some servers did not connect: notion/i)).not.toBeInTheDocument();
+    expect(popup.close).toHaveBeenCalledTimes(1);
+    expect(replace).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/settings/mcp-oauth/status?flow_id=flow-123",
+      expect.objectContaining({ headers: { Authorization: "Bearer tok" } }),
+    );
+  });
+
+  it("configures OAuth for a custom remote MCP without importing JSON", async () => {
+    const customPreset = {
+      ...xmindMcpPreset,
+      name: "team-mcp",
+      display_name: "team-mcp",
+      source: "custom",
+      installed: true,
+      status: "authorization_required",
+      connection_summary: "https://mcp.example.com/mcp",
+    };
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/settings") return jsonResponse(settingsPayload());
+      if (url === "/api/settings/cli-apps") {
+        return jsonResponse({ apps: [], installed_count: 0 });
+      }
+      if (url === "/api/settings/mcp-presets") {
+        return jsonResponse({ presets: [], installed_count: 0 });
+      }
+      return { ok: false, status: 404, text: async () => "Not found" } as Response;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    requestMutationMock.mockImplementation(async (action: string) => {
+      if (action === "settings.mcp.custom") {
+        return {
+          presets: [customPreset],
+          installed_count: 1,
+          hot_reload: {
+            ok: false,
+            message: "MCP config reloaded, but some servers did not connect: team-mcp",
+            failed: ["team-mcp"],
+          },
+          last_action: { ok: true, message: "Saved custom MCP server team-mcp." },
+        };
+      }
+      return settingsPayload();
+    });
+
+    renderSettingsView({ initialSection: "apps" });
+    fireEvent.click(await screen.findByRole("button", { name: "MCP" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Custom" }));
+
+    expect(screen.queryByText("Authentication")).not.toBeInTheDocument();
+    fireEvent.change(screen.getByLabelText("Server name"), {
+      target: { value: "team-mcp" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "HTTP" }));
+    fireEvent.change(screen.getByLabelText("URL"), {
+      target: { value: "https://mcp.example.com/mcp" },
+    });
+
+    const authentication = screen.getByRole("group", { name: "Authentication" });
+    const oauth = within(authentication).getByRole("button", { name: "OAuth" });
+    expect(oauth).toHaveAttribute("aria-pressed", "false");
+
+    fireEvent.click(within(authentication).getByRole("button", { name: "Headers" }));
+    fireEvent.change(screen.getByLabelText("Headers JSON"), {
+      target: { value: '{"Authorization":"Bearer stale"}' },
+    });
+    expect(screen.getByText("Add the request headers used by this server.")).toBeInTheDocument();
+
+    fireEvent.click(oauth);
+    expect(oauth).toHaveAttribute("aria-pressed", "true");
+    expect(screen.queryByLabelText("Headers JSON")).not.toBeInTheDocument();
+    expect(
+      screen.getByText("Save the server, then select Connect to sign in."),
+    ).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Save MCP" }));
+
+    await waitFor(() => {
+      const saveCall = requestMutationMock.mock.calls.find(
+        ([action]) => action === "settings.mcp.custom",
+      );
+      expect(saveCall).toBeDefined();
+      const values = saveCall?.[1] as Record<string, string>;
+      expect(values).toMatchObject({
+        name: "team-mcp",
+        transport: "streamableHttp",
+        url: "https://mcp.example.com/mcp",
+        auth: "oauth",
+      });
+      expect(values).not.toHaveProperty("headers");
+      expect(saveCall?.[2]).toBe(20_000);
+    });
+    expect(await screen.findByRole("button", { name: "Connect team-mcp" }))
+      .toBeInTheDocument();
+    expect(
+      screen.queryByText("MCP config reloaded, but some servers did not connect: team-mcp"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("offers a pasted callback flow when the remote WebUI uses HTTP", async () => {
+    let completed = false;
+    const callbackUrl =
+      "http://127.0.0.1:8765/auth/mcp/callback?code=oauth-code&state=manual-state";
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/settings") return jsonResponse(settingsPayload());
+      if (url === "/api/settings/cli-apps") {
+        return jsonResponse({ apps: [], installed_count: 0 });
+      }
+      if (url === "/api/settings/mcp-presets") {
+        return jsonResponse({
+          presets: [completed
+            ? {
+              ...xmindMcpPreset,
+              installed: true,
+              configured: true,
+              available: true,
+              status: "configured",
+              connection_summary: "https://app.xmind.com/api/mcp",
+            }
+            : xmindMcpPreset],
+          installed_count: completed ? 1 : 0,
+        });
+      }
+      if (url === "/api/settings/mcp-oauth/status?flow_id=flow-manual") {
+        return jsonResponse({
+          flow_id: "flow-manual",
+          name: "xmind",
+          status: completed ? "connected" : "authorization_required",
+          expires_in: 298,
+          completion_input: "callback_url",
+          authorization_url: completed
+            ? undefined
+            : "https://accounts.xmind.test/authorize?state=manual-state",
+          hot_reload: completed ? { ok: true, requires_restart: false } : undefined,
+        });
+      }
+      return { ok: false, status: 404, text: async () => "Not found" } as Response;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    requestMutationMock.mockImplementation(async (action: string) => {
+      if (action === "settings.mcp.oauth_start") {
+        return {
+          flow_id: "flow-manual",
+          name: "xmind",
+          status: "authorization_required",
+          expires_in: 300,
+          completion_input: "callback_url",
+          authorization_url: "https://accounts.xmind.test/authorize?state=manual-state",
+        };
+      }
+      if (action === "settings.mcp.oauth_complete") {
+        completed = true;
+        return {
+          flow_id: "flow-manual",
+          name: "xmind",
+          status: "connecting",
+          expires_in: 299,
+          completion_input: "callback_url",
+        };
+      }
+      return settingsPayload();
+    });
+    const popup = {
+      opener: window,
+      closed: false,
+      location: { replace: vi.fn() },
+      document: { title: "", body: { textContent: "" } },
+      focus: vi.fn(),
+      close: vi.fn(),
+    };
+    vi.stubGlobal("open", vi.fn(() => popup));
+
+    renderSettingsView({ initialSection: "apps" });
+    fireEvent.click(await screen.findByRole("button", { name: "MCP" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Connect Xmind" }));
+
+    const callbackInput = await screen.findByRole("textbox", { name: "Full callback URL" });
+    expect(screen.getByText(/localhost page will not load/i)).toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Finish signing in, then paste the callback URL into nanobot.",
+    );
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+
+    fireEvent.change(callbackInput, { target: { value: callbackUrl } });
+    fireEvent.click(screen.getByRole("button", { name: "Finish sign-in" }));
+
+    await waitFor(() => expect(requestMutationMock).toHaveBeenCalledWith(
+      "settings.mcp.oauth_complete",
+      { flow_id: "flow-manual", callback_url: callbackUrl },
+      20_000,
+    ));
+    expect(await screen.findByRole("button", { name: "Xmind: Configured" }, { timeout: 2500 }))
+      .toHaveTextContent("Configured");
+    expect(screen.queryByRole("textbox", { name: "Full callback URL" })).not.toBeInTheDocument();
+    expect(popup.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("lets the user cancel an active OAuth connection after closing the popup", async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/settings") return jsonResponse(settingsPayload());
+      if (url === "/api/settings/cli-apps") return jsonResponse({ apps: [], installed_count: 0 });
+      if (url === "/api/settings/mcp-presets") {
+        return jsonResponse({ presets: [xmindMcpPreset], installed_count: 0 });
+      }
+      if (url === "/api/settings/mcp-oauth/status?flow_id=flow-cancel") {
+        return new Promise<Response>(() => {});
+      }
+      return { ok: false, status: 404, text: async () => "Not found" } as Response;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    requestMutationMock.mockImplementation(async (action: string) => {
+      if (action === "settings.mcp.oauth_start") {
+        return {
+          flow_id: "flow-cancel",
+          name: "xmind",
+          status: "authorization_required",
+          expires_in: 300,
+          authorization_url: "https://accounts.xmind.test/authorize?state=cancel",
+        };
+      }
+      if (action === "settings.mcp.oauth_cancel") {
+        return {
+          flow_id: "flow-cancel",
+          name: "xmind",
+          status: "cancelled",
+          expires_in: 299,
+        };
+      }
+      return settingsPayload();
+    });
+    const popup = {
+      opener: window,
+      closed: false,
+      location: { replace: vi.fn() },
+      document: { title: "", body: { textContent: "" } },
+      focus: vi.fn(),
+      close: vi.fn(),
+    };
+    vi.stubGlobal("open", vi.fn(() => popup));
+
+    renderSettingsView({ initialSection: "apps" });
+    fireEvent.click(await screen.findByRole("button", { name: "MCP" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Connect Xmind" }));
+
+    const cancelButton = await screen.findByRole("button", { name: "Cancel" });
+    expect(screen.getByRole("button", { name: "Connecting Xmind" })).toBeInTheDocument();
+    popup.closed = true;
+    fireEvent.click(cancelButton);
+
+    await waitFor(() => expect(requestMutationMock).toHaveBeenCalledWith(
+      "settings.mcp.oauth_cancel",
+      { flow_id: "flow-cancel" },
+      20_000,
+    ));
+    expect(await screen.findByRole("button", { name: "Connect Xmind" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Connecting Xmind" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Cancel" })).not.toBeInTheDocument();
+    expect(popup.close).not.toHaveBeenCalled();
+  });
+
+  it("silently removes an MCP when the card already shows the result", async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/settings") return jsonResponse(settingsPayload());
+      if (url === "/api/settings/cli-apps") {
+        return jsonResponse({ apps: [], installed_count: 0 });
+      }
+      if (url === "/api/settings/mcp-presets") {
+        return jsonResponse({
+          presets: [{
+            ...xmindMcpPreset,
+            installed: true,
+            configured: true,
+            available: true,
+            status: "configured",
+            connection_summary: "https://app.xmind.com/api/mcp",
+          }],
+          installed_count: 1,
+        });
+      }
+      return { ok: false, status: 404, text: async () => "Not found" } as Response;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    requestMutationMock.mockResolvedValueOnce({
+      presets: [xmindMcpPreset],
+      installed_count: 0,
+      requires_restart: false,
+      hot_reload: {
+        ok: true,
+        message: "MCP config reloaded without restarting nanobot.",
+      },
+      last_action: {
+        ok: true,
+        message: "Removed MCP preset for Xmind. MCP config reloaded without restarting nanobot.",
+        removed: true,
+      },
+    });
+
+    renderSettingsView({ initialSection: "apps" });
+    fireEvent.click(await screen.findByRole("button", { name: "MCP" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Remove" }));
+
+    await waitFor(() => expect(requestMutationMock).toHaveBeenCalledWith(
+      "settings.mcp.remove",
+      { name: "xmind" },
+      20_000,
+    ));
+    expect(await screen.findByRole("button", { name: "Connect Xmind" })).toBeInTheDocument();
+    expect(screen.queryByText(/Removed MCP preset|reloaded without restarting/)).not.toBeInTheDocument();
+  });
+
+  it("offers a one-click recovery when the OAuth popup is blocked", async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/settings") return jsonResponse(settingsPayload());
+      if (url === "/api/settings/cli-apps") return jsonResponse({ apps: [], installed_count: 0 });
+      if (url === "/api/settings/mcp-presets") {
+        return jsonResponse({ presets: [xmindMcpPreset], installed_count: 0 });
+      }
+      return new Promise<Response>(() => {});
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    requestMutationMock.mockImplementation(async (action: string) => {
+      if (action === "settings.mcp.oauth_start") {
+        return {
+          flow_id: "flow-blocked",
+          name: "xmind",
+          status: "authorization_required",
+          expires_in: 300,
+          authorization_url: "https://accounts.xmind.test/authorize?state=blocked",
+        };
+      }
+      return settingsPayload();
+    });
+    const popup = {
+      opener: window,
+      closed: false,
+      location: { replace: vi.fn() },
+      focus: vi.fn(),
+      close: vi.fn(),
+    };
+    const open = vi.fn()
+      .mockReturnValueOnce(null)
+      .mockReturnValueOnce(popup);
+    vi.stubGlobal("open", open);
+
+    renderSettingsView({ initialSection: "apps" });
+    fireEvent.click(await screen.findByRole("button", { name: "MCP" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Connect Xmind" }));
+
+    const continueButton = await screen.findByRole("button", { name: "Continue sign-in" });
+    expect(screen.getByRole("status")).toHaveTextContent("Open the sign-in page to continue.");
+    expect(screen.getByRole("button", { name: "Cancel" })).toBeInTheDocument();
+    fireEvent.click(continueButton);
+    expect(open).toHaveBeenLastCalledWith(
+      "https://accounts.xmind.test/authorize?state=blocked",
+      "nanobot-mcp-oauth",
+      "popup,width=560,height=720,resizable=yes,scrollbars=yes",
+    );
+    expect(screen.getByRole("button", { name: "Cancel" })).toBeInTheDocument();
+  });
+
+  it("does not mistake a COOP-isolated OAuth tab for a blocked popup", async () => {
+    let popupIsolated = false;
+    let statusCalls = 0;
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === "/api/settings") return jsonResponse(settingsPayload());
+      if (url === "/api/settings/cli-apps") return jsonResponse({ apps: [], installed_count: 0 });
+      if (url === "/api/settings/mcp-presets") {
+        return jsonResponse({ presets: [xmindMcpPreset], installed_count: 0 });
+      }
+      if (url === "/api/settings/mcp-oauth/status?flow_id=flow-coop") {
+        statusCalls += 1;
+        return jsonResponse({
+          flow_id: "flow-coop",
+          name: "xmind",
+          status: statusCalls === 1 ? "authorization_required" : "failed",
+          expires_in: 299,
+          error: statusCalls === 1 ? undefined : "Cancelled for test cleanup.",
+          authorization_url: statusCalls === 1
+            ? "https://accounts.xmind.test/authorize?state=coop"
+            : undefined,
+        });
+      }
+      return { ok: false, status: 404, text: async () => "Not found" } as Response;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    requestMutationMock.mockImplementation(async (action: string) => {
+      if (action === "settings.mcp.oauth_start") {
+        return {
+          flow_id: "flow-coop",
+          name: "xmind",
+          status: "authorization_required",
+          expires_in: 300,
+          authorization_url: "https://accounts.xmind.test/authorize?state=coop",
+        };
+      }
+      return settingsPayload();
+    });
+    const popup = {
+      opener: window,
+      get closed() {
+        return popupIsolated;
+      },
+      location: {
+        replace: vi.fn(() => {
+          popupIsolated = true;
+        }),
+      },
+      document: { title: "", body: { textContent: "" } },
+      focus: vi.fn(),
+      close: vi.fn(),
+    };
+    vi.stubGlobal("open", vi.fn(() => popup));
+
+    renderSettingsView({ initialSection: "apps" });
+    fireEvent.click(await screen.findByRole("button", { name: "MCP" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Connect Xmind" }));
+
+    await waitFor(() => expect(statusCalls).toBe(1), { timeout: 2000 });
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Finish signing in in the browser window.",
+    );
+    expect(screen.queryByRole("button", { name: "Continue sign-in" })).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Cancel" })).toBeInTheDocument();
+  });
+
   it("keeps runtime dependencies out of Apps and explains chat mentions", async () => {
     vi.stubGlobal("fetch", vi.fn(async (input: RequestInfo | URL) => {
       const url = String(input);
@@ -694,7 +1245,7 @@ describe("SettingsView Apps catalog", () => {
     ).not.toBeInTheDocument();
     expect(screen.getByRole("button", { name: "Ready" })).toHaveAttribute("aria-pressed", "false");
     expect(screen.getByRole("button", { name: "Apps" })).toHaveAttribute("aria-pressed", "true");
-    expect(screen.getByRole("button", { name: "Integrations" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "MCP" })).toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Plugins" })).not.toBeInTheDocument();
     expect(screen.queryByText("Api")).not.toBeInTheDocument();
     expect(screen.queryByText("0 ready")).not.toBeInTheDocument();
@@ -2023,8 +2574,8 @@ describe("SettingsView Apps catalog", () => {
 
     expect(await screen.findByText("No apps available.")).toBeInTheDocument();
     expect(screen.queryByText("Loading Apps...")).not.toBeInTheDocument();
-    fireEvent.click(screen.getByRole("button", { name: "Browse integrations" }));
-    expect(await screen.findByText("Add integration")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Browse MCP tools" }));
+    expect(await screen.findByText("Add MCP server")).toBeInTheDocument();
   });
 
   it("shows token activity on the overview", async () => {