nvidia-nat-mcp 1.3.0a20250909__py3-none-any.whl

nat/meta/pypi.md

@@ -0,0 +1,32 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2025, 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.
+-->
+
+![NVIDIA NeMo Agent Toolkit](https://media.githubusercontent.com/media/NVIDIA/NeMo-Agent-Toolkit/refs/heads/main/docs/source/_static/banner.png "NeMo Agent toolkit banner image")
+
+
+# NVIDIA NeMo Agent Toolkit MCP Subpackage
+Subpackage for MCP client integration in NeMo Agent toolkit.
+
+This package provides MCP (Model Context Protocol) client functionality, allowing NeMo Agent toolkit workflows to connect to external MCP servers and use their tools as functions.
+
+## Features
+
+- Connect to MCP servers via streamable-http, SSE, or stdio transports
+- Wrap individual MCP tools as NeMo Agent toolkit functions
+- Connect to MCP servers and dynamically discover available tools
+
+For more information about the NVIDIA NeMo Agent toolkit, please visit the [NeMo Agent toolkit GitHub Repo](https://github.com/NVIDIA/NeMo-Agent-Toolkit).

nat/plugins/mcp/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, 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.

nat/plugins/mcp/client_base.py

@@ -0,0 +1,406 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, 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 __future__ import annotations
+
+import logging
+from abc import ABC
+from abc import abstractmethod
+from contextlib import AsyncExitStack
+from contextlib import asynccontextmanager
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import Field
+from pydantic import create_model
+
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from mcp.client.stdio import StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.types import TextContent
+from nat.plugins.mcp.exception_handler import mcp_exception_handler
+from nat.plugins.mcp.exceptions import MCPToolNotFoundError
+from nat.utils.type_utils import override
+
+logger = logging.getLogger(__name__)
+
+
+def model_from_mcp_schema(name: str, mcp_input_schema: dict) -> type[BaseModel]:
+    """
+    Create a pydantic model from the input schema of the MCP tool
+    """
+    _type_map = {
+        "string": str,
+        "number": float,
+        "integer": int,
+        "boolean": bool,
+        "array": list,
+        "null": None,
+        "object": dict,
+    }
+
+    properties = mcp_input_schema.get("properties", {})
+    required_fields = set(mcp_input_schema.get("required", []))
+    schema_dict = {}
+
+    def _generate_valid_classname(class_name: str):
+        return class_name.replace('_', ' ').replace('-', ' ').title().replace(' ', '')
+
+    def _generate_field(field_name: str, field_properties: dict[str, Any]) -> tuple:
+        json_type = field_properties.get("type", "string")
+        enum_vals = field_properties.get("enum")
+
+        if enum_vals:
+            enum_name = f"{field_name.capitalize()}Enum"
+            field_type = Enum(enum_name, {item: item for item in enum_vals})
+
+        elif json_type == "object" and "properties" in field_properties:
+            field_type = model_from_mcp_schema(name=field_name, mcp_input_schema=field_properties)
+        elif json_type == "array" and "items" in field_properties:
+            item_properties = field_properties.get("items", {})
+            if item_properties.get("type") == "object":
+                item_type = model_from_mcp_schema(name=field_name, mcp_input_schema=item_properties)
+            else:
+                item_type = _type_map.get(item_properties.get("type", "string"), Any)
+            field_type = list[item_type]
+        elif isinstance(json_type, list):
+            field_type = None
+            for t in json_type:
+                mapped = _type_map.get(t, Any)
+                field_type = mapped if field_type is None else field_type | mapped
+
+            return field_type, Field(
+                default=field_properties.get("default", None if "null" in json_type else ...),
+                description=field_properties.get("description", "")
+            )
+        else:
+            field_type = _type_map.get(json_type, Any)
+
+        # Determine the default value based on whether the field is required
+        if field_name in required_fields:
+            # Field is required - use explicit default if provided, otherwise make it required
+            default_value = field_properties.get("default", ...)
+        else:
+            # Field is optional - use explicit default if provided, otherwise None
+            default_value = field_properties.get("default", None)
+            # Make the type optional if no default was provided
+            if "default" not in field_properties:
+                field_type = field_type | None
+
+        nullable = field_properties.get("nullable", False)
+        description = field_properties.get("description", "")
+
+        field_type = field_type | None if nullable else field_type
+
+        return field_type, Field(default=default_value, description=description)
+
+    for field_name, field_props in properties.items():
+        schema_dict[field_name] = _generate_field(field_name=field_name, field_properties=field_props)
+    return create_model(f"{_generate_valid_classname(name)}InputSchema", **schema_dict)
+
+
+class MCPBaseClient(ABC):
+    """
+    Base client for creating a session and connecting to an MCP server
+
+    Args:
+        transport (str): The type of client to use ('sse', 'stdio', or 'streamable-http')
+    """
+
+    def __init__(self, transport: str = 'streamable-http'):
+        self._tools = None
+        self._transport = transport.lower()
+        if self._transport not in ['sse', 'stdio', 'streamable-http']:
+            raise ValueError("transport must be either 'sse', 'stdio' or 'streamable-http'")
+
+        self._exit_stack: AsyncExitStack | None = None
+
+        self._session: ClientSession | None = None
+
+    @property
+    def transport(self) -> str:
+        return self._transport
+
+    async def __aenter__(self):
+        if self._exit_stack:
+            raise RuntimeError("MCPBaseClient already initialized. Use async with to initialize.")
+
+        self._exit_stack = AsyncExitStack()
+
+        self._session = await self._exit_stack.enter_async_context(self.connect_to_server())
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+
+        if not self._exit_stack:
+            raise RuntimeError("MCPBaseClient not initialized. Use async with to initialize.")
+
+        await self._exit_stack.aclose()
+        self._session = None
+        self._exit_stack = None
+
+    @property
+    def server_name(self):
+        """
+        Provide server name for logging
+        """
+        return self._transport
+
+    @abstractmethod
+    @asynccontextmanager
+    async def connect_to_server(self):
+        """
+        Establish a session with an MCP server within an async context
+        """
+        pass
+
+    async def get_tools(self):
+        """
+        Retrieve a dictionary of all tools served by the MCP server.
+        """
+
+        if not self._session:
+            raise RuntimeError("MCPBaseClient not initialized. Use async with to initialize.")
+
+        response = await self._session.list_tools()
+
+        return {
+            tool.name:
+                MCPToolClient(session=self._session,
+                              tool_name=tool.name,
+                              tool_description=tool.description,
+                              tool_input_schema=tool.inputSchema)
+            for tool in response.tools
+        }
+
+    @mcp_exception_handler
+    async def get_tool(self, tool_name: str) -> MCPToolClient:
+        """
+        Get an MCP Tool by name.
+
+        Args:
+            tool_name (str): Name of the tool to load.
+
+        Returns:
+            MCPToolClient for the configured tool.
+
+        Raises:
+            MCPToolNotFoundError: If no tool is available with that name.
+        """
+        if not self._exit_stack:
+            raise RuntimeError("MCPBaseClient not initialized. Use async with to initialize.")
+
+        if not self._tools:
+            self._tools = await self.get_tools()
+
+        tool = self._tools.get(tool_name)
+        if not tool:
+            raise MCPToolNotFoundError(tool_name, self.server_name)
+        return tool
+
+    @mcp_exception_handler
+    async def call_tool(self, tool_name: str, tool_args: dict | None):
+        if not self._session:
+            raise RuntimeError("MCPBaseClient not initialized. Use async with to initialize.")
+
+        result = await self._session.call_tool(tool_name, tool_args)
+        return result
+
+
+class MCPSSEClient(MCPBaseClient):
+    """
+    Client for creating a session and connecting to an MCP server using SSE
+
+    Args:
+      url (str): The url of the MCP server
+    """
+
+    def __init__(self, url: str):
+        super().__init__("sse")
+        self._url = url
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def server_name(self):
+        return f"sse:{self._url}"
+
+    @asynccontextmanager
+    @override
+    async def connect_to_server(self):
+        """
+        Establish a session with an MCP SSE server within an async context
+        """
+        async with sse_client(url=self._url) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                yield session
+
+
+class MCPStdioClient(MCPBaseClient):
+    """
+    Client for creating a session and connecting to an MCP server using stdio
+
+    Args:
+      command (str): The command to run
+      args (list[str] | None): Additional arguments for the command
+      env (dict[str, str] | None): Environment variables to set for the process
+    """
+
+    def __init__(self, command: str, args: list[str] | None = None, env: dict[str, str] | None = None):
+        super().__init__("stdio")
+        self._command = command
+        self._args = args
+        self._env = env
+
+    @property
+    def command(self) -> str:
+        return self._command
+
+    @property
+    def server_name(self):
+        return f"stdio:{self._command}"
+
+    @property
+    def args(self) -> list[str] | None:
+        return self._args
+
+    @property
+    def env(self) -> dict[str, str] | None:
+        return self._env
+
+    @asynccontextmanager
+    @override
+    async def connect_to_server(self):
+        """
+        Establish a session with an MCP server via stdio within an async context
+        """
+
+        server_params = StdioServerParameters(command=self._command, args=self._args or [], env=self._env)
+        async with stdio_client(server_params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                yield session
+
+
+class MCPStreamableHTTPClient(MCPBaseClient):
+    """
+    Client for creating a session and connecting to an MCP server using streamable-http
+
+    Args:
+      url (str): The url of the MCP server
+    """
+
+    def __init__(self, url: str):
+        super().__init__("streamable-http")
+
+        self._url = url
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def server_name(self):
+        return f"streamable-http:{self._url}"
+
+    @asynccontextmanager
+    async def connect_to_server(self):
+        """
+        Establish a session with an MCP server via streamable-http within an async context
+        """
+        async with streamablehttp_client(url=self._url) as (read, write, get_session_id):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                yield session
+
+
+class MCPToolClient:
+    """
+    Client wrapper used to call an MCP tool.
+
+    Args:
+        connect_fn (callable): Function that returns an async context manager for connecting to the server
+        tool_name (str): The name of the tool to wrap
+        tool_description (str): The description of the tool provided by the MCP server.
+        tool_input_schema (dict): The input schema for the tool.
+    """
+
+    def __init__(self,
+                 session: ClientSession,
+                 tool_name: str,
+                 tool_description: str | None,
+                 tool_input_schema: dict | None = None):
+        self._session = session
+        self._tool_name = tool_name
+        self._tool_description = tool_description
+        self._input_schema = (model_from_mcp_schema(self._tool_name, tool_input_schema) if tool_input_schema else None)
+
+    @property
+    def name(self):
+        """Returns the name of the tool."""
+        return self._tool_name
+
+    @property
+    def description(self):
+        """
+        Returns the tool's description. If none was provided. Provides a simple description using the tool's name
+        """
+        if not self._tool_description:
+            return f"MCP Tool {self._tool_name}"
+        return self._tool_description
+
+    @property
+    def input_schema(self):
+        """
+        Returns the tool's input_schema.
+        """
+        return self._input_schema
+
+    def set_description(self, description: str):
+        """
+        Manually define the tool's description using the provided string.
+        """
+        self._tool_description = description
+
+    async def acall(self, tool_args: dict) -> str:
+        """
+        Call the MCP tool with the provided arguments.
+
+        Args:
+            tool_args (dict[str, Any]): A dictionary of key value pairs to serve as inputs for the MCP tool.
+        """
+        result = await self._session.call_tool(self._tool_name, tool_args)
+
+        output = []
+
+        for res in result.content:
+            if isinstance(res, TextContent):
+                output.append(res.text)
+            else:
+                # Log non-text content for now
+                logger.warning("Got not-text output from %s of type %s", self.name, type(res))
+        result_str = "\n".join(output)
+
+        if result.isError:
+            raise RuntimeError(result_str)
+
+        return result_str

nat/plugins/mcp/client_impl.py

@@ -0,0 +1,229 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, 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 BaseModel
+from pydantic import Field
+from pydantic import HttpUrl
+from pydantic import model_validator
+
+from nat.builder.builder import Builder
+from nat.builder.function_info import FunctionInfo
+from nat.cli.register_workflow import register_function
+from nat.data_models.function import FunctionBaseConfig
+from nat.experimental.decorators.experimental_warning_decorator import experimental
+from nat.plugins.mcp.client_base import MCPBaseClient
+
+logger = logging.getLogger(__name__)
+
+
+class MCPToolOverrideConfig(BaseModel):
+    """
+    Configuration for overriding tool properties when exposing from MCP server.
+    """
+    alias: str | None = Field(default=None, description="Override the tool name (function name in the workflow)")
+    description: str | None = Field(default=None, description="Override the tool description")
+
+
+class MCPServerConfig(BaseModel):
+    """
+    Server connection details for MCP client.
+    Supports stdio, sse, and streamable-http transports.
+    streamable-http is the recommended default for HTTP-based connections.
+    """
+    transport: Literal["stdio", "sse", "streamable-http"] = Field(
+        ..., description="Transport type to connect to the MCP server (stdio, sse, or streamable-http)")
+    url: HttpUrl | None = Field(default=None,
+                                description="URL of the MCP server (for sse or streamable-http transport)")
+    command: str | None = Field(default=None,
+                                description="Command to run for stdio transport (e.g. 'python' or 'docker')")
+    args: list[str] | None = Field(default=None, description="Arguments for the stdio command")
+    env: dict[str, str] | None = Field(default=None, description="Environment variables for the stdio process")
+
+    @model_validator(mode="after")
+    def validate_model(self):
+        """Validate that stdio and SSE/Streamable HTTP properties are mutually exclusive."""
+        if self.transport == "stdio":
+            if self.url is not None:
+                raise ValueError("url should not be set when using stdio transport")
+            if not self.command:
+                raise ValueError("command is required when using stdio transport")
+        elif self.transport in ("sse", "streamable-http"):
+            if self.command is not None or self.args is not None or self.env is not None:
+                raise ValueError("command, args, and env should not be set when using sse or streamable-http transport")
+            if not self.url:
+                raise ValueError("url is required when using sse or streamable-http transport")
+        return self
+
+
+class MCPClientConfig(FunctionBaseConfig, name="mcp_client"):
+    """
+    Configuration for connecting to an MCP server as a client and exposing selected tools.
+    """
+    server: MCPServerConfig = Field(..., description="Server connection details (transport, url/command, etc.)")
+    tool_filter: dict[str, MCPToolOverrideConfig] | list[str] | None = Field(
+        default=None,
+        description="""Filter or map tools to expose from the server (list or dict).
+        Can be:
+        - A list of tool names to expose: ['tool1', 'tool2']
+        - A dict mapping tool names to override configs:
+          {'tool1': {'alias': 'new_name', 'description': 'New desc'}}
+          {'tool2': {'description': 'Override description only'}}  # alias defaults to 'tool2'
+        """)
+
+
+class MCPSingleToolConfig(FunctionBaseConfig, name="mcp_single_tool"):
+    """
+    Configuration for wrapping a single tool from an MCP server as a NeMo Agent toolkit function.
+    """
+    client: MCPBaseClient = Field(..., description="MCP client to use for the tool")
+    tool_name: str = Field(..., description="Name of the tool to use")
+    tool_description: str | None = Field(default=None, description="Description of the tool")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+def _get_server_name_safe(client: MCPBaseClient) -> str:
+    # Avoid leaking env secrets from stdio client in logs.
+    if client.transport == "stdio":
+        safe_server = f"stdio: {client.command}"
+    else:
+        safe_server = f"{client.transport}: {client.url}"
+
+    return safe_server
+
+
+@register_function(config_type=MCPSingleToolConfig)
+async def mcp_single_tool(config: MCPSingleToolConfig, builder: Builder):
+    """
+    Wrap a single tool from an MCP server as a NeMo Agent toolkit function.
+    """
+    tool = await config.client.get_tool(config.tool_name)
+    if config.tool_description:
+        tool.set_description(description=config.tool_description)
+    input_schema = tool.input_schema
+
+    logger.info("Configured to use tool: %s from MCP server at %s", tool.name, _get_server_name_safe(config.client))
+
+    def _convert_from_str(input_str: str) -> BaseModel:
+        return input_schema.model_validate_json(input_str)
+
+    @experimental(feature_name="mcp_client")
+    async def _response_fn(tool_input: BaseModel | None = None, **kwargs) -> str:
+        try:
+            if tool_input:
+                return await tool.acall(tool_input.model_dump())
+            _ = input_schema.model_validate(kwargs)
+            return await tool.acall(kwargs)
+        except Exception as e:
+            return str(e)
+
+    fn = FunctionInfo.create(single_fn=_response_fn,
+                             description=tool.description,
+                             input_schema=input_schema,
+                             converters=[_convert_from_str])
+    yield fn
+
+
+@register_function(MCPClientConfig)
+async def mcp_client_function_handler(config: MCPClientConfig, builder: Builder):
+    """
+    Connect to an MCP server, discover tools, and register them as functions in the workflow.
+
+    Note:
+    - Uses builder's exit stack to manage client lifecycle
+    - Applies tool filters if provided
+    """
+    from nat.plugins.mcp.client_base import MCPSSEClient
+    from nat.plugins.mcp.client_base import MCPStdioClient
+    from nat.plugins.mcp.client_base import MCPStreamableHTTPClient
+
+    # Build the appropriate client
+    client_cls = {
+        "stdio": lambda: MCPStdioClient(config.server.command, config.server.args, config.server.env),
+        "sse": lambda: MCPSSEClient(str(config.server.url)),
+        "streamable-http": lambda: MCPStreamableHTTPClient(str(config.server.url)),
+    }.get(config.server.transport)
+
+    if not client_cls:
+        raise ValueError(f"Unsupported transport: {config.server.transport}")
+
+    client = client_cls()
+    logger.info("Configured to use MCP server at %s", _get_server_name_safe(client))
+
+    # client aenter connects to the server and stores the client in the exit stack
+    # so it's cleaned up when the workflow is done
+    async with client:
+        all_tools = await client.get_tools()
+        tool_configs = mcp_filter_tools(all_tools, config.tool_filter)
+
+        for tool_name, tool_cfg in tool_configs.items():
+            await builder.add_function(
+                tool_cfg["function_name"],
+                MCPSingleToolConfig(
+                    client=client,
+                    tool_name=tool_name,
+                    tool_description=tool_cfg["description"],
+                ))
+
+        @experimental(feature_name="mcp_client")
+        async def idle_fn(text: str) -> str:
+            # This function is a placeholder and will be removed when function groups are used
+            return f"MCP client connected: {text}"
+
+        yield FunctionInfo.create(single_fn=idle_fn, description="MCP client")
+
+
+def mcp_filter_tools(all_tools: dict, tool_filter) -> dict[str, dict]:
+    """
+    Apply tool filtering and optional aliasing/description overrides.
+
+    Returns:
+        Dict[str, dict] where each value has:
+            - function_name
+            - description
+    """
+    if tool_filter is None:
+        return {name: {"function_name": name, "description": tool.description} for name, tool in all_tools.items()}
+
+    if isinstance(tool_filter, list):
+        return {
+            name: {
+                "function_name": name, "description": all_tools[name].description
+            }
+            for name in tool_filter if name in all_tools
+        }
+
+    if isinstance(tool_filter, dict):
+        result = {}
+        for name, override in tool_filter.items():
+            tool = all_tools.get(name)
+            if not tool:
+                logger.warning("Tool '%s' specified in tool_filter not found in MCP server", name)
+                continue
+
+            if isinstance(override, MCPToolOverrideConfig):
+                result[name] = {
+                    "function_name": override.alias or name, "description": override.description or tool.description
+                }
+            else:
+                logger.warning("Unsupported override type for '%s': %s", name, type(override))
+                result[name] = {"function_name": name, "description": tool.description}
+        return result
+
+    # Fallback for unsupported tool_filter types
+    raise ValueError(f"Unsupported tool_filter type: {type(tool_filter)}")

nat/plugins/mcp/exception_handler.py

@@ -0,0 +1,211 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, 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, 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,22 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, 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
+
+# Import any providers which need to be automatically registered here
+
+from . import client_impl
+from . import tool

nat/plugins/mcp/tool.py

@@ -0,0 +1,133 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, 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 BaseModel
+from pydantic import Field
+from pydantic import HttpUrl
+from pydantic import model_validator
+
+from nat.builder.builder import Builder
+from nat.builder.function_info import FunctionInfo
+from nat.cli.register_workflow import register_function
+from nat.data_models.function import FunctionBaseConfig
+
+logger = logging.getLogger(__name__)
+
+
+class MCPToolConfig(FunctionBaseConfig, name="mcp_tool_wrapper"):
+    """
+    Function which connects to a Model Context Protocol (MCP) server and wraps the selected tool as a NeMo Agent toolkit
+    function.
+    """
+    # Add your custom configuration parameters here
+    url: HttpUrl | None = Field(default=None,
+                                description="The URL of the MCP server (for streamable-http or sse modes)")
+    mcp_tool_name: str = Field(description="The name of the tool served by the MCP Server that you want to use")
+    transport: Literal["sse", "stdio", "streamable-http"] = Field(
+        default="streamable-http",
+        description="The type of transport to use (default: streamable-http, backwards compatible with sse)")
+    command: str | None = Field(default=None,
+                                description="The command to run for stdio mode (e.g. 'docker' or 'python')")
+    args: list[str] | None = Field(default=None, description="Additional arguments for the stdio command")
+    env: dict[str, str] | None = Field(default=None, description="Environment variables to set for the stdio process")
+    description: str | None = Field(default=None,
+                                    description="""
+        Description for the tool that will override the description provided by the MCP server. Should only be used if
+        the description provided by the server is poor or nonexistent
+        """)
+    return_exception: bool = Field(default=True,
+                                   description="""
+        If true, the tool will return the exception message if the tool call fails.
+        If false, raise the exception.
+        """)
+
+    @model_validator(mode="after")
+    def validate_model(self):
+        """Validate that stdio and SSE/Streamable HTTP properties are mutually exclusive."""
+        if self.transport == 'stdio':
+            if self.url is not None:
+                raise ValueError("url should not be set when using stdio client type")
+            if not self.command:
+                raise ValueError("command is required when using stdio client type")
+        elif self.transport in ['streamable-http', 'sse']:
+            if self.command is not None or self.args is not None or self.env is not None:
+                raise ValueError(
+                    "command, args, and env should not be set when using streamable-http or sse client type")
+            if not self.url:
+                raise ValueError("url is required when using streamable-http or sse client type")
+        return self
+
+
+@register_function(config_type=MCPToolConfig)
+async def mcp_tool(config: MCPToolConfig, builder: Builder):
+    """
+    Generate a NeMo Agent Toolkit Function that wraps a tool provided by the MCP server.
+    """
+
+    from nat.plugins.mcp.client_base import MCPSSEClient
+    from nat.plugins.mcp.client_base import MCPStdioClient
+    from nat.plugins.mcp.client_base import MCPStreamableHTTPClient
+    from nat.plugins.mcp.client_base import MCPToolClient
+
+    # Initialize the client
+    if config.transport == 'stdio':
+        client = MCPStdioClient(command=config.command, args=config.args, env=config.env)
+    elif config.transport == 'streamable-http':
+        client = MCPStreamableHTTPClient(url=str(config.url))
+    elif config.transport == 'sse':
+        client = MCPSSEClient(url=str(config.url))
+    else:
+        raise ValueError(f"Invalid transport type: {config.transport}")
+
+    async with client:
+        # If the tool is found create a MCPToolClient object and set the description if provided
+        tool: MCPToolClient = await client.get_tool(config.mcp_tool_name)
+        if config.description:
+            tool.set_description(description=config.description)
+
+        logger.info("Configured to use tool: %s from MCP server at %s", tool.name, client.server_name)
+
+        def _convert_from_str(input_str: str) -> tool.input_schema:
+            return tool.input_schema.model_validate_json(input_str)
+
+        async def _response_fn(tool_input: BaseModel | None = None, **kwargs) -> str:
+            # Run the tool, catching any errors and sending to agent for correction
+            try:
+                if tool_input:
+                    args = tool_input.model_dump()
+                    return await tool.acall(args)
+
+                _ = tool.input_schema.model_validate(kwargs)
+                return await tool.acall(kwargs)
+            except Exception as e:
+                if config.return_exception:
+                    if tool_input:
+                        logger.warning("Error calling tool %s with serialized input: %s",
+                                       tool.name,
+                                       tool_input.model_dump(),
+                                       exc_info=True)
+                    else:
+                        logger.warning("Error calling tool %s with input: %s", tool.name, kwargs, exc_info=True)
+                    return str(e)
+                # If the tool call fails, raise the exception.
+                raise
+
+        yield FunctionInfo.create(single_fn=_response_fn,
+                                  description=tool.description,
+                                  input_schema=tool.input_schema,
+                                  converters=[_convert_from_str])

nvidia_nat_mcp-1.3.0a20250909.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: nvidia-nat-mcp
+Version: 1.3.0a20250909
+Summary: Subpackage for MCP client integration in NeMo Agent toolkit
+Keywords: ai,rag,agents,mcp
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: nvidia-nat==v1.3.0a20250909
+Requires-Dist: mcp~=1.13
+
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2025, 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.
+-->
+
+![NVIDIA NeMo Agent Toolkit](https://media.githubusercontent.com/media/NVIDIA/NeMo-Agent-Toolkit/refs/heads/main/docs/source/_static/banner.png "NeMo Agent toolkit banner image")
+
+
+# NVIDIA NeMo Agent Toolkit MCP Subpackage
+Subpackage for MCP client integration in NeMo Agent toolkit.
+
+This package provides MCP (Model Context Protocol) client functionality, allowing NeMo Agent toolkit workflows to connect to external MCP servers and use their tools as functions.
+
+## Features
+
+- Connect to MCP servers via streamable-http, SSE, or stdio transports
+- Wrap individual MCP tools as NeMo Agent toolkit functions
+- Connect to MCP servers and dynamically discover available tools
+
+For more information about the NVIDIA NeMo Agent toolkit, please visit the [NeMo Agent toolkit GitHub Repo](https://github.com/NVIDIA/NeMo-Agent-Toolkit).

nvidia_nat_mcp-1.3.0a20250909.dist-info/RECORD

@@ -0,0 +1,13 @@
+nat/meta/pypi.md,sha256=GyV4DI1d9ThgEhnYTQ0vh40Q9hPC8jN-goLnRiFDmZ8,1498
+nat/plugins/mcp/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv-tZzbU9W-izgx9aMEQg,680
+nat/plugins/mcp/client_base.py,sha256=4vFOBFoSpLpkq7r2iXDMbi6tDj02JBidZo5RiBR167w,13424
+nat/plugins/mcp/client_impl.py,sha256=6rG3LcCX4TFsiST5O0_C8eOpY9LdnoSMarfAWeR76XA,9724
+nat/plugins/mcp/exception_handler.py,sha256=JdPdZG1NgWpdRnIz7JTGHiJASS5wot9nJiD3SRWV4Kw,7649
+nat/plugins/mcp/exceptions.py,sha256=EGVOnYlui8xufm8dhJyPL1SUqBLnCGOTvRoeyNcmcWE,5980
+nat/plugins/mcp/register.py,sha256=HOT2Wl2isGuyFc7BUTi58-BbjI5-EtZMZo7stsv5pN4,831
+nat/plugins/mcp/tool.py,sha256=MSRnnr1a6OjfqVkt2SYPkfLi9lU0JqovIZuTOL1cgHQ,6378
+nvidia_nat_mcp-1.3.0a20250909.dist-info/METADATA,sha256=w2nXFHRlGLbHy6RPOhRmnA3AgLKzNdnC6DFXdNPdPYs,1997
+nvidia_nat_mcp-1.3.0a20250909.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nvidia_nat_mcp-1.3.0a20250909.dist-info/entry_points.txt,sha256=x7dQTqek3GEdU-y9GslnygxMu0BSbEeUiOOMa2gvaaQ,52
+nvidia_nat_mcp-1.3.0a20250909.dist-info/top_level.txt,sha256=8-CJ2cP6-f0ZReXe5Hzqp-5pvzzHz-5Ds5H2bGqh1-U,4
+nvidia_nat_mcp-1.3.0a20250909.dist-info/RECORD,,

nvidia_nat_mcp-1.3.0a20250909.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nvidia_nat_mcp-1.3.0a20250909.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[nat.components]
+nat_mcp = nat.plugins.mcp.register

nvidia_nat_mcp-1.3.0a20250909.dist-info/top_level.txt

@@ -0,0 +1 @@
+nat