Merge pull request #5777 from MicrosoftDocs/main

Auto Publish – main to live - 2025-06-27 22:06 UTC

Author: Taojunshen

articles/ai-foundry/agents/how-to/tools/model-context-protocol-samples.md

@@ -0,0 +1,106 @@
+---
+title: 'MCP tool code samples'
+titleSuffix: Azure AI Foundry
+description: Find code samples to connect Foundry Agent service with MCP.
+services: cognitive-services
+manager: nitinme
+ms.service: azure-ai-agent-service
+ms.topic: how-to
+ms.date: 06/26/2025
+author: aahill
+ms.author: aahi
+zone_pivot_groups: selection-mcp-code
+ms.custom: azure-ai-agents-code
+---
+
+# How to use the Model Context Protocol (MCP) tool
+
+Use this article to find step-by-step instructions and code samples for connecting Foundry Agent service with MCP.
+
+Follow the [REST API Quickstart](../../quickstart.md?pivots=rest-api#api-call-information) to set the right values for the environment variables `AGENT_TOKEN`, `AZURE_AI_FOUNDRY_PROJECT_ENDPOINT` and `API_VERSION`.
+
+
+## Create an Agent with the MCP tool enabled
+
+To make the MCP tool available to your agent, initialize a tool with the server endpoint, server label and more
+```bash
+curl --request POST \
+  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+	  "instructions": "You are a customer support chatbot. Use the tools provided and your knowledge base to best respond to customer queries.",
+  	"tools": [
+          {
+              "type": "mcp",
+              "server_label": "<unique name for your MCP server>",
+              "server_url": "<your MCP server url>",
+              "require_approval": "never",
+          }
+      ],
+  "name": "my-assistant",
+  "model": "gpt-4o",
+}"
+```
+
+## Create a thread
+
+```bash
+curl --request POST \
+  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=$API_VERSION \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d ''
+```
+
+## Add a user question to the thread
+
+```bash
+curl --request POST \
+  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+      "role": "user",
+      "content": "<user input related to the MCP server you connect>"
+    }'
+```
+
+## Create a run and check the output
+
+Create a run to pass headers for the tool and observe that the model uses the Grounding with Bing Search tool to provide a response to the user's question.
+
+```bash
+curl --request POST \
+  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=$API_VERSION \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+	    "assistant_id": "<agent_id>",
+    	"tool_resources": {
+          "mcp": [
+            {
+                "server_label": "<the same unique name you provided during agent creation>",
+                "headers": {
+                    "Authorization": "Bearer <token>",
+                }
+            }
+          ]
+      },
+    }'
+```
+## Retrieve the status of the run
+
+```bash
+curl --request GET \
+  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=$API_VERSION \
+  -H "Authorization: Bearer $AGENT_TOKEN"
+```
+
+## Retrieve the agent response
+
+```bash
+curl --request GET \
+  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
+  -H "Authorization: Bearer $AGENT_TOKEN"
+```

articles/ai-foundry/agents/how-to/tools/model-context-protocol.md

@@ -0,0 +1,54 @@
+---
+title: 'How to connect to Model Context Protocol Server Endpoint in Azure AI Foundry Agent Service'
+titleSuffix: Azure AI Foundry
+description: Learn how to add MCP to Foundry Agent service.
+services: cognitive-services
+manager: nitinme
+ms.service: azure-ai-agent-service
+ms.topic: how-to
+ms.date: 06/17/2025
+author: aahill
+ms.author: aahi
+ms.custom: references_regions
+---
+# Connect to Model Context Protocol (MCP) Servers (Preview)
+You can extend the capabilities of your Foundry Agent by connecting it to tools hosted on remote Model Context Protocol (MCP) servers (bring your own MCP server endpoint). These servers are maintained by developers and organizations and expose tools that can be accessed by MCP-compatible clients, such as the Foundry Agent service.
+
+[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open standard that defines how applications provide tools and contextual data to large language models (LLMs). It enables consistent, scalable integration of external tools into model workflows.
+
+> [!IMPORTANT]
+> * Your use of connected non-Microsoft services is subject to the terms between you and the service provider.  By connecting to a non-Microsoft service, some of your data, such as prompt content, is passed to the non-Microsoft service, and/or your application might receive data from the non-Microsoft service. You are responsible for your use (and any charges associated with your use) of non-Microsoft services and data.
+> * The remote MCP servers you decide to use with this MCP tool were created by third parties, not Microsoft, and have not been tested or verified by Microsoft. Microsoft has no responsibility to you or others in relation to your use of any remote MCP servers. We recommend carefully reviewing and tracking what MCP servers you add to Foundry Agent service and relying on servers hosted by trusted service providers themselves rather than proxies. This MCP tool also allows you to pass custom headers such as authentication keys or schema as might be needed by a remote MCP server. We recommend reviewing all data being shared with remote MCP servers and optionally logging it for auditing purposes. Be cognizant of non-Microsoft practices for retention and location of data.
+
+## How it works
+You can bring multiple remote MCP servers to Foundry Agent service by adding them as tools. For each tool, you need to provide a unique `server_label` within the same agent and `server_url` that points to the remote MCP server. The MCP tool supports custom headers, allowing you to connect to these servers using the authentication scheme they require or passing other headers required by the MCP server. You can only specify headers by including in `tool_resources` at each run such as API keys, OAuth access tokens, or other credentials directly in your request. The most commonly used header is the authorization header. For more information on using MCP, see:
+* [Security best practices](https://modelcontextprotocol.io/specification/draft/basic/security_best_practices)
+* [Understanding and mitigating security risks in MCP implementations](https://techcommunity.microsoft.com/blog/microsoft-security-blog/understanding-and-mitigating-security-risks-in-mcp-implementations/4404667)
+
+> [!Note]
+> * You need to bring a remote MCP server (an existing MCP server endpoint)
+> * With current MCP tool in Foundry Agent, explicit approval is not supported (only `never` is accepted for `require_approval` parameter). Please review carefully what MCP server(s) you added to Foundry Agent service. We recommend reviewing all data being shared with remote MCP servers and optionally logging it for auditing purposes.
+> * Supported regions: `westus`, `westus2`, `uaenorth`, `southindia` and `switzerlandnorth`
+> * The MCP tool supports custom headers for a specific run, allowing you to pass headers as needed by MCP server, such as authentication schema. Headers you pass in will only be available for the current run and will not be persisted.
+
+## Usage support
+
+|Azure AI foundry support  | Python SDK |	C# SDK | JavaScript SDK | REST API |Basic agent setup | Standard agent setup |
+|:---------:|:---------:|:---------:|:---------:|:---------:|:---------:|---------:|
+| - | - | - | - | ✔️ | ✔️ | ✔️ |
+
+## Setup  
+1. Create an Azure AI Foundry Agent by following the steps in the [quickstart](../../quickstart.md).
+
+1. Find the remote MCP server you want to connect to, such as GitHub MCP Server. Create or update a Foundry Agent with a `mcp` tool with the following information:
+   1. `server_url`: the url of the MCP server, for example, `https://api.githubcopilot.com/mcp/`
+   2. `server_label`: a unique identifier of this MCP server to the agent, for example, `github`
+   3. `require_approval`: only `never` is supported right now
+  
+1. Create a run and pass additional information about the `mcp` tool in `tool_resources` with headers
+   1. `tool_label`: use the identifier you provided during create/update agent
+   2. `headers`: pass a set of headers required by the MCP server
+
+## Next steps
+
+* [How to use the MCP tool](./model-context-protocol-samples.md)

articles/ai-foundry/agents/how-to/tools/overview.md

@@ -32,6 +32,7 @@ To streamline workflows with your AI agent with capabilities to take actions. Th
 
 - **Azure Logic Apps**: Low-code / no-code solution to add a workflow to your AI Agent
 - **OpenAPI Spec tool**: Bring an existing OpenAPI specification of a service API you want to add to your AI agent, with no or minor changes.
+- **MCP tool**: Bring an existing Model Context Protocol (MCP) endpoint that you want to add to your AI agent.
 - **Function calling**: Write your own custom, stateless functions to define the expected behaviors.
 - **Azure Functions**: Write and manage your own custom, stateful functions. 
 
@@ -75,6 +76,7 @@ The Foundry Agent Service provides the following built-in tools. You can use the
 |[Function calling](function-calling.md)     |Describe the structure of functions you create to an agent and have them be called when appropriate during the agent's interactions with users.         |
 |[Grounding with Bing Search](bing-grounding.md)     | Enable your agent to use Grounding with Bing Search to access and return information from the internet.         |
 | [Grounding with Bing Custom Search (preview)](bing-custom-search.md) | Enhance your Agent response with selected web domains |
+| [Model Context Protocol (preview)](./model-context-protocol.md) | Give the agent access to tools hosted on an existing MCP endpoint |
 | [Microsoft Fabric (preview)](fabric.md) | Integrate your agent with the [Microsoft Fabric data agent](https://go.microsoft.com/fwlink/?linkid=2312815) to unlock powerful data analysis capabilities. |
 | [OpenAPI 3.0 Specified tool ](openapi-spec.md) | Connect your Azure AI Agent to external APIs using functions with an OpenAPI 3.0 specification. |
 

articles/ai-foundry/agents/toc.yml

@@ -86,6 +86,14 @@ items:
               href: how-to/tools/openapi-spec-samples.md
             - name: Invoke an OpenAPI App Service web app
               href: /azure/app-service/invoke-openapi-web-app-from-azure-ai-agent-service?context=/azure/ai-services/agents/context/context
+        - name: Model Context Protocol (MCP)
+          items:
+            - name: Overview
+              href: how-to/tools/model-context-protocol.md
+              displayName: model context protocol, mcp
+            - name: How to use Model Context Protocol
+              displayName: model context protocol, mcp samples
+              href: how-to/tools/model-context-protocol-samples.md
         - name: Azure Functions
           items:
             - name: Overview

articles/ai-foundry/agents/whats-new.md

@@ -7,14 +7,20 @@ author: aahill
 ms.author: aahi
 ms.service: azure-ai-agent-service
 ms.topic: overview
-ms.date: 04/23/2025
+ms.date: 06/26/2025
 ms.custom: azure-ai-agents
 ---
 
 # What's new in Azure AI Foundry Agent Service
 
 This article provides a summary of the latest releases and major documentation updates for Azure AI Foundry Agent Service.
 
+## June 2025
+
+### Model Context Protocol (MCP) tool
+
+You can new extend the capabilities of your agents by connecting them to tools hosted on remote [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) servers by using the [MCP tool](./how-to/tools/model-context-protocol.md). 
+
 ## May 2025
 
 ### Azure AI Foundry Agent Service GA