Python: [Feature Branch] Added hosted MCP support

python/packages/azure-ai/agent_framework_azure_ai/_client.py

@@ -1,13 +1,14 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import sys
-from collections.abc import MutableSequence
+from collections.abc import MutableMapping, MutableSequence
 from typing import Any, ClassVar, TypeVar
 
 from agent_framework import (
     AGENT_FRAMEWORK_USER_AGENT,
     ChatMessage,
     ChatOptions,
+    HostedMCPTool,
     TextContent,
     get_logger,
     use_chat_middleware,
@@ -18,6 +19,7 @@
 from agent_framework.openai._responses_client import OpenAIBaseResponsesClient
 from azure.ai.projects.aio import AIProjectClient
 from azure.ai.projects.models import (
+    MCPTool,
     PromptAgentDefinition,
     PromptAgentDefinitionText,
     ResponseTextFormatConfigurationJsonSchema,
@@ -325,3 +327,27 @@ def _update_agent_name(self, agent_name: str | None) -> None:
         # to update the agent name in the client.
         if agent_name and not self.agent_name:
             self.agent_name = agent_name
+
+    def get_mcp_tool(self, tool: HostedMCPTool) -> MutableMapping[str, Any]:
+        """Get MCP tool from HostedMCPTool."""
+        mcp: MCPTool = {
+            "type": "mcp",
+            "server_label": tool.name.replace(" ", "_"),
+            "server_url": str(tool.url),
+        }
+
+        if tool.allowed_tools:
+            mcp["allowed_tools"] = list(tool.allowed_tools)
+
+        # TODO (dmytrostruk): Check "always" approval mode
+        if tool.approval_mode:
+            match tool.approval_mode:
+                case str():
+                    mcp["require_approval"] = "always" if tool.approval_mode == "always_require" else "never"
+                case _:
+                    if always_require_approvals := tool.approval_mode.get("always_require_approval"):
+                        mcp["require_approval"] = {"always": {"tool_names": list(always_require_approvals)}}
+                    if never_require_approvals := tool.approval_mode.get("never_require_approval"):
+                        mcp["require_approval"] = {"never": {"tool_names": list(never_require_approvals)}}
+
+        return mcp

python/packages/core/agent_framework/openai/_responses_client.py

@@ -187,31 +187,7 @@ def _tools_to_response_tools(
             if isinstance(tool, ToolProtocol):
                 match tool:
                     case HostedMCPTool():
-                        mcp: Mcp = {
-                            "type": "mcp",
-                            "server_label": tool.name.replace(" ", "_"),
-                            "server_url": str(tool.url),
-                            "server_description": tool.description,
-                            "headers": tool.headers,
-                        }
-                        if tool.allowed_tools:
-                            mcp["allowed_tools"] = list(tool.allowed_tools)
-                        if tool.approval_mode:
-                            match tool.approval_mode:
-                                case str():
-                                    mcp["require_approval"] = (
-                                        "always" if tool.approval_mode == "always_require" else "never"
-                                    )
-                                case _:
-                                    if always_require_approvals := tool.approval_mode.get("always_require_approval"):
-                                        mcp["require_approval"] = {
-                                            "always": {"tool_names": list(always_require_approvals)}
-                                        }
-                                    if never_require_approvals := tool.approval_mode.get("never_require_approval"):
-                                        mcp["require_approval"] = {
-                                            "never": {"tool_names": list(never_require_approvals)}
-                                        }
-                        response_tools.append(mcp)
+                        response_tools.append(self.get_mcp_tool(tool))
                     case HostedCodeInterpreterTool():
                         tool_args: CodeInterpreterContainerCodeInterpreterToolAuto = {"type": "auto"}
                         if tool.inputs:
@@ -305,6 +281,27 @@ def _tools_to_response_tools(
                     response_tools.append(tool_dict)
         return response_tools
 
+    def get_mcp_tool(self, tool: HostedMCPTool) -> MutableMapping[str, Any]:
+        """Get MCP tool from HostedMCPTool."""
+        mcp: Mcp = {
+            "type": "mcp",
+            "server_label": tool.name.replace(" ", "_"),
+            "server_url": str(tool.url),
+            "server_description": tool.description,
+            "headers": tool.headers,
+        }
+        if tool.allowed_tools:
+            mcp["allowed_tools"] = list(tool.allowed_tools)
+        if tool.approval_mode:
+            match tool.approval_mode:
+                case str():
+                    mcp["require_approval"] = "always" if tool.approval_mode == "always_require" else "never"
+                case _:
+                    if always_require_approvals := tool.approval_mode.get("always_require_approval"):
+                        mcp["require_approval"] = {"always": {"tool_names": list(always_require_approvals)}}
+                    if never_require_approvals := tool.approval_mode.get("never_require_approval"):
+                        mcp["require_approval"] = {"never": {"tool_names": list(never_require_approvals)}}
+
     async def prepare_options(
         self, messages: MutableSequence[ChatMessage], chat_options: ChatOptions
     ) -> dict[str, Any]:

python/samples/getting_started/agents/azure_ai/README.md

@@ -12,6 +12,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_ai_with_existing_agent.py`](azure_ai_with_existing_agent.py) | Shows how to work with a pre-existing agent by providing the agent name and version to the Azure AI client. Demonstrates agent reuse patterns for production scenarios. |
 | [`azure_ai_with_existing_conversation.py`](azure_ai_with_existing_conversation.py) | Shows how to work with a pre-existing conversation by providing the conversation ID to continue existing chat sessions. |
 | [`azure_ai_with_explicit_settings.py`](azure_ai_with_explicit_settings.py) | Shows how to create an agent with explicitly configured `AzureAIClient` settings, including project endpoint, model deployment, and credentials rather than relying on environment variable defaults. |
+| [`azure_ai_with_hosted_mcp.py`](azure_ai_with_hosted_mcp.py) | Shows how to integrate hosted Model Context Protocol (MCP) tools with Azure AI Agent. |
 | [`azure_ai_with_response_format.py`](azure_ai_with_response_format.py) | Shows how to use structured outputs (response format) with Azure AI agents using Pydantic models to enforce specific response schemas. |
 | [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
 

python/samples/getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py

@@ -0,0 +1,46 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import HostedMCPTool
+from agent_framework.azure import AzureAIClient
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Hosted MCP Example
+
+This sample demonstrates integrating hosted Model Context Protocol (MCP) tools with Azure AI Agent.
+"""
+
+
+async def run_hosted_mcp() -> None:
+    # Since no Agent ID is provided, the agent will be automatically created.
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIClient(async_credential=credential).create_agent(
+            name="MyDocsAgent",
+            instructions="You are a helpful assistant that can help with Microsoft documentation questions.",
+            tools=HostedMCPTool(
+                name="Microsoft Learn MCP",
+                url="https://learn.microsoft.com/api/mcp",
+                # "always_require" mode is not supported yet
+                approval_mode="never_require",
+            ),
+        ) as agent,
+    ):
+        query = "How to create an Azure storage account using az cli?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"{agent.name}: {result}\n")
+
+
+async def main() -> None:
+    print("=== Azure AI Agent with Hosted Mcp Tools Example ===\n")
+
+    await run_hosted_mcp()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())