5.13 Azure AI Foundry Agent Integration

Model Context Protocol (MCP) Integration with Azure AI Foundry

This guide demonstrates how to integrate Model Context Protocol (MCP) servers with Azure AI 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 Azure AI 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 Azure AI Foundry's robust agent framework, providing enterprise-grade AI solutions with extensive customization capabilities.

Note: If you want to use MCP in Azure AI 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:

Prerequisites

Before starting, ensure you have:

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:

Setting Up MCP with Azure AI Foundry

Environment Configuration

Choose your preferred development environment:

---

Python Implementation

*Note* You can run this notebook

1. Install Required Packages

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

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

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

project_client = AIProjectClient(

    endpoint="https://your-project-endpoint.services.ai.azure.com/api/projects/your-project",

    credential=DefaultAzureCredential(),

)

5. Create MCP Tool

mcp_tool = McpTool(

    server_label=mcp_server_label,

    server_url=mcp_server_url,

    allowed_tools=[],  # Optional: specify allowed tools

)

6. Complete Python Example

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

1. Install Required Packages

#r "nuget: Azure.AI.Agents.Persistent, 1.1.0-beta.4"

#r "nuget: Azure.Identity, 1.14.2"

2. Import Dependencies

using Azure.AI.Agents.Persistent;

using Azure.Identity;

3. Configure Settings

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

MCPToolDefinition mcpTool = new(mcpServerLabel, mcpServerUrl);

5. Create Agent with MCP Tools

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

// 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

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

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

mcp_tool.update_headers("SuperSecret", "123456")

.NET

MCPToolResource mcpToolResource = new(mcpServerLabel);

mcpToolResource.UpdateHeader("SuperSecret", "123456");

Troubleshooting Common Issues

1. Connection Issues

2. Tool Call Failures

3. Performance Issues

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

Support

For additional support and questions:

What's next