Merge pull request #51218 from buzahid/ai-agents

New Module - Integrate MCP Tools with Azure AI Agents

Author: JamesJBarnett

learn-pr/paths/develop-ai-agents-on-azure/index.yml

@@ -31,5 +31,6 @@ modules:
 - learn.wwl.develop-ai-agent-with-semantic-kernel
 - learn.wwl.orchestrate-sk-multi-agent-solution
 - learn.wwl.develop-multi-agent-azure-ai-foundry
+- learn.wwl.connect-agent-to-mcp-tools
 trophy:
   uid: learn.wwl.develop-ai-agent-on-azure.trophy

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/1-introduction.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.connect-agent-to-mcp-tools.introduction
+title: Introduction
+metadata:
+  title: Introduction
+  description: "Learn how to integrate Model Context Protocol (MCP) tools with Azure AI Agents."
+  ms.date: 06/13/2025
+  author: buzahid
+  ms.author: buzahid
+  ms.topic: unit
+durationInMinutes: 2
+content: |
+  [!include[](includes/1-introduction.md)]

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/2-understand-mcp-tool-discovery.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.connect-agent-to-mcp-tools.understand-mcp-tool-discovery
+title: Understand MCP tool discovery
+metadata:
+  title: Understand MCP Tool Discovery
+  description: "Learn how Model Context Protocol (MCP) servers host functions that can be discovered by LLMs."
+  ms.date: 06/13/2025
+  author: buzahid
+  ms.author: buzahid
+  ms.topic: unit
+durationInMinutes: 5
+content: |
+  [!include[](includes/2-understand-mcp-tool-discovery.md)]

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/3-mcp-client-server-setup.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.connect-agent-to-mcp-tools.mcp-client-server-setup
+title: Integrate agent tools using an MCP server and client
+metadata:
+  title: Integrate Agent Tools Using an MCP Server and Client
+  description: "Learn how to expose Model Context Protocol (MCP) tools through a server and register them to an Azure AI Agent."
+  ms.date: 06/13/2025
+  author: buzahid
+  ms.author: buzahid
+  ms.topic: unit
+durationInMinutes: 5
+content: |
+  [!include[](includes/3-mcp-client-server-setup.md)]

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/4-exercise.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.connect-agent-to-mcp-tools.exercise
+title: Exercise - Connect MCP tools to Azure AI Agents
+metadata:
+  title: Exercise - Connect MCP Tools to Azure AI Agents
+  description: "Build a Model Context Protocol (MCP) client-server application that dynamically registers tools to an Azure AI Agent."
+  ms.date: 06/13/2025
+  author: buzahid
+  ms.author: buzahid
+  ms.topic: unit
+durationInMinutes: 30
+content: |
+  [!include[](includes/4-exercise.md)]

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/5-knowledge-check.yml

@@ -0,0 +1,47 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.connect-agent-to-mcp-tools.knowledge-check
+title: Module assessment
+metadata:
+  title: Module Assessment
+  description: "Check your learning on connecting Model Context Protocol (MCP) tools to Azure AI Agents."
+  ms.date: 06/13/2025
+  author: buzahid
+  ms.author: buzahid
+  ms.topic: unit
+durationInMinutes: 3
+content: |
+quiz:
+  questions:
+  - content: "What role does the MCP server play in the MCP agent tool integration?"
+    choices:
+    - content: "Runs the AI agent and processes user prompts directly."
+      isCorrect: false
+      explanation: "Incorrect. The server hosts tools; the agent processes prompts."
+    - content: "Manages network connections between multiple agents."
+      isCorrect: false
+      explanation: "Incorrect. The server focuses on tool hosting, not agent networking."
+    - content: "Hosts tool definitions and makes them available for discovery by the client."
+      isCorrect: true
+      explanation: "Correct. The MCP server acts as a central registry for tool definitions."
+  - content: "How does an MCP client retrieve available tools from the MCP server?"
+    choices:
+    - content: "By calling `session.list_tools()` to get the current tool catalog."
+      isCorrect: true
+      explanation: "Correct. The client uses `list_tools()` to discover tools dynamically."
+    - content: "By reading a static JSON file from the server directory."
+      isCorrect: false
+      explanation: "Incorrect. Tools are discovered dynamically, not via static files."
+    - content: "By subscribing to server events via a WebSocket connection."
+      isCorrect: false
+      explanation: "Incorrect. The client uses direct calls, not event subscriptions, to list tools."
+  - content: "Why should MCP tools be wrapped in async functions on the client-side?"
+    choices:
+    - content: "To allow the agent to wait for user input."
+      isCorrect: false
+      explanation: "Incorrect. The tools do not prevent the agent from receiving user input."
+    - content: "To enable asynchronous invocation so the agent can call tools without blocking."
+      isCorrect: true
+      explanation: "Async functions let the agent invoke tools efficiently."
+    - content: "To convert the functions into REST API endpoints automatically."
+      isCorrect: false
+      explanation: "Incorrect. Wrapping tools in async functions does not generate REST endpoints."

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/6-summary.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.connect-agent-to-mcp-tools.summary
+title: Summary
+metadata:
+  title: Summary
+  description: "Reflect on what you learned about Model Context Protocol (MCP) agent tools."
+  ms.date: 06/13/2025
+  author: buzahid
+  ms.author: buzahid
+  ms.topic: unit
+durationInMinutes: 1
+content: |
+  [!include[](includes/6-summary.md)]

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/includes/1-introduction.md

@@ -0,0 +1,7 @@
+AI agents are capable of performing a wide range of tasks, but many tasks still require them to interact with tools outside the large language model. Agents may need to access APIs, databases, or internal services. Manually integrating and maintaining these tools can quickly become complex, especially as your system grows, or changes frequently.
+
+Model Context Protocol (MCP) servers can help solve this problem by integrating with AI agents. Connecting an Azure AI Agent to a Model Context Protocol (MCP) server can provide your agent with a catalog of tools accessible on demand. This approach makes your AI solution more robust, scalable, and easier to maintain.
+
+Suppose you're working for a retailer that specializes in cosmetics. Your team wants to build an AI assistant that can help manage inventory by checking product stock levels and recent sales trends. Using an MCP server, you can connect the assistant to a set of tools that can make inventory assessments and provide recommendations to the team.
+
+In this module, you learn how to set up an MCP server and client, and connect tools to an Azure AI Agent dynamically. You also practice creating your own AI MCP tool solution with Azure AI Foundry Agent Service.

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/includes/2-understand-mcp-tool-discovery.md

@@ -0,0 +1,30 @@
+As AI agents become more capable, the range of tools and services they can access also grows. However, registering new tools, managing, updating, and integrating them can quickly become complex and time-consuming. Dynamic tool discovery helps solve this problem by enabling agents to find and use tools automatically at runtime.
+
+## What is dynamic tool discovery?
+
+Dynamic tool discovery is a mechanism that allows an AI agent to discover available external tools without needing hardcoded knowledge of each one. Instead of manually adding or updating every tool your agent can use, the agent queries a centralized Model Context Protocol (MCP) server. This server acts as a live catalog, exposing tools that the agent can understand and call.
+
+This approach means:
+
+- Tools can be added, updated, or removed centrally without modifying the agent code.
+- Agents can always use the latest version of a tool, improving accuracy and reliability.
+- The complexity of managing tools shifts away from the agent and into a dedicated service.
+
+## How does MCP enable dynamic tool discovery?
+
+An MCP server hosts a set of functions that are exposed as tools using the `@mcp.tool` decorator. Tools are a primitive type in the MCP that enables servers to expose executable functionality to clients. A client can connect to the server and fetch these tools dynamically. The client then generates function wrappers that are added to the Azure AI Agent's tool definitions. This setup creates a flexible pipeline:
+
+- The MCP server hosts available tools.
+- The MCP client dynamically discovers the tools.
+- The Azure AI Agent uses the available tools to respond to user requests.
+
+## Why use dynamic tool discovery with MCP?
+
+This approach provides several benefits:
+
+- Scalability: Easily add new tools or update existing ones without redeploying agents.
+- Modularity: Agents can remain simple, focusing on delegation rather than managing tool details.
+- Maintainability: Centralized tool management reduces duplication and errors.
+- Flexibility: Supports diverse tool types and complex workflows by aggregating capabilities.
+
+Dynamic tool discovery is especially useful in environments where tools evolve rapidly or where many teams manage different APIs and services. Using tools allows AI agents to adapt to changing capabilities in real time, interact with external systems securely, and perform actions that go beyond language generation.

learn-pr/wwl-data-ai/connect-agent-to-mcp-tools/includes/3-mcp-client-server-setup.md

@@ -0,0 +1,30 @@
+To dynamically connect tools to your Azure AI Agent, you first need a functioning Model Context Protocol (MCP) setup. This includes both the MCP server, which hosts your tool catalog, and the MCP client, which fetches those tools and makes them usable by your agent.
+
+## What is the MCP Server?
+
+The MCP server acts as a registry for tools your agent can use. You can initialize your MCP server using `FastMCP("server-name")`. The FastMCP class uses Python type hints and document strings to automatically generate tool definitions, making it easy to create and maintain MCP tools. These definitions are then served over HTTP when requested by the client. Because tool definitions live on the server, you can update or add new tools at any time, without having to modify or redeploy your agent.
+
+## What is the MCP Client?
+
+The MCP client acts as a bridge between your MCP server and the Azure AI Agent Service. The client initializes an MCP client session and connects to the server. Afterwards, it performs three key tasks:
+
+- Discovers available tools from the MCP server using `session.list_tools()`.
+- Generates Python function stubs that wrap the tools.
+- Registers those functions with your agent.
+
+This allows the agent to call any tool listed in the MCP catalog as if it were a native function, all without hardcoded logic.
+
+## Register tools with an Azure AI Agent
+
+When an MCP client session is initialized, the client can dynamically pull in tools from the MCP server. An MCP tool can be invoked using `session.call_tool(tool_name, tool_args)`. The tools should each be wrapped in an async function so that the agent is able to invoke them. Finally, those functions are bundled together and become part of the agent's toolset and are available during runtime for any user request.
+
+**Overview of MCP agent tool integration**
+
+- The **MCP server** hosts tool definitions decorated with `@mcp.tool`.
+- The **MCP client** initializes an MCP client connection to the server. 
+- The **MCP client**  fetches the available tool definitions with `session.list_tools()`.
+- Each tool is wrapped in an async function that invokes `session.call_tool`
+- The tool functions are bundled into `FunctionTool` that makes them usable by the agent.
+- The `FunctionTool` is registered to the agent's toolset.
+
+Now your agent is able to access and invoke your tools through natural language interaction. By setting up the MCP server and client, you create a clean separation between tool management and agent logic—enabling your system to adapt quickly as new tools become available.