nvidia-nat-mcp 1.4.0a20260107__py3-none-any.whl

nat/plugins/mcp/exception_handler.py

@@ -0,0 +1,211 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import ssl
+import sys
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+import httpx
+
+from nat.plugins.mcp.exceptions import MCPAuthenticationError
+from nat.plugins.mcp.exceptions import MCPConnectionError
+from nat.plugins.mcp.exceptions import MCPError
+from nat.plugins.mcp.exceptions import MCPProtocolError
+from nat.plugins.mcp.exceptions import MCPRequestError
+from nat.plugins.mcp.exceptions import MCPSSLError
+from nat.plugins.mcp.exceptions import MCPTimeoutError
+from nat.plugins.mcp.exceptions import MCPToolNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+def format_mcp_error(error: MCPError, include_traceback: bool = False) -> None:
+    """Format MCP errors for CLI display with structured logging and user guidance.
+
+    Logs structured error information for debugging and displays user-friendly
+    error messages with actionable suggestions to stderr.
+
+    Args:
+        error (MCPError): MCPError instance containing message, url, category, suggestions, and original_exception
+        include_traceback (bool, optional): Whether to include the traceback in the error message. Defaults to False.
+    """
+    # Log structured error information for debugging
+    logger.error("MCP operation failed: %s", error, exc_info=include_traceback)
+
+    # Display user-friendly suggestions
+    for suggestion in error.suggestions:
+        print(f"  → {suggestion}", file=sys.stderr)
+
+
+def _extract_url(args: tuple, kwargs: dict[str, Any], url_param: str, func_name: str) -> str:
+    """Extract URL from function arguments using clean fallback chain.
+
+    Args:
+        args: Function positional arguments
+        kwargs: Function keyword arguments
+        url_param (str): Parameter name containing the URL
+        func_name (str): Function name for logging
+
+    Returns:
+        str: URL string or "unknown" if extraction fails
+    """
+    # Try keyword arguments first
+    if url_param in kwargs:
+        return kwargs[url_param]
+
+    # Try self attribute (e.g., self.url)
+    if args and hasattr(args[0], url_param):
+        return getattr(args[0], url_param)
+
+    # Try common case: url as second parameter after self
+    if len(args) > 1 and url_param == "url":
+        return args[1]
+
+    # Fallback with warning
+    logger.warning("Could not extract URL for error handling in %s", func_name)
+    return "unknown"
+
+
+def extract_primary_exception(exceptions: list[Exception]) -> Exception:
+    """Extract the most relevant exception from a group.
+
+    Prioritizes connection errors over others for better user experience.
+
+    Args:
+        exceptions (list[Exception]): List of exceptions from ExceptionGroup
+
+    Returns:
+        Exception: Most relevant exception for user feedback
+    """
+    # Prioritize connection errors
+    for exc in exceptions:
+        if isinstance(exc, httpx.ConnectError | ConnectionError):
+            return exc
+
+    # Then timeout errors
+    for exc in exceptions:
+        if isinstance(exc, httpx.TimeoutException):
+            return exc
+
+    # Then SSL errors
+    for exc in exceptions:
+        if isinstance(exc, ssl.SSLError):
+            return exc
+
+    # Fall back to first exception
+    return exceptions[0]
+
+
+def convert_to_mcp_error(exception: Exception, url: str) -> MCPError:
+    """Convert single exception to appropriate MCPError.
+
+    Args:
+        exception (Exception): Single exception to convert
+        url (str): MCP server URL for context
+
+    Returns:
+        MCPError: Appropriate MCPError subclass
+    """
+    match exception:
+        case httpx.ConnectError() | ConnectionError():
+            return MCPConnectionError(url, exception)
+        case httpx.TimeoutException():
+            return MCPTimeoutError(url, exception)
+        case ssl.SSLError():
+            return MCPSSLError(url, exception)
+        case httpx.RequestError():
+            return MCPRequestError(url, exception)
+        case ValueError() if "Tool" in str(exception) and "not available" in str(exception):
+            # Extract tool name from error message if possible
+            tool_name = str(exception).split("Tool ")[1].split(" not available")[0] if "Tool " in str(
+                exception) else "unknown"
+            return MCPToolNotFoundError(tool_name, url, exception)
+        case _:
+            # Handle TaskGroup error message specifically
+            if "unhandled errors in a TaskGroup" in str(exception):
+                return MCPProtocolError(url, "Failed to connect to MCP server", exception)
+            if "unauthorized" in str(exception).lower() or "forbidden" in str(exception).lower():
+                return MCPAuthenticationError(url, exception)
+            return MCPError(f"Unexpected error: {exception}", url, original_exception=exception)
+
+
+def handle_mcp_exceptions(url_param: str = "url") -> Callable[..., Any]:
+    """Decorator that handles exceptions and converts them to MCPErrors.
+
+    This decorator wraps MCP client methods and converts low-level exceptions
+    to structured MCPError instances with helpful user guidance.
+
+    Args:
+        url_param (str): Name of the parameter or attribute containing the MCP server URL
+
+    Returns:
+        Callable[..., Any]: Decorated function
+
+    Example:
+        .. code-block:: python
+
+            @handle_mcp_exceptions("url")
+            async def get_tools(self, url: str):
+                # Method implementation
+                pass
+
+            @handle_mcp_exceptions("url")  # Uses self.url
+            async def get_tool(self):
+                # Method implementation
+                pass
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await func(*args, **kwargs)
+            except MCPError:
+                # Re-raise MCPErrors as-is
+                raise
+            except Exception as e:
+                url = _extract_url(args, kwargs, url_param, func.__name__)
+
+                # Handle ExceptionGroup by extracting most relevant exception
+                if isinstance(e, ExceptionGroup):  # noqa: F821
+                    primary_exception = extract_primary_exception(list(e.exceptions))
+                    mcp_error = convert_to_mcp_error(primary_exception, url)
+                else:
+                    mcp_error = convert_to_mcp_error(e, url)
+
+                raise mcp_error from e
+
+        return wrapper
+
+    return decorator
+
+
+def mcp_exception_handler(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Simplified decorator for methods that have self.url attribute.
+
+    This is a convenience decorator that assumes the URL is available as self.url.
+    Follows the same pattern as schema_exception_handler in this directory.
+
+    Args:
+        func (Callable[..., Any]): The function to decorate
+
+    Returns:
+        Callable[..., Any]: Decorated function
+    """
+    return handle_mcp_exceptions("url")(func)

nat/plugins/mcp/exceptions.py

@@ -0,0 +1,142 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from enum import Enum
+
+
+class MCPErrorCategory(str, Enum):
+    """Categories of MCP errors for structured handling."""
+    CONNECTION = "connection"
+    TIMEOUT = "timeout"
+    SSL = "ssl"
+    AUTHENTICATION = "authentication"
+    TOOL_NOT_FOUND = "tool_not_found"
+    PROTOCOL = "protocol"
+    UNKNOWN = "unknown"
+
+
+class MCPError(Exception):
+    """Base exception for MCP-related errors."""
+
+    def __init__(self,
+                 message: str,
+                 url: str,
+                 category: MCPErrorCategory = MCPErrorCategory.UNKNOWN,
+                 suggestions: list[str] | None = None,
+                 original_exception: Exception | None = None):
+        super().__init__(message)
+        self.url = url
+        self.category = category
+        self.suggestions = suggestions or []
+        self.original_exception = original_exception
+
+
+class MCPConnectionError(MCPError):
+    """Exception for MCP connection failures."""
+
+    def __init__(self, url: str, original_exception: Exception | None = None):
+        super().__init__(f"Unable to connect to MCP server at {url}",
+                         url=url,
+                         category=MCPErrorCategory.CONNECTION,
+                         suggestions=[
+                             "Please ensure the MCP server is running and accessible",
+                             "Check if the URL and port are correct"
+                         ],
+                         original_exception=original_exception)
+
+
+class MCPTimeoutError(MCPError):
+    """Exception for MCP timeout errors."""
+
+    def __init__(self, url: str, original_exception: Exception | None = None):
+        super().__init__(f"Connection timed out to MCP server at {url}",
+                         url=url,
+                         category=MCPErrorCategory.TIMEOUT,
+                         suggestions=[
+                             "The server may be overloaded or network is slow",
+                             "Try again in a moment or check network connectivity"
+                         ],
+                         original_exception=original_exception)
+
+
+class MCPSSLError(MCPError):
+    """Exception for MCP SSL/TLS errors."""
+
+    def __init__(self, url: str, original_exception: Exception | None = None):
+        super().__init__(f"SSL/TLS error connecting to {url}",
+                         url=url,
+                         category=MCPErrorCategory.SSL,
+                         suggestions=[
+                             "Check if the server requires HTTPS or has valid certificates",
+                             "Try using HTTP instead of HTTPS if appropriate"
+                         ],
+                         original_exception=original_exception)
+
+
+class MCPRequestError(MCPError):
+    """Exception for MCP request errors."""
+
+    def __init__(self, url: str, original_exception: Exception | None = None):
+        message = f"Request failed to MCP server at {url}"
+        if original_exception:
+            message += f": {original_exception}"
+
+        super().__init__(message,
+                         url=url,
+                         category=MCPErrorCategory.PROTOCOL,
+                         suggestions=["Check the server URL format and network settings"],
+                         original_exception=original_exception)
+
+
+class MCPToolNotFoundError(MCPError):
+    """Exception for when a specific MCP tool is not found."""
+
+    def __init__(self, tool_name: str, url: str, original_exception: Exception | None = None):
+        super().__init__(f"Tool '{tool_name}' not available at {url}",
+                         url=url,
+                         category=MCPErrorCategory.TOOL_NOT_FOUND,
+                         suggestions=[
+                             "Use 'nat info mcp --detail' to see available tools",
+                             "Check that the tool name is spelled correctly"
+                         ],
+                         original_exception=original_exception)
+
+
+class MCPAuthenticationError(MCPError):
+    """Exception for MCP authentication failures."""
+
+    def __init__(self, url: str, original_exception: Exception | None = None):
+        super().__init__(f"Authentication failed when connecting to MCP server at {url}",
+                         url=url,
+                         category=MCPErrorCategory.AUTHENTICATION,
+                         suggestions=[
+                             "Check if the server requires authentication credentials",
+                             "Verify that your credentials are correct and not expired"
+                         ],
+                         original_exception=original_exception)
+
+
+class MCPProtocolError(MCPError):
+    """Exception for MCP protocol-related errors."""
+
+    def __init__(self, url: str, message: str = "Protocol error", original_exception: Exception | None = None):
+        super().__init__(f"{message} (MCP server at {url})",
+                         url=url,
+                         category=MCPErrorCategory.PROTOCOL,
+                         suggestions=[
+                             "Check that the MCP server is running and accessible at this URL",
+                             "Verify the server supports the expected MCP protocol version"
+                         ],
+                         original_exception=original_exception)

nat/plugins/mcp/register.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# flake8: noqa
+# isort:skip_file
+
+# Register client components
+from .client import client_impl
+
+# Register server/frontend components
+from .server import register_frontend

nat/plugins/mcp/server/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""MCP server/frontend components."""

nat/plugins/mcp/server/front_end_config.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+from typing import Literal
+
+from pydantic import Field
+from pydantic import field_validator
+from pydantic import model_validator
+
+from nat.authentication.oauth2.oauth2_resource_server_config import OAuth2ResourceServerConfig
+from nat.data_models.front_end import FrontEndBaseConfig
+
+logger = logging.getLogger(__name__)
+
+
+class MCPFrontEndConfig(FrontEndBaseConfig, name="mcp"):
+    """MCP front end configuration.
+
+    A simple MCP (Model Context Protocol) front end for NeMo Agent toolkit.
+    """
+
+    name: str = Field(default="NeMo Agent Toolkit MCP",
+                      description="Name of the MCP server (default: NeMo Agent Toolkit MCP)")
+    host: str = Field(default="localhost", description="Host to bind the server to (default: localhost)")
+    port: int = Field(default=9901, description="Port to bind the server to (default: 9901)", ge=0, le=65535)
+    debug: bool = Field(default=False, description="Enable debug mode (default: False)")
+    log_level: str = Field(default="INFO", description="Log level for the MCP server (default: INFO)")
+    tool_names: list[str] = Field(
+        default_factory=list,
+        description="The list of tools MCP server will expose (default: all tools)."
+        "Tool names can be functions or function groups",
+    )
+    transport: Literal["sse", "streamable-http"] = Field(
+        default="streamable-http",
+        description="Transport type for the MCP server (default: streamable-http, backwards compatible with sse)")
+    runner_class: str | None = Field(
+        default=None, description="Custom worker class for handling MCP routes (default: built-in worker)")
+    base_path: str | None = Field(default=None,
+                                  description="Base path to mount the MCP server at (e.g., '/api/v1'). "
+                                  "If specified, the server will be accessible at http://host:port{base_path}/mcp. "
+                                  "If None, server runs at root path /mcp.")
+
+    server_auth: OAuth2ResourceServerConfig | None = Field(
+        default=None, description=("OAuth 2.0 Resource Server configuration for token verification."))
+
+    @field_validator('base_path')
+    @classmethod
+    def validate_base_path(cls, v: str | None) -> str | None:
+        """Validate that base_path starts with '/' and doesn't end with '/'."""
+        if v is not None:
+            if not v.startswith('/'):
+                raise ValueError("base_path must start with '/'")
+            if v.endswith('/'):
+                raise ValueError("base_path must not end with '/'")
+        return v
+
+    # Memory profiling configuration
+    enable_memory_profiling: bool = Field(default=False,
+                                          description="Enable memory profiling and diagnostics (default: False)")
+    memory_profile_interval: int = Field(default=50,
+                                         description="Log memory stats every N requests (default: 50)",
+                                         ge=1)
+    memory_profile_top_n: int = Field(default=10,
+                                      description="Number of top memory allocations to log (default: 10)",
+                                      ge=1,
+                                      le=50)
+    memory_profile_log_level: str = Field(default="DEBUG",
+                                          description="Log level for memory profiling output (default: DEBUG)")
+
+    @model_validator(mode="after")
+    def validate_security_configuration(self):
+        """Validate security configuration to prevent accidental misconfigurations."""
+        # Check if server is bound to a non-localhost interface without authentication
+        localhost_hosts = {"localhost", "127.0.0.1", "::1"}
+        if self.host not in localhost_hosts and self.server_auth is None:
+            logger.warning(
+                "MCP server is configured to bind to '%s' without authentication. "
+                "This may expose your server to unauthorized access. "
+                "Consider either: (1) binding to localhost for local-only access, "
+                "or (2) configuring server_auth for production deployments on public interfaces.",
+                self.host)
+
+        # Check if SSE transport is used (which doesn't support authentication)
+        if self.transport == "sse":
+            if self.server_auth is not None:
+                logger.warning("SSE transport does not support authentication. "
+                               "The configured server_auth will be ignored. "
+                               "For production use with authentication, use 'streamable-http' transport instead.")
+            elif self.host not in localhost_hosts:
+                logger.warning(
+                    "SSE transport does not support authentication and is bound to '%s'. "
+                    "This configuration is not recommended for production use. "
+                    "For production deployments, use 'streamable-http' transport with server_auth configured.",
+                    self.host)
+
+        return self

nat/plugins/mcp/server/front_end_plugin.py

@@ -0,0 +1,155 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import typing
+
+from nat.builder.front_end import FrontEndBase
+from nat.builder.workflow_builder import WorkflowBuilder
+from nat.plugins.mcp.server.front_end_config import MCPFrontEndConfig
+from nat.plugins.mcp.server.front_end_plugin_worker import MCPFrontEndPluginWorkerBase
+
+if typing.TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+
+class MCPFrontEndPlugin(FrontEndBase[MCPFrontEndConfig]):
+    """MCP front end plugin implementation."""
+
+    def get_worker_class(self) -> type[MCPFrontEndPluginWorkerBase]:
+        """Get the worker class for handling MCP routes."""
+        from nat.plugins.mcp.server.front_end_plugin_worker import MCPFrontEndPluginWorker
+
+        return MCPFrontEndPluginWorker
+
+    @typing.final
+    def get_worker_class_name(self) -> str:
+        """Get the worker class name from configuration or default."""
+        if self.front_end_config.runner_class:
+            return self.front_end_config.runner_class
+
+        worker_class = self.get_worker_class()
+        return f"{worker_class.__module__}.{worker_class.__qualname__}"
+
+    def _get_worker_instance(self):
+        """Get an instance of the worker class."""
+        # Import the worker class dynamically if specified in config
+        if self.front_end_config.runner_class:
+            module_name, class_name = self.front_end_config.runner_class.rsplit(".", 1)
+            import importlib
+            module = importlib.import_module(module_name)
+            worker_class = getattr(module, class_name)
+        else:
+            worker_class = self.get_worker_class()
+
+        return worker_class(self.full_config)
+
+    async def run(self) -> None:
+        """Run the MCP server."""
+        # Build the workflow and add routes using the worker
+        async with WorkflowBuilder.from_config(config=self.full_config) as builder:
+
+            # Get the worker instance
+            worker = self._get_worker_instance()
+
+            # Let the worker create the MCP server (allows plugins to customize)
+            mcp = await worker.create_mcp_server()
+
+            # Add routes through the worker (includes health endpoint and function registration)
+            await worker.add_routes(mcp, builder)
+
+            # Start the MCP server with configurable transport
+            # streamable-http is the default, but users can choose sse if preferred
+            try:
+                # If base_path is configured, mount server at sub-path using FastAPI wrapper
+                if self.front_end_config.base_path:
+                    if self.front_end_config.transport == "sse":
+                        logger.warning(
+                            "base_path is configured but SSE transport does not support mounting at sub-paths. "
+                            "Use streamable-http transport for base_path support.")
+                        logger.info("Starting MCP server with SSE endpoint at /sse")
+                        await mcp.run_sse_async()
+                    else:
+                        full_url = f"http://{self.front_end_config.host}:{self.front_end_config.port}{self.front_end_config.base_path}/mcp"
+                        logger.info(
+                            "Mounting MCP server at %s/mcp on %s:%s",
+                            self.front_end_config.base_path,
+                            self.front_end_config.host,
+                            self.front_end_config.port,
+                        )
+                        logger.info("MCP server URL: %s", full_url)
+                        await self._run_with_mount(mcp)
+                # Standard behavior - run at root path
+                elif self.front_end_config.transport == "sse":
+                    logger.info("Starting MCP server with SSE endpoint at /sse")
+                    await mcp.run_sse_async()
+                else:  # streamable-http
+                    full_url = f"http://{self.front_end_config.host}:{self.front_end_config.port}/mcp"
+                    logger.info("MCP server URL: %s", full_url)
+                    await mcp.run_streamable_http_async()
+            except KeyboardInterrupt:
+                logger.info("MCP server shutdown requested (Ctrl+C). Shutting down gracefully.")
+
+    async def _run_with_mount(self, mcp: "FastMCP") -> None:
+        """Run MCP server mounted at configured base_path using FastAPI wrapper.
+
+        Args:
+            mcp: The FastMCP server instance to mount
+        """
+        import contextlib
+
+        import uvicorn
+        from fastapi import FastAPI
+
+        @contextlib.asynccontextmanager
+        async def lifespan(_app: FastAPI):
+            """Manage MCP server session lifecycle."""
+            logger.info("Starting MCP server session manager...")
+            async with contextlib.AsyncExitStack() as stack:
+                try:
+                    # Initialize the MCP server's session manager
+                    await stack.enter_async_context(mcp.session_manager.run())
+                    logger.info("MCP server session manager started successfully")
+                    yield
+                except Exception as e:
+                    logger.error("Failed to start MCP server session manager: %s", e)
+                    raise
+            logger.info("MCP server session manager stopped")
+
+        # Create a FastAPI wrapper app with lifespan management
+        app = FastAPI(
+            title=self.front_end_config.name,
+            description="MCP server mounted at custom base path",
+            lifespan=lifespan,
+        )
+
+        # Mount the MCP server's ASGI app at the configured base_path
+        app.mount(self.front_end_config.base_path, mcp.streamable_http_app())
+
+        # Allow plugins to add routes to the wrapper app (e.g., OAuth discovery endpoints)
+        worker = self._get_worker_instance()
+        await worker.add_root_level_routes(app, mcp)
+
+        # Configure and start uvicorn server
+        config = uvicorn.Config(
+            app,
+            host=self.front_end_config.host,
+            port=self.front_end_config.port,
+            log_level=self.front_end_config.log_level.lower(),
+        )
+        server = uvicorn.Server(config)
+        await server.serve()