Merge pull request #103 from IBM/fix-basic-auth-gateways

Fix uv sync and return 502 status when gateway addition fails

Author: crivetimihai

README.md

@@ -177,6 +177,8 @@ pkill mcpgateway
 export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
 export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1
 python3 -m mcpgateway.wrapper
+# Alternatively with uv
+uv run --directory . -m mcpgateway.wrapper
 ```
 
 See [.env.example](.env.example) for full list of ENV variables you can use to override the configuration.
@@ -243,6 +245,8 @@ export MCP_WRAPPER_LOG_LEVEL=DEBUG  # or OFF to disable logging
 
 # Run the wrapper from the installed module
 python3 -m mcpgateway.wrapper
+# Alternatively with uv
+uv run --directory . -m mcpgateway.wrapper
 ```
 
 **Or using the container image:**
@@ -270,6 +274,8 @@ npx -y supergateway --stdio "uvenv run mcp_server_time -- --local-timezone=Europ
 export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
 export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1
 python3 -m mcpgateway.wrapper
+# Alternatively with uv
+uv run --directory . -m mcpgateway.wrapper
 ```
 
 <details>
@@ -352,6 +358,8 @@ pipx install --include-deps mcp-contextforge-gateway
 MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
 MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1 \
 python3 -m mcpgateway.wrapper
+# Alternatively with uv
+uv run --directory . -m mcpgateway.wrapper
 ```
 
 **Claude Desktop JSON** (uses the host Python that pipx injected):
@@ -402,11 +410,9 @@ uv pip install mcp-contextforge-gateway
 # Launch wrapper
 MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
 MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1 \
-uv python -m mcpgateway.wrapper # Use this just for testing, as the Client will run the uv command
+uv run --directory . -m mcpgateway.wrapper # Use this just for testing, as the Client will run the uv command
 ```
 
-*(You can swap `uv python` for plain `python` if the venv is active.)*
-
 #### Claude Desktop JSON (runs through **uvenv run**)
 
 ```json

docs/docs/using/clients/cline.md

@@ -34,22 +34,31 @@ To integrate Cline with your MCP Gateway:
 1. **Configure MCP Server**:
    - Open the Cline settings in VS Code.
    - Navigate to the MCP Servers section.
-   - Add a new MCP server with the following configuration:
+   - Add a new MCP server with the following configuration under mcpServers as shown below:
 
      ```json
-     {
-       "name": "MCP Gateway",
-       "url": "http://localhost:4444",
-       "auth": {
-         "type": "basic",
-         "username": "admin",
-         "password": "changeme"
-       }
-     }
+     "mcpServers": {
+         "mcpgateway-wrapper": {
+            "disabled": true,
+            "timeout": 60,
+            "type": "stdio",
+            "command": "uv",
+            "args": [
+            "run",
+            "--directory",
+            "REPLACE_WITH_PATH_TO_REPO",
+            "-m",
+            "mcpgateway.wrapper"
+            ],
+            "env": {
+               "MCP_SERVER_CATALOG_URLS": "http://localhost:4444",
+               "MCP_AUTH_TOKEN": "REPLACE_WITH_MCPGATEWAY_BEARER_TOKEN",
+               "MCP_WRAPPER_LOG_LEVEL": "OFF"
+            }
+         }
+      }
      ```
 
-   - Replace the URL, username, and password with your MCP Gateway's details.
-
 2. **Enable the MCP Server**:
    - Ensure the newly added MCP server is enabled in the Cline settings.
 

mcpgateway/admin.py

@@ -48,7 +48,7 @@
     ToolRead,
     ToolUpdate,
 )
-from mcpgateway.services.gateway_service import GatewayService
+from mcpgateway.services.gateway_service import GatewayConnectionError, GatewayService
 from mcpgateway.services.prompt_service import PromptService
 from mcpgateway.services.resource_service import ResourceService
 from mcpgateway.services.root_service import RootService
@@ -762,10 +762,19 @@ async def admin_add_gateway(request: Request, db: Session = Depends(get_db), use
         auth_header_key=form.get("auth_header_key", ""),
         auth_header_value=form.get("auth_header_value", ""),
     )
-    await gateway_service.register_gateway(db, gateway)
-
     root_path = request.scope.get("root_path", "")
-    return RedirectResponse(f"{root_path}/admin#gateways", status_code=303)
+    try:
+        await gateway_service.register_gateway(db, gateway)
+        return RedirectResponse(f"{root_path}/admin#gateways", status_code=303)
+    except Exception as ex:
+        if isinstance(ex, GatewayConnectionError):
+            return RedirectResponse(f"{root_path}/admin#gateways", status_code=502)
+        elif isinstance(ex, ValueError):
+            return RedirectResponse(f"{root_path}/admin#gateways", status_code=400)
+        elif isinstance(ex, RuntimeError):
+            return RedirectResponse(f"{root_path}/admin#gateways", status_code=500)
+        else:
+            return RedirectResponse(f"{root_path}/admin#gateways", status_code=500)
 
 
 @admin_router.post("/gateways/{gateway_id}/edit")

mcpgateway/main.py

@@ -28,7 +28,6 @@
 import asyncio
 import json
 import logging
-import os
 from contextlib import asynccontextmanager
 from typing import Any, AsyncIterator, Dict, List, Optional, Union
 
@@ -78,7 +77,7 @@
     ToolUpdate,
 )
 from mcpgateway.services.completion_service import CompletionService
-from mcpgateway.services.gateway_service import GatewayService
+from mcpgateway.services.gateway_service import GatewayConnectionError, GatewayService
 from mcpgateway.services.logging_service import LoggingService
 from mcpgateway.services.prompt_service import (
     PromptError,
@@ -1506,7 +1505,17 @@ async def register_gateway(
         Created gateway.
     """
     logger.debug(f"User '{user}' requested to register gateway: {gateway}")
-    return await gateway_service.register_gateway(db, gateway)
+    try:
+        return await gateway_service.register_gateway(db, gateway)
+    except Exception as ex:
+        if isinstance(ex, GatewayConnectionError):
+            return JSONResponse(content={"message": "Unable to connect to gateway"}, status_code=502)
+        elif isinstance(ex, ValueError):
+            return JSONResponse(content={"message": "Unable to process input"}, status_code=400)
+        elif isinstance(ex, RuntimeError):
+            return JSONResponse(content={"message": "Error during execution"}, status_code=500)
+        else:
+            return JSONResponse(content={"message": "Unexpected error"}, status_code=500)
 
 
 @gateway_router.get("/{gateway_id}", response_model=GatewayRead)

mcpgateway/services/gateway_service.py

@@ -123,7 +123,11 @@ def __init__(self):
             self._redis_client = None
 
     async def initialize(self) -> None:
-        """Initialize the service and start health check if this instance is the leader."""
+        """Initialize the service and start health check if this instance is the leader.
+
+        Raises:
+            ConnectionError: When redis ping fails
+        """
         logger.info("Initializing gateway service")
 
         if self._redis_client:
@@ -166,6 +170,7 @@ async def register_gateway(self, db: Session, gateway: GatewayCreate) -> Gateway
 
         Raises:
             GatewayNameConflictError: If gateway name already exists
+            []: When ExceptionGroup found
         """
         try:
             # Check for name conflicts (both active and inactive)
@@ -232,19 +237,18 @@ async def register_gateway(self, db: Session, gateway: GatewayCreate) -> Gateway
             await self._notify_gateway_added(db_gateway)
 
             return GatewayRead.model_validate(gateway)
+        except* GatewayConnectionError as ge:
+            logger.error("GatewayConnectionError in group: %s", ge.exceptions)
+            raise ge.exceptions[0]
         except* ValueError as ve:
             logger.error("ValueErrors in group: %s", ve.exceptions)
+            raise ve.exceptions[0]
         except* RuntimeError as re:
             logger.error("RuntimeErrors in group: %s", re.exceptions)
+            raise re.exceptions[0]
         except* BaseException as other:  # catches every other sub-exception
             logger.error("Other grouped errors: %s", other.exceptions)
-        # except IntegrityError as ex:
-        #     logger.error(f"Error adding gateway: {ex}")
-        #     db.rollback()
-        #     raise GatewayError(f"Gateway already exists: {gateway.name}")
-        # except Exception as e:
-        #     db.rollback()
-        #     raise GatewayError(f"Failed to register gateway: {str(e)}")
+            raise other.exceptions[0]
 
     async def list_gateways(self, db: Session, include_inactive: bool = False) -> List[GatewayRead]:
         """List all registered gateways.

mcpgateway/wrapper.py

@@ -73,32 +73,52 @@
 # Base URL Extraction
 # -----------------------------------------------------------------------------
 def _extract_base_url(url: str) -> str:
-    """
-    Extract the base URL (scheme and network location) from a full URL.
+    """Return the gateway-level base URL.
+
+    The function keeps any application root path (`APP_ROOT_PATH`) that the
+    remote gateway is mounted under (for example `/gateway`) while removing
+    the `/servers/<id>` suffix that appears in catalog endpoints. It also
+    discards any query string or fragment.
 
     Args:
-        url (str): The full URL to parse, e.g., "https://example.com/path?query=1".
+        url (str): Full catalog URL, e.g.
+            `https://host.com/gateway/servers/1`.
 
     Returns:
-        str: The base URL, including scheme and netloc, e.g., "https://example.com".
+        str: Clean base URL suitable for building `/tools/`, `/prompts/`,
+        or `/resources/` endpoints—for example
+        `https://host.com/gateway`.
 
     Raises:
-        ValueError: If the URL does not contain a scheme or netloc.
-
-    Example:
-        >>> _extract_base_url("https://www.example.com/path/to/resource")
-        'https://www.example.com'
+        ValueError: If *url* lacks a scheme or network location.
+
+    Examples:
+        >>> _extract_base_url("https://host.com/servers/2")
+        'https://host.com'
+        >>> _extract_base_url("https://host.com/gateway/servers/2")
+        'https://host.com/gateway'
+        >>> _extract_base_url("https://host.com/gateway/servers")
+        'https://host.com/gateway'
+        >>> _extract_base_url("https://host.com/gateway")
+        'https://host.com/gateway'
+
+    Note:
+        If the target server was started with `APP_ROOT_PATH=/gateway`, the
+        resulting catalog URLs include that prefix.  This helper preserves the
+        prefix so the wrapper's follow-up calls remain correctly scoped.
     """
     parsed = urlparse(url)
     if not parsed.scheme or not parsed.netloc:
         raise ValueError(f"Invalid URL provided: {url}")
 
-    if "/servers/" in url:
-        before_servers = parsed.path.split("/servers")[0]
-        return f"{parsed.scheme}://{parsed.netloc}{before_servers}"
-
-    return f"{url}"
+    path = parsed.path or ""
+    if "/servers/" in path:
+        path = path.split("/servers")[0]           # ".../servers/123" -> "..."
+    elif path.endswith("/servers"):
+        path = path[:-len("/servers")]             # ".../servers"     -> "..."
+    # otherwise keep the existing path (supports APP_ROOT_PATH)
 
+    return f"{parsed.scheme}://{parsed.netloc}{path}"
 
 BASE_URL: str = _extract_base_url(SERVER_CATALOG_URLS[0]) if SERVER_CATALOG_URLS else ""
 
@@ -162,10 +182,6 @@ async def get_tools_from_mcp_server(catalog_urls: List[str]) -> List[str]:
 
     Returns:
         List[str]: A list of tool ID strings extracted from the server catalog.
-
-    Raises:
-        httpx.RequestError: If a network problem occurs.
-        httpx.HTTPStatusError: If the server returns a 4xx or 5xx response.
     """
     server_ids = [url.split("/")[-1] for url in catalog_urls]
     url = f"{BASE_URL}/servers/"
@@ -187,10 +203,6 @@ async def tools_metadata(tool_ids: List[str]) -> List[Dict[str, Any]]:
 
     Returns:
         List[Dict[str, Any]]: A list of metadata dictionaries for each tool.
-
-    Raises:
-        httpx.RequestError: If a network problem occurs.
-        httpx.HTTPStatusError: If the server returns a 4xx or 5xx response.
     """
     if not tool_ids:
         return []
@@ -212,10 +224,6 @@ async def get_prompts_from_mcp_server(catalog_urls: List[str]) -> List[str]:
 
     Returns:
         List[str]: A list of prompt ID strings.
-
-    Raises:
-        httpx.RequestError: If a network problem occurs.
-        httpx.HTTPStatusError: If the server returns a 4xx or 5xx response.
     """
     server_ids = [url.split("/")[-1] for url in catalog_urls]
     url = f"{BASE_URL}/servers/"
@@ -237,10 +245,6 @@ async def prompts_metadata(prompt_ids: List[str]) -> List[Dict[str, Any]]:
 
     Returns:
         List[Dict[str, Any]]: A list of metadata dictionaries for each prompt.
-
-    Raises:
-        httpx.RequestError: If a network problem occurs.
-        httpx.HTTPStatusError: If the server returns a 4xx or 5xx response.
     """
     if not prompt_ids:
         return []
@@ -261,10 +265,6 @@ async def get_resources_from_mcp_server(catalog_urls: List[str]) -> List[str]:
 
     Returns:
         List[str]: A list of resource ID strings.
-
-    Raises:
-        httpx.RequestError: If a network problem occurs.
-        httpx.HTTPStatusError: If the server returns a 4xx or 5xx response.
     """
     server_ids = [url.split("/")[-1] for url in catalog_urls]
     url = f"{BASE_URL}/servers/"
@@ -286,10 +286,6 @@ async def resources_metadata(resource_ids: List[str]) -> List[Dict[str, Any]]:
 
     Returns:
         List[Dict[str, Any]]: A list of metadata dictionaries for each resource.
-
-    Raises:
-        httpx.RequestError: If a network problem occurs.
-        httpx.HTTPStatusError: If the server returns a 4xx or 5xx response.
     """
     if not resource_ids:
         return []