wehub-resource-sync
379 lines
12 KiB
Markdown
379 lines
12 KiB
Markdown
# Model Context Protocol (MCP) Integration with Microsoft Foundry
|
|
|
|
This guide demonstrates how to integrate Model Context Protocol (MCP) servers with Microsoft Foundry agents, enabling powerful tool orchestration and enterprise AI capabilities.
|
|
|
|
## Introduction
|
|
|
|
Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. When integrated with Microsoft Foundry, MCP allows agents to access and interact with various external services, APIs, and data sources in a standardized way.
|
|
|
|
This integration combines the flexibility of MCP's tool ecosystem with Microsoft Foundry's robust agent framework, providing enterprise-grade AI solutions with extensive customization capabilities.
|
|
|
|
**Note:** If you want to use MCP in Microsoft Foundry Agent Service, currently only the following regions are supported: westus, westus2, uaenorth, southindia and switzerlandnorth
|
|
|
|
## Learning Objectives
|
|
|
|
By the end of this guide, you will be able to:
|
|
|
|
- Understand the Model Context Protocol and its benefits
|
|
- Set up MCP servers for use with Microsoft Foundry agents
|
|
- Create and configure agents with MCP tool integration
|
|
- Implement practical examples using real MCP servers
|
|
- Handle tool responses and citations in agent conversations
|
|
|
|
## Prerequisites
|
|
|
|
Before starting, ensure you have:
|
|
|
|
- An Azure subscription with Microsoft Foundry access
|
|
- Python 3.10+ or .NET 8.0+
|
|
- Azure CLI installed and configured
|
|
- Appropriate permissions to create AI resources
|
|
|
|
## What is Model Context Protocol (MCP)?
|
|
|
|
Model Context Protocol is a standardized way for AI applications to connect to external data sources and tools. Key benefits include:
|
|
|
|
- **Standardized Integration**: Consistent interface across different tools and services
|
|
- **Security**: Secure authentication and authorization mechanisms
|
|
- **Flexibility**: Support for various data sources, APIs, and custom tools
|
|
- **Extensibility**: Easy to add new capabilities and integrations
|
|
|
|
## Setting Up MCP with Microsoft Foundry
|
|
|
|
### Environment Configuration
|
|
|
|
Choose your preferred development environment:
|
|
|
|
- [Python Implementation](#python-implementation)
|
|
- [.NET Implementation](#net-implementation)
|
|
|
|
---
|
|
|
|
## Python Implementation
|
|
|
|
***Note*** You can run this [notebook](./mcp_support_python.ipynb)
|
|
|
|
### 1. Install Required Packages
|
|
|
|
```bash
|
|
pip install azure-ai-projects -U
|
|
pip install azure-ai-agents==1.1.0b4 -U
|
|
pip install azure-identity -U
|
|
pip install mcp==1.11.0 -U
|
|
```
|
|
|
|
### 2. Import Dependencies
|
|
|
|
```python
|
|
import os, time
|
|
from azure.ai.projects import AIProjectClient
|
|
from azure.identity import DefaultAzureCredential
|
|
from azure.ai.agents.models import McpTool, RequiredMcpToolCall, SubmitToolApprovalAction, ToolApproval
|
|
```
|
|
|
|
### 3. Configure MCP Settings
|
|
|
|
```python
|
|
mcp_server_url = os.environ.get("MCP_SERVER_URL", "https://learn.microsoft.com/api/mcp")
|
|
mcp_server_label = os.environ.get("MCP_SERVER_LABEL", "mslearn")
|
|
```
|
|
|
|
### 4. Initialize Project Client
|
|
|
|
```python
|
|
project_client = AIProjectClient(
|
|
endpoint="https://your-project-endpoint.services.ai.azure.com/api/projects/your-project",
|
|
credential=DefaultAzureCredential(),
|
|
)
|
|
```
|
|
|
|
### 5. Create MCP Tool
|
|
|
|
```python
|
|
mcp_tool = McpTool(
|
|
server_label=mcp_server_label,
|
|
server_url=mcp_server_url,
|
|
allowed_tools=[], # Optional: specify allowed tools
|
|
)
|
|
```
|
|
|
|
### 6. Complete Python Example
|
|
|
|
```python
|
|
with project_client:
|
|
agents_client = project_client.agents
|
|
|
|
# Create a new agent with MCP tools
|
|
agent = agents_client.create_agent(
|
|
model="Your AOAI Model Deployment",
|
|
name="my-mcp-agent",
|
|
instructions="You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
|
|
tools=mcp_tool.definitions,
|
|
)
|
|
print(f"Created agent, ID: {agent.id}")
|
|
print(f"MCP Server: {mcp_tool.server_label} at {mcp_tool.server_url}")
|
|
|
|
# Create thread for communication
|
|
thread = agents_client.threads.create()
|
|
print(f"Created thread, ID: {thread.id}")
|
|
|
|
# Create message to thread
|
|
message = agents_client.messages.create(
|
|
thread_id=thread.id,
|
|
role="user",
|
|
content="What's difference between Azure OpenAI and OpenAI?",
|
|
)
|
|
print(f"Created message, ID: {message.id}")
|
|
|
|
# Handle tool approvals and run agent
|
|
mcp_tool.update_headers("SuperSecret", "123456")
|
|
run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)
|
|
print(f"Created run, ID: {run.id}")
|
|
|
|
while run.status in ["queued", "in_progress", "requires_action"]:
|
|
time.sleep(1)
|
|
run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)
|
|
|
|
if run.status == "requires_action" and isinstance(run.required_action, SubmitToolApprovalAction):
|
|
tool_calls = run.required_action.submit_tool_approval.tool_calls
|
|
if not tool_calls:
|
|
print("No tool calls provided - cancelling run")
|
|
agents_client.runs.cancel(thread_id=thread.id, run_id=run.id)
|
|
break
|
|
|
|
tool_approvals = []
|
|
for tool_call in tool_calls:
|
|
if isinstance(tool_call, RequiredMcpToolCall):
|
|
try:
|
|
print(f"Approving tool call: {tool_call}")
|
|
tool_approvals.append(
|
|
ToolApproval(
|
|
tool_call_id=tool_call.id,
|
|
approve=True,
|
|
headers=mcp_tool.headers,
|
|
)
|
|
)
|
|
except Exception as e:
|
|
print(f"Error approving tool_call {tool_call.id}: {e}")
|
|
|
|
if tool_approvals:
|
|
agents_client.runs.submit_tool_outputs(
|
|
thread_id=thread.id, run_id=run.id, tool_approvals=tool_approvals
|
|
)
|
|
|
|
print(f"Current run status: {run.status}")
|
|
|
|
print(f"Run completed with status: {run.status}")
|
|
|
|
# Display conversation
|
|
messages = agents_client.messages.list(thread_id=thread.id)
|
|
print("\nConversation:")
|
|
print("-" * 50)
|
|
for msg in messages:
|
|
if msg.text_messages:
|
|
last_text = msg.text_messages[-1]
|
|
print(f"{msg.role.upper()}: {last_text.text.value}")
|
|
print("-" * 50)
|
|
```
|
|
|
|
---
|
|
|
|
## .NET Implementation
|
|
|
|
***Note*** You can run this [notebook](./mcp_support_dotnet.ipynb)
|
|
|
|
### 1. Install Required Packages
|
|
|
|
```csharp
|
|
#r "nuget: Azure.AI.Agents.Persistent, 1.1.0-beta.4"
|
|
#r "nuget: Azure.Identity, 1.14.2"
|
|
```
|
|
|
|
### 2. Import Dependencies
|
|
|
|
```csharp
|
|
using Azure.AI.Agents.Persistent;
|
|
using Azure.Identity;
|
|
```
|
|
|
|
### 3. Configure Settings
|
|
|
|
```csharp
|
|
var projectEndpoint = "https://your-project-endpoint.services.ai.azure.com/api/projects/your-project";
|
|
var modelDeploymentName = "Your AOAI Model Deployment";
|
|
var mcpServerUrl = "https://learn.microsoft.com/api/mcp";
|
|
var mcpServerLabel = "mslearn";
|
|
PersistentAgentsClient agentClient = new(projectEndpoint, new DefaultAzureCredential());
|
|
```
|
|
|
|
### 4. Create MCP Tool Definition
|
|
|
|
```csharp
|
|
MCPToolDefinition mcpTool = new(mcpServerLabel, mcpServerUrl);
|
|
```
|
|
|
|
### 5. Create Agent with MCP Tools
|
|
|
|
```csharp
|
|
PersistentAgent agent = await agentClient.Administration.CreateAgentAsync(
|
|
model: modelDeploymentName,
|
|
name: "my-learn-agent",
|
|
instructions: "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
|
|
tools: [mcpTool]
|
|
);
|
|
```
|
|
|
|
### 6. Complete .NET Example
|
|
|
|
```csharp
|
|
// Create thread and message
|
|
PersistentAgentThread thread = await agentClient.Threads.CreateThreadAsync();
|
|
|
|
PersistentThreadMessage message = await agentClient.Messages.CreateMessageAsync(
|
|
thread.Id,
|
|
MessageRole.User,
|
|
"What's difference between Azure OpenAI and OpenAI?");
|
|
|
|
// Configure tool resources with headers
|
|
MCPToolResource mcpToolResource = new(mcpServerLabel);
|
|
mcpToolResource.UpdateHeader("SuperSecret", "123456");
|
|
ToolResources toolResources = mcpToolResource.ToToolResources();
|
|
|
|
// Create and handle run
|
|
ThreadRun run = await agentClient.Runs.CreateRunAsync(thread, agent, toolResources);
|
|
|
|
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress || run.Status == RunStatus.RequiresAction)
|
|
{
|
|
await Task.Delay(TimeSpan.FromMilliseconds(1000));
|
|
run = await agentClient.Runs.GetRunAsync(thread.Id, run.Id);
|
|
|
|
if (run.Status == RunStatus.RequiresAction && run.RequiredAction is SubmitToolApprovalAction toolApprovalAction)
|
|
{
|
|
var toolApprovals = new List<ToolApproval>();
|
|
foreach (var toolCall in toolApprovalAction.SubmitToolApproval.ToolCalls)
|
|
{
|
|
if (toolCall is RequiredMcpToolCall mcpToolCall)
|
|
{
|
|
Console.WriteLine($"Approving MCP tool call: {mcpToolCall.Name}");
|
|
toolApprovals.Add(new ToolApproval(mcpToolCall.Id, approve: true)
|
|
{
|
|
Headers = { ["SuperSecret"] = "123456" }
|
|
});
|
|
}
|
|
}
|
|
|
|
if (toolApprovals.Count > 0)
|
|
{
|
|
run = await agentClient.Runs.SubmitToolOutputsToRunAsync(thread.Id, run.Id, toolApprovals: toolApprovals);
|
|
}
|
|
}
|
|
}
|
|
|
|
// Display messages
|
|
using Azure;
|
|
|
|
AsyncPageable<PersistentThreadMessage> messages = agentClient.Messages.GetMessagesAsync(
|
|
threadId: thread.Id,
|
|
order: ListSortOrder.Ascending
|
|
);
|
|
|
|
await foreach (PersistentThreadMessage threadMessage in messages)
|
|
{
|
|
Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
|
|
foreach (MessageContent contentItem in threadMessage.ContentItems)
|
|
{
|
|
if (contentItem is MessageTextContent textItem)
|
|
{
|
|
Console.Write(textItem.Text);
|
|
}
|
|
else if (contentItem is MessageImageFileContent imageFileItem)
|
|
{
|
|
Console.Write($"<image from ID: {imageFileItem.FileId}>");
|
|
}
|
|
Console.WriteLine();
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## MCP Tool Configuration Options
|
|
|
|
When configuring MCP tools for your agent, you can specify several important parameters:
|
|
|
|
### Python Configuration
|
|
|
|
```python
|
|
mcp_tool = McpTool(
|
|
server_label="unique_server_name", # Identifier for the MCP server
|
|
server_url="https://api.example.com/mcp", # MCP server endpoint
|
|
allowed_tools=[], # Optional: specify allowed tools
|
|
)
|
|
```
|
|
|
|
### .NET Configuration
|
|
|
|
```csharp
|
|
MCPToolDefinition mcpTool = new(
|
|
"unique_server_name", // Server label
|
|
"https://api.example.com/mcp" // MCP server URL
|
|
);
|
|
```
|
|
|
|
## Authentication and Headers
|
|
|
|
Both implementations support custom headers for authentication:
|
|
|
|
### Python
|
|
```python
|
|
mcp_tool.update_headers("SuperSecret", "123456")
|
|
```
|
|
|
|
### .NET
|
|
```csharp
|
|
MCPToolResource mcpToolResource = new(mcpServerLabel);
|
|
mcpToolResource.UpdateHeader("SuperSecret", "123456");
|
|
```
|
|
|
|
## Troubleshooting Common Issues
|
|
|
|
### 1. Connection Issues
|
|
- Verify MCP server URL is accessible
|
|
- Check authentication credentials
|
|
- Ensure network connectivity
|
|
|
|
### 2. Tool Call Failures
|
|
- Review tool arguments and formatting
|
|
- Check server-specific requirements
|
|
- Implement proper error handling
|
|
|
|
### 3. Performance Issues
|
|
- Optimize tool call frequency
|
|
- Implement caching where appropriate
|
|
- Monitor server response times
|
|
|
|
## Next Steps
|
|
|
|
To further enhance your MCP integration:
|
|
|
|
1. **Explore Custom MCP Servers**: Build your own MCP servers for proprietary data sources
|
|
2. **Implement Advanced Security**: Add OAuth2 or custom authentication mechanisms
|
|
3. **Monitor and Analytics**: Implement logging and monitoring for tool usage
|
|
4. **Scale Your Solution**: Consider load balancing and distributed MCP server architectures
|
|
|
|
## Additional Resources
|
|
|
|
- [Microsoft Foundry Documentation](https://learn.microsoft.com/azure/ai-foundry/)
|
|
- [Model Context Protocol Samples](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/model-context-protocol-samples)
|
|
- [Microsoft Foundry Agents Overview](https://learn.microsoft.com/azure/ai-foundry/agents/)
|
|
- [MCP Specification](https://spec.modelcontextprotocol.io/)
|
|
|
|
## Support
|
|
|
|
For additional support and questions:
|
|
- Review the [Microsoft Foundry documentation](https://learn.microsoft.com/azure/ai-foundry/)
|
|
- Check the [MCP community resources](https://modelcontextprotocol.io/)
|
|
|
|
## What's next
|
|
|
|
- [5.14 MCP Context Engineering](../mcp-contextengineering/README.md) |