openhands-agent-server 1.22.1__tar.gz → 1.23.0__tar.gz

{openhands_agent_server-1.22.1 → openhands_agent_server-1.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.22.1
+Version: 1.23.0
 Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk

{openhands_agent_server-1.22.1 → openhands_agent_server-1.23.0}/openhands/agent_server/api.py

@@ -38,6 +38,7 @@ from openhands.agent_server.file_router import file_router
 from openhands.agent_server.git_router import git_router
 from openhands.agent_server.hooks_router import hooks_router
 from openhands.agent_server.llm_router import llm_router
+from openhands.agent_server.mcp_router import mcp_router
 from openhands.agent_server.middleware import LocalhostCORSMiddleware
 from openhands.agent_server.profiles_router import profiles_router
 from openhands.agent_server.server_details_router import (
@@ -53,6 +54,7 @@ from openhands.agent_server.tool_router import tool_router
 from openhands.agent_server.vscode_router import vscode_router
 from openhands.agent_server.vscode_service import get_vscode_service
 from openhands.agent_server.workspace_router import workspace_router
+from openhands.agent_server.workspaces_router import workspaces_router
 from openhands.sdk.logger import DEBUG, get_logger
 from openhands.sdk.utils.redact import sanitize_dict
 from openhands.tools.terminal.constants import TMUX_SOCKET_NAME
@@ -288,7 +290,9 @@ def _add_api_routes(app: FastAPI, config: Config) -> None:
     api_router.include_router(skills_router)
     api_router.include_router(hooks_router)
     api_router.include_router(llm_router)
+    api_router.include_router(mcp_router)
     api_router.include_router(settings_router)
+    api_router.include_router(workspaces_router)
     api_router.include_router(profiles_router)
     api_router.include_router(cloud_proxy_router)
     # /api/auth/* mints workspace cookies and requires the header to bootstrap,

{openhands_agent_server-1.22.1 → openhands_agent_server-1.23.0}/openhands/agent_server/conversation_router.py

@@ -22,6 +22,7 @@ from openhands.agent_server._secrets_exposure import (
 from openhands.agent_server.conversation_service import ConversationService
 from openhands.agent_server.dependencies import get_conversation_service
 from openhands.agent_server.models import (
+    INCLUDE_SKILLS_PARAM_TITLE,
     AgentResponseResult,
     AskAgentRequest,
     AskAgentResponse,
@@ -36,6 +37,7 @@ from openhands.agent_server.models import (
     Success,
     UpdateConversationRequest,
     UpdateSecretsRequest,
+    trim_conversation_response_skills,
 )
 from openhands.sdk import LLM, Agent, TextContent
 from openhands.sdk.conversation.state import ConversationExecutionStatus
@@ -86,14 +88,28 @@ async def search_conversations(
         ConversationSortOrder,
         Query(title="Sort order for conversations"),
     ] = ConversationSortOrder.CREATED_AT_DESC,
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ConversationPage:
     """Search / List conversations"""
     assert limit > 0
     assert limit <= 100
-    return await conversation_service.search_conversations(
+    page = await conversation_service.search_conversations(
         page_id, limit, status, sort_order
     )
+    if not include_skills:
+        # ``model_copy`` rather than in-place mutation so we never
+        # write back into whatever the upstream service handed us
+        # (matters for services that cache their return value,
+        # including the ``AsyncMock`` used in route tests).
+        page = page.model_copy(
+            update={
+                "items": [
+                    trim_conversation_response_skills(item) for item in page.items
+                ]
+            }
+        )
+    return page
 
 
 @conversation_router.get("/count")
@@ -114,12 +130,15 @@ async def count_conversations(
 )
 async def get_conversation(
     conversation_id: UUID,
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ConversationInfo:
     """Given an id, get a conversation"""
     conversation = await conversation_service.get_conversation(conversation_id)
     if conversation is None:
         raise HTTPException(status.HTTP_404_NOT_FOUND)
+    if not include_skills:
+        conversation = trim_conversation_response_skills(conversation)
     return conversation
 
 
@@ -147,12 +166,18 @@ async def get_conversation_agent_final_response(
 @conversation_router.get("")
 async def batch_get_conversations(
     ids: Annotated[list[UUID], Query()],
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> list[ConversationInfo | None]:
     """Get a batch of conversations given their ids, returning null for
     any missing item"""
     assert len(ids) < 100
     conversations = await conversation_service.batch_get_conversations(ids)
+    if not include_skills:
+        return [
+            trim_conversation_response_skills(c) if c is not None else None
+            for c in conversations
+        ]
     return conversations
 
 
@@ -165,11 +190,14 @@ async def start_conversation(
         StartConversationRequest, Body(examples=START_CONVERSATION_EXAMPLES)
     ],
     response: Response,
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ConversationInfo:
     """Start a conversation in the local environment."""
     info, is_new = await conversation_service.start_conversation(request)
     response.status_code = status.HTTP_201_CREATED if is_new else status.HTTP_200_OK
+    if not include_skills:
+        info = trim_conversation_response_skills(info)
     return info
 
 
@@ -187,6 +215,26 @@ async def pause_conversation(
     return Success()
 
 
+@conversation_router.post(
+    "/{conversation_id}/interrupt",
+    responses={404: {"description": "Item not found"}},
+)
+async def interrupt_conversation(
+    conversation_id: UUID,
+    conversation_service: ConversationService = Depends(get_conversation_service),
+) -> Success:
+    """Immediately interrupt a running conversation.
+
+    Unlike ``/pause``, which waits for the current LLM call to finish,
+    ``/interrupt`` cancels the in-flight request so the effect is instant.
+    The conversation transitions to *paused* and can be resumed later.
+    """
+    interrupted = await conversation_service.interrupt_conversation(conversation_id)
+    if not interrupted:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST)
+    return Success()
+
+
 @conversation_router.delete(
     "/{conversation_id}", responses={404: {"description": "Item not found"}}
 )
@@ -407,6 +455,7 @@ async def condense_conversation(
 async def fork_conversation(
     conversation_id: UUID,
     request: Annotated[ForkConversationRequest, Body()] = ForkConversationRequest(),  # noqa: B008
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ConversationInfo:
     """Fork a conversation, deep-copying its event history.
@@ -432,4 +481,6 @@ async def fork_conversation(
             status.HTTP_404_NOT_FOUND,
             detail="Source conversation not found",
         )
+    if not include_skills:
+        info = trim_conversation_response_skills(info)
     return info

{openhands_agent_server-1.22.1 → openhands_agent_server-1.23.0}/openhands/agent_server/conversation_router_acp.py

@@ -14,11 +14,13 @@ from pydantic import SecretStr
 from openhands.agent_server.conversation_service import ConversationService
 from openhands.agent_server.dependencies import get_conversation_service
 from openhands.agent_server.models import (
+    INCLUDE_SKILLS_PARAM_TITLE,
     ACPConversationInfo,
     ACPConversationPage,
     ConversationSortOrder,
     SendMessageRequest,
     StartACPConversationRequest,
+    trim_conversation_response_skills,
 )
 from openhands.sdk import LLM, Agent, TextContent
 from openhands.sdk.agent.acp_agent import ACPAgent
@@ -76,6 +78,7 @@ async def search_acp_conversations(
         ConversationSortOrder,
         Query(title="Sort order for conversations"),
     ] = ConversationSortOrder.CREATED_AT_DESC,
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ACPConversationPage:
     """Search conversations using the ACP-capable contract.
@@ -85,9 +88,18 @@ async def search_acp_conversations(
     """
     assert limit > 0
     assert limit <= 100
-    return await conversation_service.search_acp_conversations(
+    page = await conversation_service.search_acp_conversations(
         page_id, limit, status, sort_order
     )
+    if not include_skills:
+        page = page.model_copy(
+            update={
+                "items": [
+                    trim_conversation_response_skills(item) for item in page.items
+                ]
+            }
+        )
+    return page
 
 
 @conversation_router_acp.get("/count", deprecated=True)
@@ -113,6 +125,7 @@ async def count_acp_conversations(
 )
 async def get_acp_conversation(
     conversation_id: UUID,
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ACPConversationInfo:
     """Get a conversation using the ACP-capable contract.
@@ -123,12 +136,15 @@ async def get_acp_conversation(
     conversation = await conversation_service.get_acp_conversation(conversation_id)
     if conversation is None:
         raise HTTPException(status.HTTP_404_NOT_FOUND)
+    if not include_skills:
+        conversation = trim_conversation_response_skills(conversation)
     return conversation
 
 
 @conversation_router_acp.get("", deprecated=True)
 async def batch_get_acp_conversations(
     ids: Annotated[list[UUID], Query()],
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> list[ACPConversationInfo | None]:
     """Batch get conversations using the ACP-capable contract.
@@ -137,7 +153,13 @@ async def batch_get_acp_conversations(
     Use ``/api/conversations`` instead.
     """
     assert len(ids) < 100
-    return await conversation_service.batch_get_acp_conversations(ids)
+    conversations = await conversation_service.batch_get_acp_conversations(ids)
+    if not include_skills:
+        return [
+            trim_conversation_response_skills(c) if c is not None else None
+            for c in conversations
+        ]
+    return conversations
 
 
 @conversation_router_acp.post("", deprecated=True)
@@ -147,6 +169,7 @@ async def start_acp_conversation(
         Body(examples=START_ACP_CONVERSATION_EXAMPLES),
     ],
     response: Response,
+    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ACPConversationInfo:
     """Start a conversation using the ACP-capable contract.
@@ -157,4 +180,6 @@ async def start_acp_conversation(
     """
     info, is_new = await conversation_service.start_acp_conversation(request)
     response.status_code = status.HTTP_201_CREATED if is_new else status.HTTP_200_OK
+    if not include_skills:
+        info = trim_conversation_response_skills(info)
     return info

{openhands_agent_server-1.22.1 → openhands_agent_server-1.23.0}/openhands/agent_server/conversation_service.py

@@ -649,6 +649,25 @@ class ConversationService:
             await self._notify_conversation_webhooks(conversation_info)
         return bool(event_service)
 
+    async def interrupt_conversation(self, conversation_id: UUID) -> bool:
+        """Immediately cancel an in-flight LLM call for a conversation.
+
+        Unlike :meth:`pause_conversation`, which waits for the current
+        LLM request to finish, this cancels the running ``arun()`` task
+        so the interruption takes effect mid-stream.
+        """
+        if self._event_services is None:
+            raise ValueError("inactive_service")
+        event_service = self._event_services.get(conversation_id)
+        if event_service:
+            await event_service.interrupt()
+            state = await event_service.get_state()
+            conversation_info = _compose_webhook_conversation_info(
+                event_service.stored, state
+            )
+            await self._notify_conversation_webhooks(conversation_info)
+        return bool(event_service)
+
     async def resume_conversation(self, conversation_id: UUID) -> bool:
         if self._event_services is None:
             raise ValueError("inactive_service")

{openhands_agent_server-1.22.1 → openhands_agent_server-1.23.0}/openhands/agent_server/event_service.py

@@ -18,6 +18,7 @@ from openhands.agent_server.models import (
 )
 from openhands.agent_server.pub_sub import PubSub, Subscriber
 from openhands.sdk import LLM, AgentBase, Event, Message, get_logger
+from openhands.sdk.conversation.base import BaseConversation
 from openhands.sdk.conversation.impl.local_conversation import LocalConversation
 from openhands.sdk.conversation.response_utils import get_agent_final_response
 from openhands.sdk.conversation.secret_registry import SecretValue
@@ -706,8 +707,11 @@ class EventService:
         """Run the conversation asynchronously in the background.
 
         This method starts the conversation run in a background task and returns
-        immediately. The conversation status can be monitored via the
-        GET /api/conversations/{id} endpoint or WebSocket events.
+        immediately.  When possible, the conversation is driven via its native
+        ``arun()`` coroutine so LLM I/O does not tie up a thread-pool worker.
+        For conversations that do not expose ``arun()`` (e.g., custom
+        subclasses), the synchronous ``run()`` is executed in the thread pool as
+        before.
 
         Raises:
             ValueError: If the service is inactive or conversation is already running.
@@ -735,7 +739,28 @@ class EventService:
 
             async def _run_and_publish():
                 try:
-                    await loop.run_in_executor(self._run_executor, conversation.run)
+                    # Prefer the native async path when available so the event
+                    # loop is free during LLM I/O.  Fall back to thread-pool
+                    # execution for backward compatibility.
+                    #
+                    # Both guards are required:
+                    #  • iscoroutinefunction – filters out non-async objects
+                    #    (e.g. MagicMock in tests).
+                    #  • override check – BaseConversation defines a default
+                    #    ``async def arun()`` that delegates to sync ``run()``,
+                    #    so iscoroutinefunction alone is always True for real
+                    #    subclasses.  We detect an *actual* override to avoid
+                    #    running a sync-only subclass on the event loop.
+                    arun = getattr(conversation, "arun", None)
+                    has_native_arun = (
+                        arun is not None
+                        and asyncio.iscoroutinefunction(arun)
+                        and type(conversation).arun is not BaseConversation.arun
+                    )
+                    if has_native_arun:
+                        await conversation.arun()
+                    else:
+                        await loop.run_in_executor(self._run_executor, conversation.run)
                 except Exception:
                     logger.exception("Error during conversation run")
                 finally:
@@ -787,6 +812,28 @@ class EventService:
             # Publish state update after pause to ensure stats are updated
             await self._publish_state_update()
 
+    async def interrupt(self):
+        """Immediately cancel an in-flight async LLM call.
+
+        Delegates to :meth:`LocalConversation.interrupt` which cancels the
+        ``arun()`` task.  If no async run is in progress the call falls
+        back to :meth:`pause`.
+        """
+        if self._conversation:
+            self._conversation.interrupt()
+            # Wait for the run task to finish so we can publish the final
+            # state update (PAUSED + InterruptEvent) cleanly.
+            if self._run_task is not None and not self._run_task.done():
+                with suppress(Exception):
+                    await asyncio.wait_for(self._run_task, timeout=5.0)
+                # Only clear _run_task if it actually finished; if
+                # wait_for timed out the task may still be running and
+                # clearing prematurely would allow a second run() to
+                # start while the first is still in progress.
+                if self._run_task is not None and self._run_task.done():
+                    self._run_task = None
+            await self._publish_state_update()
+
     async def update_secrets(self, secrets: dict[str, SecretValue]):
         """Update secrets in the conversation."""
         if not self._conversation:
@@ -832,8 +879,15 @@ class EventService:
                     logger.warning(
                         "Failed to pause conversation during close", exc_info=True
                     )
+            # Cancel the run task so arun()'s CancelledError handler can
+            # transition to PAUSED cleanly.  For the legacy thread-pool
+            # path the underlying thread keeps running but the wrapper
+            # task still settles, unblocking the wait below.
+            self._run_task.cancel()
             try:
                 await asyncio.wait_for(self._run_task, timeout=10.0)
+            except asyncio.CancelledError:
+                pass  # Expected after cancel()
             except Exception as exc:
                 logger.warning("Run task did not exit cleanly during close: %s", exc)
             self._run_task = None

openhands_agent_server-1.23.0/openhands/agent_server/mcp_router.py

@@ -0,0 +1,225 @@
+"""MCP router for OpenHands SDK.
+
+Exposes a single endpoint, ``POST /api/mcp/test``, that lets clients verify
+a candidate MCP server configuration in isolation -- before persisting it
+to settings, where a misconfiguration would otherwise surface only at
+conversation start (and there manifest as a noisy traceback that aborts
+agent initialization).
+
+The endpoint is intentionally side-effect-free: it spins up the MCP
+connection, lists the advertised tools, then tears the connection down.
+It never mutates server state or touches stored settings.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated, Any, Literal
+
+from fastapi import APIRouter
+from pydantic import BaseModel, Field, model_validator
+
+from openhands.sdk.logger import get_logger
+from openhands.sdk.mcp import create_mcp_tools
+from openhands.sdk.mcp.exceptions import MCPError, MCPTimeoutError
+
+
+logger = get_logger(__name__)
+
+mcp_router = APIRouter(prefix="/mcp", tags=["MCP"])
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+#
+# We accept a single server spec instead of the full ``MCPConfig`` map. The
+# UI flow this powers ("add a new MCP server") always validates one server
+# at a time, and keeping the request shape narrow avoids exposing tuple-of-
+# transports semantics the caller doesn't need.
+
+_DEFAULT_SERVER_NAME = "test-server"
+
+
+class _StdioMCPServerSpec(BaseModel):
+    """Stdio (subprocess) MCP server spec.
+
+    Mirrors the subset of ``fastmcp.mcp_config.StdioMCPServer`` fields the
+    OpenHands UI exposes today.
+    """
+
+    type: Literal["stdio"] = "stdio"
+    command: str = Field(..., min_length=1, description="Executable to invoke")
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, str] = Field(default_factory=dict)
+    cwd: str | None = None
+
+
+class _RemoteMCPServerSpec(BaseModel):
+    """Remote (HTTP / SSE) MCP server spec."""
+
+    # ``shttp`` is the alias the OpenHands settings layer uses for
+    # streamable-http; we accept both spellings so the UI can forward
+    # its own value unchanged.
+    type: Literal["http", "shttp", "streamable-http", "sse"]
+    url: str = Field(..., min_length=1)
+    headers: dict[str, str] = Field(default_factory=dict)
+    api_key: str | None = Field(
+        default=None,
+        description=(
+            "Bearer token. If provided, sent as 'Authorization: Bearer <token>'."
+        ),
+    )
+
+    def to_fastmcp_dict(self) -> dict[str, Any]:
+        # fastmcp's RemoteMCPServer accepts "http", "streamable-http", "sse";
+        # collapse the OpenHands-specific "shttp" alias to "http".
+        transport = "http" if self.type == "shttp" else self.type
+        out: dict[str, Any] = {"url": self.url, "transport": transport}
+        headers = dict(self.headers)
+        if self.api_key:
+            # Don't clobber a caller-provided Authorization header.
+            headers.setdefault("Authorization", f"Bearer {self.api_key}")
+        if headers:
+            out["headers"] = headers
+        return out
+
+
+class MCPTestRequest(BaseModel):
+    """Body for ``POST /api/mcp/test``."""
+
+    name: str = Field(
+        default=_DEFAULT_SERVER_NAME,
+        min_length=1,
+        max_length=128,
+        description=(
+            "Name to use for the server inside the temporary MCPConfig. "
+            "Only affects error messages -- does not need to match any "
+            "persisted setting."
+        ),
+    )
+    server: Annotated[
+        _StdioMCPServerSpec | _RemoteMCPServerSpec,
+        Field(discriminator="type"),
+    ]
+    timeout: float = Field(
+        default=15.0,
+        gt=0,
+        le=120,
+        description="Seconds to wait for connection + tools/list to complete.",
+    )
+
+    @model_validator(mode="after")
+    def _strip_name(self) -> MCPTestRequest:
+        # Mirror the validation MCPConfig itself applies to server keys --
+        # whitespace-only names would silently bypass min_length=1 above.
+        self.name = self.name.strip() or _DEFAULT_SERVER_NAME
+        return self
+
+
+class MCPTestSuccess(BaseModel):
+    """Response when the candidate server connects and lists its tools."""
+
+    ok: Literal[True] = True
+    tools: list[str] = Field(
+        default_factory=list,
+        description="Names of tools advertised by the MCP server.",
+    )
+
+
+class MCPTestFailure(BaseModel):
+    """Response when the candidate server fails to connect or list tools.
+
+    The endpoint returns HTTP 200 in both success and failure cases: a
+    failure here is the *expected* outcome of validating a user-supplied
+    config, not a server-side error. The structured shape makes it easy
+    for the UI to render an actionable message.
+    """
+
+    ok: Literal[False] = False
+    error: str = Field(description="Human-readable error message.")
+    error_kind: Literal["timeout", "connection", "unknown"] = Field(
+        description="Coarse error classification, useful for branching UI."
+    )
+
+
+MCPTestResponse = MCPTestSuccess | MCPTestFailure
+
+
+# ---------------------------------------------------------------------------
+# Endpoint
+# ---------------------------------------------------------------------------
+
+
+def _server_to_fastmcp_dict(spec: _StdioMCPServerSpec | _RemoteMCPServerSpec) -> dict:
+    if isinstance(spec, _StdioMCPServerSpec):
+        out: dict[str, Any] = {"command": spec.command, "args": list(spec.args)}
+        if spec.env:
+            out["env"] = dict(spec.env)
+        if spec.cwd:
+            out["cwd"] = spec.cwd
+        return out
+    return spec.to_fastmcp_dict()
+
+
+def _probe_mcp_server(request: MCPTestRequest) -> MCPTestResponse:
+    """Synchronous probe -- safe to run inside ``run_in_executor``.
+
+    ``create_mcp_tools`` already runs its own event loop in a background
+    thread via ``MCPClient.call_async_from_sync``. We deliberately do not
+    call it from the FastAPI request task; instead the caller hops into a
+    threadpool first.
+    """
+
+    config = {"mcpServers": {request.name: _server_to_fastmcp_dict(request.server)}}
+
+    try:
+        # ``create_mcp_tools`` returns a client that owns a background loop
+        # and a (possibly long-lived) subprocess. Use the context-manager
+        # form so we always tear it down, even when listing succeeded.
+        with create_mcp_tools(config, timeout=request.timeout) as client:
+            return MCPTestSuccess(tools=[tool.name for tool in client.tools])
+    except MCPTimeoutError as exc:
+        logger.info("MCP test timed out for server %r: %s", request.name, exc)
+        return MCPTestFailure(error=str(exc), error_kind="timeout")
+    except MCPError as exc:
+        # ``MCPError("MCP Connection Failure")`` is what client.connect()
+        # raises when the underlying fastmcp client fails to start. Surface
+        # the root-cause message (e.g. "sh: 1: mcp-server-github: Permission
+        # denied") because the wrapper alone isn't useful.
+        cause = exc.__cause__ or exc.__context__
+        detail = str(cause) if cause else str(exc) or "Failed to connect to MCP server"
+        logger.info(
+            "MCP test connection failed for server %r: %s", request.name, detail
+        )
+        return MCPTestFailure(error=detail, error_kind="connection")
+    except Exception as exc:  # noqa: BLE001 - we want to surface anything else
+        # Any other exception is unexpected but should still return a
+        # structured response: the UI can't recover from a 500.
+        logger.warning(
+            "MCP test failed unexpectedly for server %r",
+            request.name,
+            exc_info=True,
+        )
+        return MCPTestFailure(
+            error=f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__,
+            error_kind="unknown",
+        )
+
+
+@mcp_router.post(
+    "/test",
+    response_model=MCPTestResponse,
+    summary="Test an MCP server configuration",
+    description=(
+        "Attempt to connect to a candidate MCP server and list its tools, "
+        "without persisting any settings. Useful for validating user input "
+        "in 'add MCP server' flows before storing the config. "
+        "Returns 200 with `ok=false` for connection / timeout failures "
+        "(those are expected during validation, not server errors)."
+    ),
+)
+async def test_mcp_server(request: MCPTestRequest) -> MCPTestResponse:
+    """Probe a single MCP server config and report whether it works."""
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, _probe_mcp_server, request)