مشاركة عبر

ربط الوكلاء بخوادم بروتوكول السياق النموذجي

قم بربط وكلاء Foundry الخاص بك بخوادم بروتوكول السياق النموذجي (MCP) باستخدام أداة MCP. هذا يوسع قدرات الوكيل من خلال الأدوات الخارجية ومصادر البيانات. من خلال الاتصال بنقاط نهاية خوادم MCP البعيدة، يمكن لوكلائك الوصول إلى أدوات مستضافة من قبل المطورين والمؤسسات التي يمكن لعملاء متوافقين مع MCP مثل Foundry Agent Service استخدامها.

MCP هو معيار مفتوح يحدد كيفية توفير التطبيقات للأدوات والبيانات السياقية لنماذج اللغات الكبيرة (LLMs). فهو يتيح تكاملا متسقا وقابلا للتطوير للأدوات الخارجية في مهام سير عمل النموذج.

في هذه المقالة، ستتعرف على كيفية:

  • أضف خادم MCP بعيد كأداة.
  • قم بالتحقق من المصادقة على خادم MCP باستخدام اتصال المشروع.
  • راجع ووافق على استدعاءات أدوات MCP.
  • استكشاف مشاكل التكامل الشائعة مع MCP.

للحصول على تفاصيل مفاهيمية حول كيفية عمل تكامل MCP، راجع كيف يعمل.

دعم الاستخدام

يوضح الجدول التالي دعم SDK وإعداد اتصالات MCP. ✔️ (GA) تشير إلى التوفر العام، ✔️ (معاينة) تشير إلى معاينة عامة، وشرطة شرطة (-) تشير إلى عدم توفر الميزة.

دعم مايكروسوفت فاوندري حزمة تطوير التطوير الخاصة لبايثون C # SDK حزمة تطوير جافاسكريبت مجموعة تطوير جافا واجهة برمجة تطبيقات REST إعداد العامل الأساسي إعداد العامل القياسي
✔️ ✔️ (GA) ✔️ (معاينة) ✔️ (GA) ✔️ (معاينة) ✔️ (GA) ✔️ ✔️

المتطلبات المسبقه

قبل أن تبدأ، تأكد من أن لديك:

  • اشتراك في Azure مع مشروع نشط في Microsoft Foundry.
  • التحكم في الوصول القائم على الدور في Azure (RBAC): دور المساهم أو المالك في مشروع Foundry.
  • أحدث حزمة SDK للغتك. مجموعات تطوير .NET و Java حاليا قيد المعاينة. راجع البدء السريع لتفاصيل التثبيت.
  • Azure بيانات اعتماد مهيأة للمصادقة (مثل DefaultAzureCredential).
  • الوصول إلى نقطة نهاية خادم MCP بعيد (مثل خادم MCP الخاص ب GitHub عند https://api.githubcopilot.com/mcp).

نقاط نهاية خوادم MCP العامة والخاصة

تدعم خدمة الوكلاء كلا من نقاط نهاية خوادم MCP العامة والخاصة:

  • نقاط النهاية العامة: اتصل بأي خادم MCP بعيد متاح للعامة. يعمل هذا الخيار مع إعدادات الوكيل الأساسية والقياسية معا.
  • نقاط النهاية الخاصة: اتصل بخوادم MCP غير معرضة للإنترنت العام. يتطلب MCP الخاص إعداد وكيل قياسي مع شبكة خاصة وشبكة فرعية مخصصة لشبكة MCP داخل شبكتك الافتراضية.

بالنسبة لخوادم MCP الخاصة، قم بنشر خادم MCP الخاص بك على تطبيقات Azure Container مع إدخال داخلي فقط على شبكة فرعية مخصصة ل MCP مفوضة ل Microsoft.App/environments. للبدء، استخدم قالب إعداد 19 هجينا للموارد الخاصة والوكيل ، والذي يوفر البنية التحتية للشبكة المطلوبة بما في ذلك شبكة MCP الفرعية.

للحصول على تفاصيل حول دعم الأدوات في البيئات المعزولة للشبكة، راجع أدوات الوكلاء مع عزل الشبكة.

المصادقة

تتطلب العديد من خوادم MCP المصادقة.

في خدمة Foundry Agent، استخدم اتصال المشروع لتخزين تفاصيل المصادقة (مثل مفاتيح API أو رموز الحامل) بدلا من برمجة بيانات الاعتماد بشكل ثابت في تطبيقك.

للتعرف على خيارات المصادقة المدعومة (القائمة على المفاتيح، هويات Microsoft Entra، وتمرير هوية OAuth)، راجع MCP Server authentication.

‏‫ملاحظة‬

قم بتعيينه project_connection_id على معرف اتصال مشروعك.

نصيحة

عند إضافة خادم Azure DevOps MCP (المعاينة) من خلال كتالوج أدوات الإضافة ، يتم إنشاء المصادقة إلى Azure DevOps أثناء خطوة الاتصال التنظيمي وتخزينها كاتصال مشروع. استخدم الوصول ذو الصلاحيات الأقل ومراجعة نطاقات عند ربط المنظمة.

اعتبارات استخدام الخدمات والخوادم غير التابعة ل Microsoft

أنت خاضع للشروط بينك وبين مزود الخدمة عند استخدامك لخدمات غير متصلة بمايكروسوفت. عندما تتصل بخدمة غير تابعة لمايكروسوفت، تمرر بعض بياناتك (مثل محتوى الطلب) إلى الخدمة غير التابعة لمايكروسوفت، أو قد يتلقى تطبيقك بيانات من الخدمة غير التابعة لمايكروسوفت. أنت مسؤول عن استخدامك للخدمات والبيانات غير التابعة ل Microsoft، بالإضافة إلى أي رسوم مرتبطة بهذا الاستخدام.

الأطراف الثالثة، وليس مايكروسوفت، هي التي تنشئ خوادم MCP البعيدة التي تقرر استخدامها باستخدام أداة MCP الموضحة في هذا المقال. لا تختبر Microsoft هذه الخوادم أو تتحقق منها. لا تتحمل Microsoft أي مسؤولية تجاهك أو تجاه الآخرين فيما يتعلق باستخدامك لأي خوادم MCP بعيدة.

راجع بعناية وتتبع خوادم MCP التي تضيفها إلى خدمة وكلاء المسبك. اعتمد على الخوادم التي يستضيفها مزودو خدمة موثوقون بدلا من البروكسيات.

تسمح لك أداة MCP بتمرير عناوين مخصصة، مثل مفاتيح المصادقة أو المخططات، التي قد يحتاجها خادم MCP البعيد. راجع جميع البيانات التي تشاركها مع خوادم MCP البعيدة وسجل البيانات لأغراض التدقيق. كن على علم بالممارسات غير التابعة لمايكروسوفت للاحتفاظ بالبيانات وتحديد موقعها.

أفضل الممارسات

للحصول على إرشادات عامة حول استخدام الأدوات، راجع أفضل الممارسات لاستخدام الأدوات في خدمة وكلاء مايكروسوفت فاوندري.

عند استخدام خوادم MCP، اتبع هذه الممارسات:

  • أفضل قائمة مسموح بالأدوات باستخدام allowed_tools.
  • يتطلب الموافقة على العمليات عالية المخاطر (خاصة الأدوات التي تكتب البيانات أو تغير الموارد).
  • راجع اسم الأداة المطلوبة والحجج قبل الموافقة.
  • الموافقات على السجلات واستدعاءات الأدوات للتدقيق وحل المشكلة.

نصيحة

عند إضافة خادم Azure DevOps MCP من خلال كتالوج Add-Tools ، فإن تكوين اختيار الأدوات يتطابق مع السلوك allowed_tools الموضح في هذا المقال. اختيار مجموعة فرعية من الأدوات في واجهة الفهرس يعادل تحديد allowed_tools قائمة في الكود.

أنشئ وكيل بلغة Python باستخدام أداة MCP

استخدم نموذج التعليمات البرمجية التالي لإنشاء عامل واستدعاء الوظيفة. مجموعات تطوير .NET و Java حاليا قيد المعاينة. راجع البداية السريعة للتفاصيل.

يوضح المثال التالي كيفية استخدام خادم GitHub MCP كأداة لوكيل.

import json
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool
from openai.types.responses.response_input_param import McpApprovalResponse, ResponseInputParam

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
MCP_CONNECTION_NAME = "my-mcp-connection"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# [START tool_declaration]
tool = MCPTool(
    server_label="api-specs",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id=MCP_CONNECTION_NAME,
)
# [END tool_declaration]

# Create a prompt agent with MCP tool capabilities
agent = project.agents.create_version(
    agent_name="MyAgent7",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="Use MCP tools as needed",
        tools=[tool],
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Create a conversation to maintain context across multiple interactions
conversation = openai.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Send initial request that will trigger the MCP tool
response = openai.responses.create(
    conversation=conversation.id,
    input="What is my username in my GitHub profile?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

# Process any MCP approval requests that were generated
input_list: ResponseInputParam = []
for item in response.output:
    if item.type == "mcp_approval_request" and item.id:
        print("MCP approval requested")
        print(f"  Server: {item.server_label}")
        print(f"  Tool: {getattr(item, 'name', '<unknown>')}")
        print(
            f"  Arguments: {json.dumps(getattr(item, 'arguments', None), indent=2, default=str)}"
        )

        # Approve only after you review the tool call.
        # In production, implement your own approval UX and policy.
        should_approve = (
            input("Approve this MCP tool call? (y/N): ").strip().lower() == "y"
        )
        input_list.append(
            McpApprovalResponse(
                type="mcp_approval_response",
                approve=should_approve,
                approval_request_id=item.id,
            )
        )

# Send the approval response back to continue the agent's work
response = openai.responses.create(
    input=input_list,
    previous_response_id=response.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response: {response.output_text}")

# Clean up resources by deleting the agent version
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

الإخراج المتوقع

المثال التالي يوضح الناتج المتوقع عند تشغيل العينة:

Agent created (id: <agent-id>, name: MyAgent7, version: 1)
Created conversation (id: <conversation-id>)
Response: Your GitHub username is "example-username".
Agent deleted

إنشاء وكيل باستخدام أداة MCP

يوضح المثال التالي كيفية استخدام خادم GitHub MCP كأداة لوكيل. يستخدم المثال طرقا متزامنة لإنشاء وكيل. للطرق غير المتزامنة، راجع sample code في Azure SDK المستودع .NET على GitHub.

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create Agent with the `MCPTool`. Note that in this scenario 
// GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval is used,
// which means that any calls to the MCP server must be approved.
PromptAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    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 = { ResponseTool.CreateMcpTool(
        serverLabel: "api-specs",
        serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
    )) }
};
AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// If the tool approval is required, the response item is
// of `McpToolCallApprovalRequestItem` type and contains all
// the information about tool call. This example checks that
// the server label is "api-specs" and approves the tool call.
// All other calls are denied because they should not occur for
// the current configuration.
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);

CreateResponseOptions nextResponseOptions = new([ResponseItem.CreateUserMessageItem("Please summarize the Azure REST API specifications README")]);
ResponseResult latestResponse = null;

while (nextResponseOptions is not null)
{
    latestResponse = responseClient.CreateResponse(nextResponseOptions);
    nextResponseOptions = null;

    foreach (ResponseItem responseItem in latestResponse.OutputItems)
    {
        if (responseItem is McpToolCallApprovalRequestItem mcpToolCall)
        {
            nextResponseOptions = new CreateResponseOptions()
            {
                PreviousResponseId = latestResponse.Id,
            };
            if (string.Equals(mcpToolCall.ServerLabel, "api-specs"))
            {
                Console.WriteLine($"Approval requested for {mcpToolCall.ServerLabel} (tool: {mcpToolCall.ToolName})");
                Console.Write("Approve this MCP tool call? (y/N): ");
                bool approved = string.Equals(Console.ReadLine(), "y", StringComparison.OrdinalIgnoreCase);
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: approved));
            }
            else
            {
                Console.WriteLine($"Rejecting unknown call {mcpToolCall.ServerLabel}...");
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: false));
            }
        }
    }
}

// Output the final response from the agent.
Console.WriteLine(latestResponse.GetOutputText());

// Clean up resources by deleting the agent version.
projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

الإخراج المتوقع

المثال التالي يوضح الناتج المتوقع عند تشغيل العينة:

Approval requested for api-specs...
Response: The Azure REST API specifications repository contains the OpenAPI specifications for Azure services. It is
organized by service and includes guidelines for contributing new specifications. The repository is intended for use by developers building tools and services that interact with Azure APIs.

أنشئ وكيلا باستخدام أداة MCP باستخدام مصادقة اتصال المشروع

في هذا المثال، تتعلم كيفية المصادقة على خادم GitHub MCP وتستخدمه كأداة لوكيل. يستخدم المثال طرقا متزامنة لإنشاء وكيل. للطرق غير المتزامنة، راجع sample code في Azure SDK المستودع .NET على GitHub.

إنشاء اتصال المشروع

قبل تشغيل العينة:

  1. سجل الدخول إلى ملفك الشخصي في GitHub.
  2. اختر صورة الملف الشخصي في الزاوية العلوية اليمنى.
  3. حدد الإعدادات.
  4. في اللوحة اليسرى، اختر إعدادات المطورورموز > الوصول الشخصي (كلاسيك).
  5. في الأعلى، اختر إنشاء رمز جديد، أدخل كلمة المرور، وأنشئ رمزا يمكنه قراءة المستودعات العامة.
    • مهم: احفظ الرمز، أو أبق الصفحة مفتوحة لأنه بمجرد إغلاق الصفحة، لا يمكن عرض الرمز مرة أخرى.
  6. في بوابة Azure، افتح Microsoft Foundry.
  7. في اللوحة اليسرى، اختر مركز الإدارة ثم اختر الموارد المتصلة.
  8. أنشئ اتصالا جديدا من نوع مفاتيح مخصصة .
  9. اذكر وأضف زوج قيم مفتاح.
  10. قم بتعيين اسم المفتاح إلى Authorization ويجب أن يكون للقيمة شكل من Bearer your_github_token.

عينة كود لإنشاء الوكيل

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var mcpConnectionName = "my-mcp-connection";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create an agent with the MCPTool. Note that, in this scenario,
// GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval is used.
// This means that any calls to the MCP server must be approved.
// The ProjectConnectionId property is then set on the McpTool
// so agent can authenticate with GitHub.
McpTool tool = ResponseTool.CreateMcpTool(
        serverLabel: "api-specs",
        serverUri: new Uri("https://api.githubcopilot.com/mcp"),
        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
    ));
tool.ProjectConnectionId = mcpConnectionName;
PromptAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    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 = { tool }
};
AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// If the tool approval is required, the response item is
// of McpToolCallApprovalRequestItem type and contains all
// the information about tool call. This example checks that
// the server label is "api-specs" and approves the tool call,
// All other calls are denied because they shouldn't happen given
// the current configuration.
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);

CreateResponseOptions nextResponseOptions = new([ResponseItem.CreateUserMessageItem("What is my username in my GitHub profile?")]);
ResponseResult latestResponse = null;

while (nextResponseOptions is not null)
{
    latestResponse = responseClient.CreateResponse(nextResponseOptions);
    nextResponseOptions = null;

    foreach (ResponseItem responseItem in latestResponse.OutputItems)
    {
        if (responseItem is McpToolCallApprovalRequestItem mcpToolCall)
        {
            nextResponseOptions = new()
            {
                PreviousResponseId = latestResponse.Id,
            };
            if (string.Equals(mcpToolCall.ServerLabel, "api-specs"))
            {
                Console.WriteLine($"Approval requested for {mcpToolCall.ServerLabel} (tool: {mcpToolCall.ToolName})");
                Console.Write("Approve this MCP tool call? (y/N): ");
                bool approved = string.Equals(Console.ReadLine(), "y", StringComparison.OrdinalIgnoreCase);
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: approved));
            }
            else
            {
                Console.WriteLine($"Rejecting unknown call {mcpToolCall.ServerLabel}...");
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: false));
            }
        }
    }
}

// Output the final response from the agent.
Console.WriteLine(latestResponse.GetOutputText());

// Clean up resources by deleting the agent version.
projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

الإخراج المتوقع

المثال التالي يوضح الناتج المتوقع عند تشغيل العينة:

Approval requested for api-specs...
Response: Your GitHub username is "example-username".

إنشاء وكيل في TypeScript باستخدام أداة MCP

توضح العينة التالية من TypeScript كيفية إنشاء وكيل بقدرات أداة MCP، وإرسال طلبات تفعل سير عمل الموافقة على MCP، والتعامل مع طلبات الموافقة، وتنظيف الموارد. للحصول على نسخة جافاسكريبت، راجع sample code في Azure SDK مستودع JavaScript على GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import OpenAI from "openai";
import * as readline from "readline";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating agent with MCP tool...");

  // Define MCP tool that connects to Azure REST API specifications GitHub repository
  // The tool requires approval for each operation to ensure user control over external requests
  const agent = await project.agents.createVersion("agent-mcp", {
    kind: "prompt",
    model: "gpt-5-mini",
    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: [
      {
        type: "mcp",
        server_label: "api-specs",
        server_url: "https://gitmcp.io/Azure/azure-rest-api-specs",
        require_approval: "always",
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Create a conversation thread to maintain context across multiple interactions
  console.log("\nCreating conversation...");
  const conversation = await openai.conversations.create();
  console.log(`Created conversation (id: ${conversation.id})`);

  // Send initial request that will trigger the MCP tool to access Azure REST API specs
  // This will generate an approval request since requireApproval="always"
  console.log("\nSending request that will trigger MCP approval...");
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Please summarize the Azure REST API specifications Readme",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  // Process any MCP approval requests that were generated
  // When requireApproval="always", the agent will request permission before accessing external resources
  const inputList: OpenAI.Responses.ResponseInputItem.McpApprovalResponse[] = [];

  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
  for (const item of response.output) {
    if (item.type === "mcp_approval_request") {
      if (item.server_label === "api-specs" && item.id) {
        console.log(`\nReceived MCP approval request (id: ${item.id})`);
        console.log(`  Server: ${item.server_label}`);
        console.log(`  Tool: ${item.name}`);

        // Approve only after you review the tool call.
        // In production, implement your own approval UX and policy.
        const answer = (await ask("Approve this MCP tool call? (y/N): ")).trim().toLowerCase();
        const approve = answer === "y";
        inputList.push({
          type: "mcp_approval_response",
          approval_request_id: item.id,
          approve,
        });
      }
    }
  }

  rl.close();

  console.log(`\nProcessing ${inputList.length} approval request(s)`);
  console.log("Final input:");
  console.log(JSON.stringify(inputList, null, 2));

  // Send the approval response back to continue the agent's work
  // This allows the MCP tool to access the GitHub repository and complete the original request
  console.log("\nSending approval response...");
  const finalResponse = await openai.responses.create(
    {
      input: inputList,
      previous_response_id: response.id,
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  console.log(`\nResponse: ${finalResponse.output_text}`);

  // Clean up resources by deleting the agent version and conversation
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await openai.conversations.delete(conversation.id);
  console.log("Conversation deleted");

  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nMCP sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

الإخراج المتوقع

المثال التالي يوضح الناتج المتوقع عند تشغيل العينة:

Creating agent with MCP tool...
Agent created (id: <agent-id>, name: agent-mcp, version: 1)

Creating conversation...
Created conversation (id: <conversation-id>)

Sending request that will trigger MCP approval...

Received MCP approval request (id: <approval-request-id>)
  Server: api-specs
  Tool: get-readme

Processing 1 approval request(s)
Final input:
[
  {
    "type": "mcp_approval_response",
    "approval_request_id": "<approval-request-id>",
    "approve": true
  }
]

Sending approval response...

Response: The Azure REST API specifications repository contains the OpenAPI specifications for Azure services. It is organized by service and includes guidelines for contributing new specifications. The repository is intended for use by developers building tools and services that interact with Azure APIs.

Cleaning up resources...
Conversation deleted
Agent deleted

MCP sample completed!

أنشئ وكيلا باستخدام أداة MCP باستخدام مصادقة اتصال المشروع

توضح عينة TypeScript التالية كيفية إنشاء وكيل بقدرات أداة MCP باستخدام مصادقة اتصال المشروع، وإرسال طلبات تفعل سير عمل الموافقة على MCP، والتعامل مع طلبات الموافقة، وتنظيف الموارد. للحصول على نسخة جافاسكريبت، راجع sample code في Azure SDK مستودع JavaScript على GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import OpenAI from "openai";
import * as readline from "readline";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const MCP_CONNECTION_NAME = "my-mcp-connection";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating agent with MCP tool using project connection...");

  // Define MCP tool that connects to GitHub Copilot API with project connection authentication
  // The project connection should have Authorization header configured with "Bearer <GitHub PAT token>"
  // Token can be created at https://github.com/settings/personal-access-tokens/new
  const agent = await project.agents.createVersion("agent-mcp-connection-auth", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "Use MCP tools as needed",
    tools: [
      {
        type: "mcp",
        server_label: "api-specs",
        server_url: "https://api.githubcopilot.com/mcp",
        require_approval: "always",
        project_connection_id: MCP_CONNECTION_NAME,
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Create a conversation thread to maintain context across multiple interactions
  console.log("\nCreating conversation...");
  const conversation = await openai.conversations.create();
  console.log(`Created conversation (id: ${conversation.id})`);

  // Send initial request that will trigger the MCP tool
  console.log("\nSending request that will trigger MCP approval...");
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "What is my username in my GitHub profile?",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  // Process any MCP approval requests that were generated
  const inputList: OpenAI.Responses.ResponseInputItem.McpApprovalResponse[] = [];

  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
  for (const item of response.output) {
    if (item.type === "mcp_approval_request") {
      if (item.server_label === "api-specs" && item.id) {
        console.log(`\nReceived MCP approval request (id: ${item.id})`);
        console.log(`  Server: ${item.server_label}`);
        console.log(`  Tool: ${item.name}`);

        // Approve only after you review the tool call.
        // In production, implement your own approval UX and policy.
        const answer = (await ask("Approve this MCP tool call? (y/N): ")).trim().toLowerCase();
        const approve = answer === "y";
        inputList.push({
          type: "mcp_approval_response",
          approval_request_id: item.id,
          approve,
        });
      }
    }
  }

  rl.close();

  console.log(`\nProcessing ${inputList.length} approval request(s)`);
  console.log("Final input:");
  console.log(JSON.stringify(inputList, null, 2));

  // Send the approval response back to continue the agent's work
  // This allows the MCP tool to access the GitHub repository and complete the original request
  console.log("\nSending approval response...");
  const finalResponse = await openai.responses.create(
    {
      input: inputList,
      previous_response_id: response.id,
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  console.log(`\nResponse: ${finalResponse.output_text}`);

  // Clean up resources by deleting the agent version and conversation
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await openai.conversations.delete(conversation.id);
  console.log("Conversation deleted");

  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nMCP with project connection sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

الإخراج المتوقع

المثال التالي يوضح الناتج المتوقع عند تشغيل العينة:

Creating agent with MCP tool using project connection...
Agent created (id: <agent-id>, name: agent-mcp-connection-auth, version: 1)
Creating conversation...
Created conversation (id: <conversation-id>)
Sending request that will trigger MCP approval...
Received MCP approval request (id: <approval-request-id>)
  Server: api-specs
  Tool: get-github-username
Processing 1 approval request(s)
Final input:
[
  {
    "type": "mcp_approval_response",
    "approval_request_id": "<approval-request-id>",
    "approve": true
  }
]
Sending approval response...
Response: Your GitHub username is "example-username".
Cleaning up resources...
Conversation deleted
Agent deleted
MCP with project connection sample completed!

استخدم أدوات MCP في وكيل Java

أضف الاعتماد إلى :pom.xml

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.0-beta.3</version>
</dependency>

إنشاء وكيل باستخدام أداة MCP

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.McpTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class McpToolExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String mcpConnectionName = "my-mcp-connection";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create MCP tool with server label, URL, connection, and approval mode
        McpTool mcpTool = new McpTool("api-specs")
            .setServerUrl("https://gitmcp.io/Azure/azure-rest-api-specs")
            .setProjectConnectionId(mcpConnectionName)
            .setRequireApproval("always");

        // Create agent with MCP tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a helpful assistant that can use MCP tools.")
            .setTools(Collections.singletonList(mcpTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("mcp-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("Summarize the Azure REST API specifications"));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

الإخراج المتوقع

Agent created: mcp-agent (version 1)
Response: [ResponseOutputItem containing MCP tool results ...]

استخدم أداة MCP مع واجهة برمجة تطبيقات REST

توضح الأمثلة التالية كيفية إنشاء وكيل باستخدام أداة MCP واستدعاؤه باستخدام واجهة برمجة تطبيقات الاستجابات. إذا تضمن الرد عنصر إخراج مع type تعيين على mcp_approval_request، أرسل طلب متابعة يتضمن mcp_approval_response عنصرا.

المتطلبات المسبقه

اضبط هذه المتغيرات البيئية:

  • FOUNDRY_PROJECT_ENDPOINT: رابط نقطة نهاية مشروعك.
  • FOUNDRY_MODEL_DEPLOYMENT_NAME: اسم نشر النموذج الخاص بك.
  • AGENT_TOKEN: رمز حامل للمفاهرة.
  • MCP_PROJECT_CONNECTION_NAME (اختياري): اسم اتصال مشروع MCP الخاص بك.

الحصول على رمز مميز للوصول:

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

إذا لم يتطلب خادم MCP الخاص بك المصادقة، قم بحذفها project_connection_id من جسم الطلب.

‏‫ملاحظة‬

بالنسبة لواجهة برمجة تطبيقات REST، تحتاج أولا إلى استرجاع معرف الاتصال من اسم الاتصال باستخدام واجهة برمجة تطبيقات الاتصالات، ثم تمرير المعرف إلى تكوين أداة MCP.

نصيحة

للحصول على تفاصيل حول مخطط أدوات MCP وعناصر الموافقة، راجع OpenAI.MCPTool وأنواع عناصر الموافقة MCP في مرجع REST.

1. إنشاء وكيل MCP

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "<AGENT_NAME>-mcp",
    "description": "MCP agent",
    "definition": {
      "kind": "prompt",
      "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
      "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": [
        {
          "type": "mcp",
          "server_label": "api-specs",
          "server_url": "https://gitmcp.io/Azure/azure-rest-api-specs",
          "require_approval": "never"
        }
      ]
    }
  }'

لاستخدام خادم MCP مصادق مع اتصال مشروع، أضف "project_connection_id": "'$MCP_PROJECT_CONNECTION_NAME'" إلى تعريف الأداة وغير server_url إلى نقطة نهاية الخادم المصادق (على سبيل المثال، https://api.githubcopilot.com/mcp).

2. إنشاء رد

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent": {"type": "agent_reference", "name": "<AGENT_NAME>-mcp"},
    "input": "Please summarize the Azure REST API specifications Readme"
  }'

إذا تضمن الرد عنصر إخراج مع type تعيين على mcp_approval_request، انسخ عنصر id طلب الموافقة ك APPROVAL_REQUEST_ID. وأيضا انسخ الرد id الأعلى ك PREVIOUS_RESPONSE_ID.

3. أرسل رد موافقة

إذا كانت أداة MCP تتطلب الموافقة، أرسل طلب متابعة:

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "previous_response_id": "'$PREVIOUS_RESPONSE_ID'",
    "input": [
      {
        "type": "mcp_approval_response",
        "approval_request_id": "'$APPROVAL_REQUEST_ID'",
        "approve": true
      }
    ]
  }'

4. تنظيف الموارد

حذف الوكيل:

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/<AGENT_NAME>-mcp?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

طريقة العمل

تحتاج إلى إحضار خادم MCP بعيد (نقطة نهاية خادم MCP موجودة) إلى Foundry Agent Service. يمكنك إحضار عدة خوادم MCP عن بعد عن طريق إضافتها كأدوات. لكل أداة، تحتاج إلى توفير قيمة فريدة server_label داخل نفس العامل وقيمة server_url تشير إلى خادم MCP البعيد. تأكد من مراجعة خوادم MCP التي تضيفها إلى Foundry Agent Service بعناية.

بالإضافة إلى ربط خوادم MCP البعيدة العشوائية حسب العنوان، يمكن إضافة بعض خوادم MCP مباشرة من كتالوج أدوات إضافة Foundry. على سبيل المثال، يتوفر Azure DevOps MCP Server (المعاينة) كمدخل كتالوج. تبسط إدخالات الكتالوج إعداد الاتصال وتتوافق مع نفس آليات الموافقة والتدقيق الموثقة في هذا المقال.

لمزيد من المعلومات حول استخدام MCP، راجع:

إعداد اتصال MCP

الخطوات التالية توضح كيفية الاتصال بخادم MCP بعيد من خدمة وكلاء Foundry:

  1. ابحث عن خادم MCP البعيد الذي تريد الاتصال به، مثل خادم GitHub MCP. إنشاء أو تحديث وكيل Foundry باستخدام mcp أداة باستخدام المعلومات التالية:
    1. server_url: عنوان URL لخادم MCP، مثل https://api.githubcopilot.com/mcp/.
    2. server_label: معرف فريد لهذا الخادم MCP للوكيل، مثل github.
    3. allowed_tools: قائمة اختيارية بالأدوات التي يمكن لهذا العامل الوصول إليها واستخدامها. إذا لم توفر هذه القيمة، فإن القيمة الافتراضية تشمل جميع الأدوات في خادم MCP.
    4. require_approval: حدد اختياريا ما إذا كانت الموافقة مطلوبة أم لا. القيمة الافتراضية هي always. القيم المدعومة هي:
      • always: يحتاج المطور إلى تقديم الموافقة على كل مكالمة. إذا لم تقدم قيمة، فهذه هي القيمة الافتراضية.
      • never: لا توجد موافقة مطلوبة.
      • {"never":[<tool_name_1>, <tool_name_2>]}: يمكنك توفير قائمة بالأدوات التي لا تتطلب الموافقة.
      • {"always":[<tool_name_1>, <tool_name_2>]}: يمكنك توفير قائمة بالأدوات التي تتطلب الموافقة.
  2. project_connection_idمعرف الاتصال بالمشروع الذي يخزن المصادقة وتفاصيل الاتصال الأخرى لخادم MCP.
  3. إذا حاول النموذج استدعاء أداة في خادم MCP الخاص بك مع الحاجة للموافقة، تحصل على نوع عنصر إخراج استجابة ك mcp_approval_request. في عنصر إخراج الاستجابة، يمكنك الحصول على مزيد من التفاصيل حول الأداة التي يتم استدعاؤها في خادم MCP والوسائط التي يجب تمريرها. راجع الأداة والوسيطات حتى تتمكن من اتخاذ قرار مستنير للموافقة عليها.
  4. قدم موافقتك إلى الوكيل باستخدام previous_response_id وضبط approve إلى true.

Connect to Azure DevOps MCP Server

يتوفر Azure DevOps MCP Server (المعاينة) كإدخال كتالوج في Foundry. لأضيف ذلك:

  1. في Foundry portal، اذهب إلى project الخاص بك.
  2. اختركتالوجإضافة الأدوات> وابحث عن "Azure DevOps".
  3. اختر Azure DevOps MCP Server (معاينة) واختر Create.
  4. أدخل اسم مؤسستك في Azure DevOps واختر Connect.
  5. اختر أي أدوات Azure DevOps لتعرضها لوكيلك. يمكنك اختيار مجموعة فرعية من الأدوات للتحكم بالضبط فيما يمكن للوكيل الوصول إليه.

هذا الإعداد القائم على الكتالوج ينشئ أداة MCP لاستخدامها من قبل الوكلاء دون الحاجة إلى تغييرات في الكود. يمكنك التحقق من الاتصال وسلوك الأدوات في تجربة اختبار الدردشة في Foundry قبل دمج الأداة في كود الإنتاج.

الحدود المعروفة

  • مهلة استدعاء أداة MCP غير المتدفقة: مكالمات أدوات MCP غير المتدفقة لها مهلة زمنية تبلغ 100 ثانية. إذا استغرق خادم MCP الخاص بك أكثر من 100 ثانية للرد، تفشل المكالمة. لتجنب انتهاء المهلات، تأكد من أن خادم MCP الخاص بك يستجيب ضمن هذا الحد. إذا كانت حالة استخدامك تتطلب أوقات معالجة أطول، فكر في تحسين منطق جانب الخادم أو تقسيم العملية إلى خطوات أصغر.
  • تمرير الهوية غير مدعوم في Teams: أدوات MCP التي تستخدم تمرير الهوية الافتراضي لا تعمل عند نشر الوكيل على Microsoft Teams. الوكلاء المنشورون على Teams يستخدمون هوية مدارة للمشروع للمصادقة، والتي لا تتوافق مع تمرير الهوية (On-Behalf-Of).
  • يتطلب MCP الخاص إعداد وكيل قياسي: الاتصال بخوادم MCP الخاص متاح فقط مع إعداد الوكيل القياسي مع الشبكات الخاصة (BYO VNet). إعداد الوكيل الأساسي لا يدعم نقاط نهاية MCP الخاصة.
  • استضافة MCP الخاصة: تطبيقات حاويات Azure على شبكة فرعية مخصصة ل MCP هي التكوين المجرب لخوادم MCP الخاصة. قد تعمل تطبيقات أو خدمات التطبيقات كمضيف خاص لخادم MCP لكنها لم تتحقق داخليا.

أسئلة وأخطاء شائعة

فيما يلي بعض المشاكل الشائعة التي قد تواجهها عند استخدام أدوات MCP مع خدمة وكلاء المساند:

  • "مخطط الأدوات غير الصالح":

    عادة ما يحدث مخطط الأدوات غير الصالح إذا كان لديك anyOf تعريف خادم MCP أو allOf إذا كان المعامل يمكنه أخذ عدة أنواع من القيم. قم بتحديث تعريف خادم MCP وحاول مرة أخرى.

  • "غير مصرح به" أو "ممنوع" من خادم MCP:

    تأكد من أن خادم MCP يدعم طريقة المصادقة الخاصة بك، وتحقق من بيانات الاعتماد المخزنة في اتصال مشروعك. بالنسبة ل GitHub، استخدم رموز أقل امتيازات وقم بتدويرها بانتظام.

  • النموذج لا ينادي أبدا بأداة MCP الخاصة بك:

    تأكد من تعليمات الوكيل التي تشجع على استخدام الأدوات، وتحقق server_labelمن قيم ، server_urlو allowed_tools ، والقيم. إذا قمت بتعيين allowed_toolsالجهاز، تأكد من أن اسم الأداة يطابق ما يعرضه خادم MCP.

  • الوكيل لا يستمر أبدا بعد الموافقة:

    تأكد من إرسال طلب متابعة مع previous_response_id تعيين معرف الاستجابة الأصلي، وأنك تستخدم معرف عنصر طلب الموافقة ك approval_request_id.

استضافة خادم MCP محلي

يقبل وقت تشغيل خدمة الوكيل نقطة نهاية خادم MCP البعيدة فقط. إذا أردت إضافة أدوات من خادم MCP محلي، عليك استضافتها بنفسك على Azure Container Apps أو Azure Functions للحصول على نقطة نهاية خادم MCP بعيد.

يمكن أن تكون نقطة النهاية البعيدة إما نقطة نهاية عامة أو خاصة داخل VNet الخاص بك. بالنسبة لخوادم MCP الخاصة، قم بنشر تطبيق الحاوية الخاص بك مع إدخال داخلي فقط (--internal-only true) على شبكة فرعية مخصصة ل MCP. راجع نقاط نهاية خوادم MCP العامة والخاصة لتفاصيل الإعداد.

ضع في اعتبارك العوامل التالية عند استضافة خوادم MCP المحلية في السحابة:

إعداد خادم MCP المحلي Hosting in Azure Container Apps الاستضافة في Azure Functions
النقل نقاط نهاية HTTP POST/GET مطلوبة. مطلوب HTTP قابل للدفق.
تغييرات التعليمات البرمجية يلزم إعادة بناء الحاوية. ملفات التكوين الخاصة ب Azure Functions مطلوبة في الدليل الجذري.
Authentication مطلوب تنفيذ المصادقة المخصصة. المستند إلى المفتاح فقط. يحتاج OAuth إلى إدارة واجهة برمجة التطبيقات.
اللغة أي لغة تعمل في حاويات لينكس (Python، Node.js، .NET، TypeScript، Go). Python، Node.js، Java، .NET فقط.
متطلبات الحاويات Linux (linux / amd64) فقط. لا توجد حاويات مميزة. الخوادم المحوجرة غير مدعومة.
التبعيات يجب أن تكون جميع التبعيات في صورة الحاوية. التبعيات على مستوى نظام التشغيل (مثل Playwright) غير مدعومة.
State عديم الجنسية فقط. عديم الجنسية فقط.
الأشعة فوق البنفسجية / NPX Supported. ‏‏غير مدعومة. npx أوامر البدء غير مدعومة.

المحتوى ذو الصلة

  • Last updated on