Skip to content

Commit 7d0e775

Browse files
aahillaahill
committed
mcp tool
1 parent c5bf893 commit 7d0e775

File tree

4 files changed

+166
-0
lines changed

4 files changed

+166
-0
lines changed

‎articles/ai-foundry/agents/how-to/tools/mcp-samples.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: 'MCP tool code samples'
3+
titleSuffix: Azure AI Foundry
4+
description: Find code samples to connect Foundry Agent service with MCP.
5+
services: cognitive-services
6+
manager: nitinme
7+
ms.service: azure-ai-agent-service
8+
ms.topic: how-to
9+
ms.date: 06/26/2025
10+
author: aahill
11+
ms.author: aahi
12+
zone_pivot_groups: selection-mcp-code
13+
ms.custom: azure-ai-agents-code
14+
---
15+
16+
# How to connect Foundry Agent service with Model Context Protocol (MCP)
17+
18+
Use this article to find step-by-step instructions and code samples for connecting Foundry Agent service with MCP.
19+
20+
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`.
21+
22+
23+
## Create an Agent with the MCP tool enabled
24+
25+
To make the MCP tool available to your agent, initialize a tool with the server endpoint, server label and more
26+
```bash
27+
curl --request POST \
28+
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION \
29+
-H "Authorization: Bearer $AGENT_TOKEN" \
30+
-H "Content-Type: application/json" \
31+
-d "{
32+
"instructions": "You are a customer support chatbot. Use the tools provided and your knowledge base to best respond to customer queries.",
33+
"tools": [
34+
{
35+
"type": "mcp",
36+
"server_label": "github",
37+
"server_url": "https://gitmcp.io/Azure/azure-rest-api-specs",
38+
"require_approval": "never",
39+
}
40+
],
41+
"name": "my-assistant",
42+
"model": "gpt-4o",
43+
}"
44+
```
45+
46+
## Create a thread
47+
48+
```bash
49+
curl --request POST \
50+
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=$API_VERSION \
51+
-H "Authorization: Bearer $AGENT_TOKEN" \
52+
-H "Content-Type: application/json" \
53+
-d ''
54+
```
55+
56+
## Add a user question to the thread
57+
58+
```bash
59+
curl --request POST \
60+
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
61+
-H "Authorization: Bearer $AGENT_TOKEN" \
62+
-H "Content-Type: application/json" \
63+
-d '{
64+
"role": "user",
65+
"content": "<user input related to the MCP server you connect>"
66+
}'
67+
```
68+
69+
## Create a run and check the output
70+
71+
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.
72+
73+
```bash
74+
curl --request POST \
75+
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=$API_VERSION \
76+
-H "Authorization: Bearer $AGENT_TOKEN" \
77+
-H "Content-Type: application/json" \
78+
-d '{
79+
"assistant_id": "<agent_id>",
80+
"tool_resources": {
81+
"mcp": [
82+
{
83+
"server_label": "github",
84+
"headers": {
85+
"Authorization": "Bearer <token>",
86+
}
87+
}
88+
]
89+
},
90+
}'
91+
```
92+
## Retrieve the status of the run
93+
94+
```bash
95+
curl --request GET \
96+
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=$API_VERSION \
97+
-H "Authorization: Bearer $AGENT_TOKEN"
98+
```
99+
100+
## Retrieve the agent response
101+
102+
```bash
103+
curl --request GET \
104+
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
105+
-H "Authorization: Bearer $AGENT_TOKEN"
106+
```

‎articles/ai-foundry/agents/how-to/tools/mcp.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: 'How to connect to Model Context Protocol Server Endpoint in Azure AI Foundry Agent Service'
3+
titleSuffix: Azure AI Foundry
4+
description: Learn how to add MCP to Foundry Agent service.
5+
services: cognitive-services
6+
manager: nitinme
7+
ms.service: azure-ai-agent-service
8+
ms.topic: how-to
9+
ms.date: 06/17/2025
10+
author: aahill
11+
ms.author: aahi
12+
ms.custom: azure-ai-agents
13+
---
14+
# Connect Model Context Protocol Server with Azure AI Foundry Agent Service (Preview)
15+
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.
16+
17+
[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.
18+
19+
> [!IMPORTANT]
20+
> * 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.
21+
> * 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 third party practices for retention and location of data.
22+
23+
## How it works
24+
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.
25+
> [!Note]
26+
> * You need to bring a remote MCP server (an existing MCP server endpoint)
27+
> * With current MCP tool in Foundry Agent, explicit approval is not supported yet (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.
28+
> * Supported regions: `westus`, `westus2` and `uaenorth`
29+
30+
## Usage support
31+
32+
|Azure AI foundry support | Python SDK | C# SDK | JavaScript SDK | REST API |Basic agent setup | Standard agent setup |
33+
|:---------:|:---------:|:---------:|:---------:|:---------:|:---------:|---------:|
34+
| - | - | - | - | ✔️ | ✔️ | ✔️ |
35+
36+
## Setup
37+
1. Create an Azure AI Foundry Agent by following the steps in the [quickstart](../../quickstart.md).
38+
39+
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:
40+
1. `server_url`: the url of the MCP server, for example, `https://api.githubcopilot.com/mcp/`
41+
2. `server_label`: a unique identifier of this MCP server to the agent, for example, `github`
42+
3. `require_approval`: only `never` is supported right now
43+
44+
1. Create a run and pass additional information about the `mcp` tool in `tool_resources` with headers
45+
1. `tool_label`: use the identifier you provided during create/update agent
46+
2. `headers`: pass a set of headers required by the MCP server
47+
48+
## Next steps
49+
50+
* [How to use the MCP tool](./mcp-samples.md)

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ To streamline workflows with your AI agent with capabilities to take actions. Th
3232

3333
- **Azure Logic Apps**: Low-code / no-code solution to add a workflow to your AI Agent
3434
- **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.
35+
- **MCP tool**: Bring an existing Model Context Protocol (MCP) endpoint that you want to add to your AI agent.
3536
- **Function calling**: Write your own custom, stateless functions to define the expected behaviors.
3637
- **Azure Functions**: Write and manage your own custom, stateful functions.
3738

@@ -75,6 +76,7 @@ The Foundry Agent Service provides the following built-in tools. You can use the
7576
|[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. |
7677
|[Grounding with Bing Search](bing-grounding.md) | Enable your agent to use Grounding with Bing Search to access and return information from the internet. |
7778
| [Grounding with Bing Custom Search (preview)](bing-custom-search.md) | Enhance your Agent response with selected web domains |
79+
| [Model Context Protocol (preview)](model-context-protocol.md) | Give the agent access to tools hosted on an existing MCP endpoint |
7880
| [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. |
7981
| [OpenAPI 3.0 Specified tool ](openapi-spec.md) | Connect your Azure AI Agent to external APIs using functions with an OpenAPI 3.0 specification. |
8082

‎articles/ai-foundry/agents/toc.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,14 @@ items:
8686
href: how-to/tools/openapi-spec-samples.md
8787
- name: Invoke an OpenAPI App Service web app
8888
href: /azure/app-service/invoke-openapi-web-app-from-azure-ai-agent-service?context=/azure/ai-services/agents/context/context
89+
- name: Model Context Protocol(MCP)
90+
items:
91+
- name: Overview
92+
href: how-to/tools/mcp.md
93+
displayName: model context protocol, mcp
94+
- name: How to use Model Context Protocol
95+
displayName: model context protocol, mcp samples
96+
href: how-to/tools/mcp-samples.md
8997
- name: Azure Functions
9098
items:
9199
- name: Overview

0 commit comments

Comments
 (0)