RHIDP-12470: Add API endpoints for dynamically registering and unregistering MCP Servers

src/app/endpoints/mcp_servers.py

@@ -0,0 +1,247 @@
+"""Handler for REST API calls to dynamically manage MCP servers."""
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from llama_stack_client import APIConnectionError
+
+from authentication import get_auth_dependency
+from authentication.interface import AuthTuple
+from authorization.middleware import authorize
+from client import AsyncLlamaStackClientHolder
+from configuration import configuration
+from models.config import Action, ModelContextProtocolServer
+from models.requests import MCPServerRegistrationRequest
+from models.responses import (
+    ConflictResponse,
+    ForbiddenResponse,
+    InternalServerErrorResponse,
+    MCPServerDeleteResponse,
+    MCPServerInfo,
+    MCPServerListResponse,
+    MCPServerRegistrationResponse,
+    NotFoundResponse,
+    ServiceUnavailableResponse,
+    UnauthorizedResponse,
+)
+from utils.endpoints import check_configuration_loaded
+from log import get_logger
+
+logger = get_logger(__name__)
+router = APIRouter(tags=["mcp-servers"])
+
+
+register_responses: dict[int | str, dict[str, Any]] = {
+    201: MCPServerRegistrationResponse.openapi_response(),
+    401: UnauthorizedResponse.openapi_response(
+        examples=["missing header", "missing token"]
+    ),
+    403: ForbiddenResponse.openapi_response(examples=["endpoint"]),
+    409: ConflictResponse.openapi_response(examples=["mcp server"]),
+    500: InternalServerErrorResponse.openapi_response(examples=["configuration"]),
+    503: ServiceUnavailableResponse.openapi_response(),
+}
+
+
+@router.post(
+    "/mcp-servers",
+    responses=register_responses,
+    status_code=status.HTTP_201_CREATED,
+)
+@authorize(Action.REGISTER_MCP_SERVER)
+async def register_mcp_server_handler(
+    request: Request,
+    body: MCPServerRegistrationRequest,
+    auth: Annotated[AuthTuple, Depends(get_auth_dependency())],
+) -> MCPServerRegistrationResponse:
+    """Register an MCP server dynamically at runtime.
+
+    Adds the MCP server to the runtime configuration and registers it
+    as a toolgroup with Llama Stack so it becomes available for queries.
+
+    Raises:
+        HTTPException: On duplicate name, Llama Stack connection error,
+            or registration failure.
+
+    Returns:
+        MCPServerRegistrationResponse: Details of the newly registered server.
+    """
+    _ = auth
+    _ = request
+
+    check_configuration_loaded(configuration)
+
+    mcp_server = ModelContextProtocolServer(
+        name=body.name,
+        url=body.url,
+        provider_id=body.provider_id,
+        authorization_headers=body.authorization_headers or {},
+        headers=body.headers or [],
+        timeout=body.timeout,
+    )
+
+    try:
+        configuration.add_mcp_server(mcp_server)
+    except ValueError as e:
+        response = ConflictResponse(resource="MCP server", resource_id=body.name)
+        raise HTTPException(**response.model_dump()) from e
+
+    try:
+        client = AsyncLlamaStackClientHolder().get_client()
+        await client.toolgroups.register(  # pyright: ignore[reportDeprecated]
+            toolgroup_id=mcp_server.name,
+            provider_id=mcp_server.provider_id,
+            mcp_endpoint={"uri": mcp_server.url},
+        )
+    except APIConnectionError as e:
+        configuration.remove_mcp_server(body.name)
+        logger.error("Failed to register MCP server with Llama Stack: %s", e)
+        response = ServiceUnavailableResponse(backend_name="Llama Stack", cause=str(e))
+        raise HTTPException(**response.model_dump()) from e
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        configuration.remove_mcp_server(body.name)
+        logger.error("Failed to register MCP toolgroup: %s", e)
+        error_response = InternalServerErrorResponse(
+            response="Failed to register MCP server",
+            cause=str(e),
+        )
+        raise HTTPException(**error_response.model_dump()) from e
+
+    logger.info("Dynamically registered MCP server: %s at %s", body.name, body.url)
+
+    return MCPServerRegistrationResponse(
+        name=mcp_server.name,
+        url=mcp_server.url,
+        provider_id=mcp_server.provider_id,
+        message=f"MCP server '{mcp_server.name}' registered successfully",
+    )
+
+
+list_responses: dict[int | str, dict[str, Any]] = {
+    200: MCPServerListResponse.openapi_response(),
+    401: UnauthorizedResponse.openapi_response(
+        examples=["missing header", "missing token"]
+    ),
+    403: ForbiddenResponse.openapi_response(examples=["endpoint"]),
+    500: InternalServerErrorResponse.openapi_response(examples=["configuration"]),
+}
+
+
+@router.get("/mcp-servers", responses=list_responses)
+@authorize(Action.LIST_MCP_SERVERS)
+async def list_mcp_servers_handler(
+    request: Request,
+    auth: Annotated[AuthTuple, Depends(get_auth_dependency())],
+) -> MCPServerListResponse:
+    """List all registered MCP servers.
+
+    Returns both statically configured (from YAML) and dynamically
+    registered (via API) MCP servers.
+
+    Raises:
+        HTTPException: If configuration is not loaded.
+
+    Returns:
+        MCPServerListResponse: List of all registered MCP servers with source info.
+    """
+    _ = auth
+    _ = request
+
+    check_configuration_loaded(configuration)
+
+    servers = []
+    for mcp in configuration.mcp_servers:
+        source = "api" if configuration.is_dynamic_mcp_server(mcp.name) else "config"
+        servers.append(
+            MCPServerInfo(
+                name=mcp.name,
+                url=mcp.url,
+                provider_id=mcp.provider_id,
+                source=source,
+            )
+        )
+
+    return MCPServerListResponse(servers=servers)
+
+
+delete_responses: dict[int | str, dict[str, Any]] = {
+    200: MCPServerDeleteResponse.openapi_response(),
+    401: UnauthorizedResponse.openapi_response(
+        examples=["missing header", "missing token"]
+    ),
+    403: ForbiddenResponse.openapi_response(examples=["endpoint"]),
+    404: NotFoundResponse.openapi_response(examples=["mcp server"]),
+    500: InternalServerErrorResponse.openapi_response(examples=["configuration"]),
+    503: ServiceUnavailableResponse.openapi_response(),
+}
+
+
+@router.delete("/mcp-servers/{name}", responses=delete_responses)
+@authorize(Action.DELETE_MCP_SERVER)
+async def delete_mcp_server_handler(
+    request: Request,
+    name: str,
+    auth: Annotated[AuthTuple, Depends(get_auth_dependency())],
+) -> MCPServerDeleteResponse:
+    """Unregister a dynamically registered MCP server.
+
+    Removes the MCP server from the runtime configuration and unregisters
+    its toolgroup from Llama Stack. Only servers registered via the API
+    can be deleted; statically configured servers cannot be removed.
+
+    Raises:
+        HTTPException: If the server is not found, is statically configured,
+            or Llama Stack unregistration fails.
+
+    Returns:
+        MCPServerDeleteResponse: Confirmation of the deletion.
+    """
+    _ = auth
+    _ = request
+
+    check_configuration_loaded(configuration)
+
+    if not configuration.is_dynamic_mcp_server(name):
+        found = any(s.name == name for s in configuration.mcp_servers)
+        if found:
+            response = ForbiddenResponse(
+                response="Cannot delete statically configured MCP server",
+                cause=f"MCP server '{name}' was configured in lightspeed-stack.yaml "
+                "and cannot be removed via the API.",
+            )
+        else:
+            response = NotFoundResponse(resource="MCP server", resource_id=name)
+        raise HTTPException(**response.model_dump())
+
+    try:
+        client = AsyncLlamaStackClientHolder().get_client()
+        await client.toolgroups.unregister(  # pyright: ignore[reportDeprecated]
+            toolgroup_id=name
+        )
+    except APIConnectionError as e:
+        logger.error("Failed to unregister MCP toolgroup from Llama Stack: %s", e)
+        svc_response = ServiceUnavailableResponse(
+            backend_name="Llama Stack", cause=str(e)
+        )
+        raise HTTPException(**svc_response.model_dump()) from e
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        logger.warning(
+            "Llama Stack toolgroup unregister failed for '%s', "
+            "proceeding with local removal: %s",
+            name,
+            e,
+        )
+
+    try:
+        configuration.remove_mcp_server(name)
+    except ValueError as e:
+        logger.error("Failed to remove MCP server from configuration: %s", e)
+        response = NotFoundResponse(resource="MCP server", resource_id=name)
+        raise HTTPException(**response.model_dump()) from e
+
+    logger.info("Dynamically unregistered MCP server: %s", name)
+
+    return MCPServerDeleteResponse(
+        name=name,
+        message=f"MCP server '{name}' unregistered successfully",
+    )

src/app/routers.py

@@ -20,6 +20,7 @@
     metrics,
     tools,
     mcp_auth,
+    mcp_servers,
     # Query endpoints for Response API support
     query,
     # RHEL Lightspeed rlsapi v1 compatibility
@@ -48,6 +49,7 @@ def include_routers(app: FastAPI) -> None:
     app.include_router(models.router, prefix="/v1")
     app.include_router(tools.router, prefix="/v1")
     app.include_router(mcp_auth.router, prefix="/v1")
+    app.include_router(mcp_servers.router, prefix="/v1")
     app.include_router(shields.router, prefix="/v1")
     app.include_router(providers.router, prefix="/v1")
     app.include_router(rags.router, prefix="/v1")

src/configuration.py

@@ -64,6 +64,7 @@ def __init__(self) -> None:
         self._conversation_cache: Optional[Cache] = None
         self._quota_limiters: list[QuotaLimiter] = []
         self._token_usage_history: Optional[TokenUsageHistory] = None
+        self._dynamic_mcp_server_names: set[str] = set()
 
     def load_configuration(self, filename: str) -> None:
         """Load configuration from YAML file.
@@ -165,6 +166,67 @@ def mcp_servers(self) -> list[ModelContextProtocolServer]:
             raise LogicError("logic error: configuration is not loaded")
         return self._configuration.mcp_servers
 
+    @property
+    def dynamic_mcp_server_names(self) -> set[str]:
+        """Return the set of dynamically registered MCP server names.
+
+        Returns:
+            set[str]: Names of MCP servers added via the API (not from config file).
+        """
+        return self._dynamic_mcp_server_names
+
+    def add_mcp_server(self, mcp_server: ModelContextProtocolServer) -> None:
+        """Add an MCP server to the runtime configuration.
+
+        Parameters:
+            mcp_server: The MCP server configuration to add.
+
+        Raises:
+            LogicError: If the configuration has not been loaded.
+            ValueError: If an MCP server with the same name already exists.
+        """
+        if self._configuration is None:
+            raise LogicError("logic error: configuration is not loaded")
+        for existing in self._configuration.mcp_servers:
+            if existing.name == mcp_server.name:
+                raise ValueError(
+                    f"MCP server with name '{mcp_server.name}' already exists"
+                )
+        self._configuration.mcp_servers.append(mcp_server)
+        self._dynamic_mcp_server_names.add(mcp_server.name)
+
+    def remove_mcp_server(self, name: str) -> None:
+        """Remove a dynamically registered MCP server from the runtime configuration.
+
+        Parameters:
+            name: The name of the MCP server to remove.
+
+        Raises:
+            LogicError: If the configuration has not been loaded.
+            ValueError: If the server was not found or was statically configured.
+        """
+        if self._configuration is None:
+            raise LogicError("logic error: configuration is not loaded")
+        if name not in self._dynamic_mcp_server_names:
+            raise ValueError(
+                f"MCP server '{name}' was not dynamically registered or does not exist"
+            )
+        self._configuration.mcp_servers = [
+            s for s in self._configuration.mcp_servers if s.name != name
+        ]
+        self._dynamic_mcp_server_names.discard(name)
+
+    def is_dynamic_mcp_server(self, name: str) -> bool:
+        """Check if an MCP server was dynamically registered.
+
+        Parameters:
+            name: The name of the MCP server.
+
+        Returns:
+            bool: True if the server was registered via the API.
+        """
+        return name in self._dynamic_mcp_server_names
+
     @property
     def authentication_configuration(self) -> AuthenticationConfiguration:
         """Return authentication configuration.

src/models/config.py

@@ -1019,6 +1019,11 @@ class Action(str, Enum):
     # RHEL Lightspeed rlsapi v1 compatibility - stateless inference (no history/RAG)
     RLSAPI_V1_INFER = "rlsapi_v1_infer"
 
+    # Dynamic MCP server management
+    REGISTER_MCP_SERVER = "register_mcp_server"
+    LIST_MCP_SERVERS = "list_mcp_servers"
+    DELETE_MCP_SERVER = "delete_mcp_server"
+
     # A2A (Agent-to-Agent) protocol actions
     A2A_AGENT_CARD = "a2a_agent_card"
     A2A_TASK_EXECUTION = "a2a_task_execution"