استخدام أدوات MCP مع العوامل

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

يدعم Microsoft Agent Framework التكامل مع خوادم بروتوكول سياق النموذج (MCP)، ما يسمح لوكلاءك بالوصول إلى الأدوات والخدمات الخارجية. يوضح هذا الدليل كيفية الاتصال بخادم MCP واستخدام أدواته داخل وكيلك.

اعتبارات استخدام خوادم MCP التابعة لجهة خارجية

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

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

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

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

Important

يمكنك تحديد الرؤوس لكل تشغيل عن طريق تضمينها في موارد الأدوات في كل تشغيل، أو تكوين header_provider على Python أدوات MCP المحلية. راجع أي مفاتيح API أو رموز وصول OAuth المميزة أو بيانات الاعتماد الأخرى المشتركة مع خوادم MCP البعيدة.

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

أفضل ممارسات الأمان على موقع بروتوكول السياق النموذجي.
فهم وتخفيف المخاطر الأمنية في تطبيقات MCP في مدونة مجتمع الأمان من Microsoft.

يمكن استخدام الإصدار .NET من إطار عمل العامل مع MCP C# SDK الرسمي للسماح لوكيلك بالاتصال بأدوات MCP.

يوضح النموذج التالي كيفية:

إعداد وخادم MCP
استرداد قائمة الأدوات المتوفرة من خادم MCP
تحويل أدوات MCP إلى AIFunction's بحيث يمكن إضافتها إلى عامل
استدعاء الأدوات من عامل باستخدام استدعاء الدالة

إعداد عميل MCP

أولا، قم بإنشاء عميل MCP يتصل بخادم MCP المطلوب:

// Create an MCPClient for the GitHub server
await using var mcpClient = await McpClientFactory.CreateAsync(new StdioClientTransport(new()
{
    Name = "MCPServer",
    Command = "npx",
    Arguments = ["-y", "--verbose", "@modelcontextprotocol/server-github"],
}));

في هذا المثال:

الاسم: اسم مألوف لاتصال خادم MCP
الأمر: القابل للتنفيذ لتشغيل خادم MCP (هنا باستخدام npx لتشغيل حزمة Node.js)
الوسيطات: وسيطات سطر الأوامر التي تم تمريرها إلى خادم MCP

استرداد الأدوات المتوفرة

بمجرد الاتصال، قم باسترداد قائمة الأدوات المتوفرة من خادم MCP:

// Retrieve the list of tools available on the GitHub server
var mcpTools = await mcpClient.ListToolsAsync().ConfigureAwait(false);

يقوم ListToolsAsync() الأسلوب بإرجاع مجموعة من الأدوات التي يعرضها خادم MCP. يتم تحويل هذه الأدوات تلقائيا إلى كائنات AITool التي يمكن استخدامها من قبل وكيلك.

إنشاء عامل باستخدام أدوات MCP

أنشئ وكيلك وقدم أدوات MCP أثناء التهيئة:

AIAgent agent = new AIProjectClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .AsAIAgent(
         model: deploymentName,
         instructions: "You answer questions related to GitHub repositories only.",
         tools: [.. mcpTools.Cast<AITool>()]);

تحذير

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

نقاط رئيسية:

الإرشادات: توفير إرشادات واضحة تتوافق مع قدرات أدوات MCP
الأدوات: تحويل أدوات MCP إلى AITool العناصر ونشرها في صفيف الأدوات
سيتمكن العامل تلقائيا من الوصول إلى جميع الأدوات التي يوفرها خادم MCP

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

بمجرد التكوين، يمكن لوكيلك استخدام أدوات MCP تلقائيا لتلبية طلبات المستخدم:

// Invoke the agent and output the text result
Console.WriteLine(await agent.RunAsync("Summarize the last four commits to the microsoft/semantic-kernel repository?"));

الوكيل سيقوف:

تحليل طلب المستخدم
تحديد أدوات MCP المطلوبة
استدعاء الأدوات المناسبة من خلال خادم MCP
تجميع النتائج في استجابة متماسكة

تكوين البيئة

تأكد من إعداد متغيرات البيئة المطلوبة:

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ??
    throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

إدارة الموارد

التخلص بشكل صحيح دائما من موارد عميل MCP:

await using var mcpClient = await McpClientFactory.CreateAsync(...);

يضمن استخدام await using إغلاق اتصال عميل MCP بشكل صحيح عندما يخرج عن النطاق.

خوادم MCP الشائعة

تتضمن خوادم MCP الشائعة ما يلي:

@modelcontextprotocol/server-github: الوصول إلى GitHub المستودعات والبيانات
@modelcontextprotocol/server-filesystem: عمليات نظام الملفات
@modelcontextprotocol/server-sqlite: الوصول إلى قاعدة بيانات SQLite

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

Tip

تتوفر التعليمات البرمجية المصدر الكاملة والإرشادات لتشغيل هذه العينة في https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/ModelContextProtocol/Agent_MCP_Server.

يسمح هذا لوكلاءك بالوصول إلى الأدوات والخدمات الخارجية بسلاسة.

Note

عند الحد الأدنى من عمليات التثبيت Python، قد يلزم تثبيت دعم MCP يدويا. تثبيت mcp --pre لاستخدام MCPStdioToolأو MCPStreamableHTTPToolأو Agent.as_mcp_server(). ثبت mcp[ws] --pre إذا كنت بحاجة أيضا إلى MCPWebsocketTool.

أنواع أدوات MCP

يدعم إطار عمل العامل ثلاثة أنواع من اتصالات MCP:

MCPStdioTool - خوادم MCP المحلية

يستخدم MCPStdioTool للاتصال بخوادم MCP التي تعمل كعملية محلية باستخدام الإدخال/الإخراج القياسي:

import asyncio
from agent_framework import Agent, MCPStdioTool
from agent_framework.openai import OpenAIChatClient

async def local_mcp_example():
    """Example using a local MCP server via stdio."""
    async with (
        MCPStdioTool(
            name="calculator",
            command="uvx",
            args=["mcp-server-calculator"]
        ) as mcp_server,
        Agent(
            client=OpenAIChatClient(),
            name="MathAgent",
            instructions="You are a helpful math assistant that can solve calculations.",
        ) as agent,
    ):
        result = await agent.run(
            "What is 15 * 23 + 45?",
            tools=mcp_server
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(local_mcp_example())

MCPStreamableHTTPTool - خوادم HTTP/SSE MCP

استخدم MCPStreamableHTTPTool للاتصال بخوادم MCP عبر HTTP مع أحداث Server-Sent:

import asyncio
from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async def http_mcp_example():
    """Example using an HTTP-based MCP server."""
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        async with (
            MCPStreamableHTTPTool(
                name="Microsoft Learn MCP",
                url="https://learn.microsoft.com/api/mcp",
            ) as mcp_server,
            Agent(
                client=client,
                name="DocsAgent",
                instructions="You help with Microsoft documentation questions.",
            ) as agent,
        ):
            result = await agent.run(
                "How to create an Azure storage account using az cli?",
                tools=mcp_server
            )
            print(result)

if __name__ == "__main__":
    asyncio.run(http_mcp_example())

بالنسبة لنقاط نهاية HTTP المصادق عليها، استخدم header_provider حتى تتم إضافة بيانات الاعتماد فقط إلى نفس طلبات الأصل. أثناء استدعاء الأداة، يتلقى الموفر القيم من function_invocation_kwargs. بالنسبة للطلبات المحيطة مثل تهيئة تأكيد الاتصال، والأداة أو اكتشاف المطالبة، وpings الخلفية، فإنه يتلقى قاموسا فارغا.

إذا كان الخادم يتطلب المصادقة أثناء الاتصال، فقم بالتقاط بيانات الاعتماد المطلوبة أو تحديثها في الموفر بدلا من الاعتماد فقط على القيم لكل تشغيل. يتيح الموفر الذي يرفع KeyError بسبب عدم توفر قيمة لكل تشغيل متابعة طلب محيط دون هذا العنوان؛ يعمل هذا النمط فقط عندما يسمح الخادم بالتهيؤ والاكتشاف غير المصادق عليه. تظهر أخطاء الموفر الأخرى.

MCPWebsocketTool - خوادم WebSocket MCP

استخدم MCPWebsocketTool للاتصال بخوادم MCP عبر اتصالات WebSocket:

import asyncio
from agent_framework import Agent, MCPWebsocketTool
from agent_framework.openai import OpenAIChatClient

async def websocket_mcp_example():
    """Example using a WebSocket-based MCP server."""
    async with (
        MCPWebsocketTool(
            name="realtime-data",
            url="wss://api.example.com/mcp",
        ) as mcp_server,
        Agent(
            client=OpenAIChatClient(),
            name="DataAgent",
            instructions="You provide real-time data insights.",
        ) as agent,
    ):
        result = await agent.run(
            "What is the current market status?",
            tools=mcp_server
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(websocket_mcp_example())

خوادم MCP الشائعة

خوادم MCP الشائعة التي يمكنك استخدامها مع إطار عمل عامل Python:

الحاسبة: uvx mcp-server-calculator - الحسابات الرياضية
نظام الملفات: uvx mcp-server-filesystem - عمليات نظام الملفات
GitHub: npx @modelcontextprotocol/server-github - الوصول إلى مستودع GitHub
SQLite: uvx mcp-server-sqlite - عمليات قاعدة البيانات

يوفر كل خادم أدوات وقدرات مختلفة تعمل على توسيع وظائف الوكيل مع الحفاظ على مزايا الأمان والتوحيد القياسي لبروتوكول سياق النموذج.

مثال كامل

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.openai import OpenAIChatClient

"""
MCP Authentication Example

This example demonstrates a `header_provider` that authenticates both connection-time and tool-call requests.

For more authentication examples including OAuth 2.0 flows, see:
- https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/clients/simple-auth-client
- https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/servers/simple-auth
"""


async def api_key_auth_example() -> None:
    """Example of using API key authentication with MCP server."""
    mcp_server_url = os.getenv("MCP_SERVER_URL", "your-mcp-server-url")
    api_key = os.getenv("MCP_API_KEY")
    if not api_key:
        raise ValueError("MCP_API_KEY environment variable must be set.")

    async with Agent(
        client=OpenAIChatClient(),
        name="Agent",
        instructions="You are a helpful assistant.",
        tools=MCPStreamableHTTPTool(
            name="MCP tool",
            description="MCP tool description",
            url=mcp_server_url,
            header_provider=lambda _kwargs: {"Authorization": f"Bearer {api_key}"},
        ),
    ) as agent:
        query = "What tools are available to you?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Agent: {result.text}")

if __name__ == "__main__":
    asyncio.run(api_key_auth_example())

أنواع أدوات MCP

mcptool تتيح الحزمة للوكلاء استخدام أدوات من خوادم بروتوكول سياق النموذج (MCP).

الاتصال بخادم MCP

import (
    "github.com/microsoft/agent-framework-go/tool/mcptool"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

session, err := mcptool.Connect(ctx, &mcp.StreamableClientTransport{
    Endpoint: "https://learn.microsoft.com/api/mcp",
})
if err != nil {
    panic(err)
}
defer session.Close()

سرد أدوات MCP واستخدامها

tools, err := mcptool.ListTools(ctx, session)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Tools: tools,
    },
})

resp, err := a.RunText(ctx, "How to create an Azure storage account using az cli?").Collect()

وسائل النقل المدعومة

HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
Stdio - تشغيل عملية خادم MCP محلية

Tip

راجع نموذج أدوات MCP للحصول على مثال كامل قابل للتشغيل.

تعريض عامل كخادم MCP

يمكنك عرض عامل كخادم MCP، ما يسمح باستخدامه كأداة من قبل أي عميل متوافق مع MCP (مثل VS Code GitHub Copilot Agents أو وكلاء آخرين). يصبح اسم العامل ووصفه بيانات تعريف خادم MCP.

التفاف العامل في أداة دالة باستخدام .AsAIFunction()، وإنشاء McpServerTool، وتسجيله مع خادم MCP:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Server;

// Create the agent
AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            instructions: "You are good at telling jokes.",
            name: "Joker");

// Convert the agent to an MCP tool
McpServerTool tool = McpServerTool.Create(agent.AsAIFunction());

// Set up the MCP server over stdio
HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(settings: null);
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithTools([tool]);

await builder.Build().RunAsync();

تحذير

تثبيت حزم NuGet المطلوبة:

dotnet add package Microsoft.Extensions.Hosting --prerelease
dotnet add package ModelContextProtocol --prerelease

اتصل .as_mcp_server() بعامل لعرضه كخادم MCP:

Note

agent.as_mcp_server() يعتمد Python أيضا على الحزمة الاختياريةmcp. إذا كنت تستخدم تثبيتا ضئيلا/أساسيا، فقم بتشغيل pip install mcp --pre أولا.

from agent_framework.openai import OpenAIChatClient
from typing import Annotated

def get_specials() -> Annotated[str, "Returns the specials from the menu."]:
    return "Special Soup: Clam Chowder, Special Salad: Cobb Salad"

# Create an agent with tools
agent = OpenAIChatClient().as_agent(
    name="RestaurantAgent",
    description="Answer questions about the menu.",
    tools=[get_specials],
)

# Expose the agent as an MCP server
server = agent.as_mcp_server()

إعداد خادم MCP للاستماع عبر الإدخال/الإخراج القياسي:

import anyio
from mcp.server.stdio import stdio_server

async def run():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, server.create_initialization_options())

if __name__ == "__main__":
    anyio.run(run)

التفاف العامل مع agenttool.New، وتسجيله مع خادم MCP باستخدام mcptool.AddTool، وتشغيل الخادم عبر stdio:

import (
    "context"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
    "github.com/microsoft/agent-framework-go/tool/agenttool"
    "github.com/microsoft/agent-framework-go/tool/mcptool"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

jokeAgent := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are good at telling jokes.",
    Config: agent.Config{
        Name:        "Joker",
        Description: "An agent that tells jokes.",
    },
})

server := mcp.NewServer(&mcp.Implementation{
    Name:    "agent-mcp-server",
    Version: "1.0.0",
}, nil)

mcptool.AddTool(server, agenttool.New(jokeAgent, agenttool.Config{}))

if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
    panic(err)
}

Tip

راجع العامل كعينة أداة MCP للحصول على مثال كامل قابل للتشغيل.

الخطوات التالية

المحادثات والذاكرة

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-08-25

استخدام أدوات MCP مع العوامل

اعتبارات استخدام خوادم MCP التابعة لجهة خارجية

إعداد عميل MCP

استرداد الأدوات المتوفرة

إنشاء عامل باستخدام أدوات MCP

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

تكوين البيئة

إدارة الموارد

خوادم MCP الشائعة

أنواع أدوات MCP

MCPStdioTool - خوادم MCP المحلية

MCPStreamableHTTPTool - خوادم HTTP/SSE MCP

MCPWebsocketTool - خوادم WebSocket MCP

خوادم MCP الشائعة

مثال كامل

أنواع أدوات MCP

الاتصال بخادم MCP

سرد أدوات MCP واستخدامها

وسائل النقل المدعومة

تعريض عامل كخادم MCP

الخطوات التالية

الملاحظات

الموارد الإضافية