MCP-eszközök használata ügynökökkel

A Model Context Protocol egy nyílt szabvány, amely meghatározza, hogy az alkalmazások hogyan biztosítják az eszközöket és a környezetfüggő adatokat a nagy nyelvi modellek (LLM-ek) számára. Lehetővé teszi a külső eszközök egységes, méretezhető integrálását a modell-munkafolyamatokba.

A Microsoft Agent Framework támogatja a Model Context Protocol (MCP) kiszolgálókkal való integrációt, így az ügynökök hozzáférhetnek külső eszközökhöz és szolgáltatásokhoz. Ez az útmutató bemutatja, hogyan csatlakozhat egy MCP-kiszolgálóhoz, és hogyan használhatja az eszközeit az ügynökön belül.

Harmadik féltől származó MCP-kiszolgálók használatának szempontjai

A Model Context Protocol-kiszolgálók használatára az Ön és a szolgáltató közötti feltételek vonatkoznak. Ha nem Microsoft-szolgáltatáshoz csatlakozik, az adatok egy része (például a parancssori tartalom) át lesz adva a nem Microsoft-szolgáltatásnak, vagy előfordulhat, hogy az alkalmazás adatokat kap a nem Microsoft-szolgáltatástól. Ön a felelős a nem Microsoft-szolgáltatások és -adatok használatáért, valamint a használattal kapcsolatos díjakért.

A cikkben ismertetett MCP-eszközzel használni kívánt távoli MCP-kiszolgálókat nem a Microsoft, hanem harmadik felek hozták létre. A Microsoft nem tesztelte vagy ellenőrizte ezeket a kiszolgálókat. A Microsoft nem vállal felelősséget Önért vagy másokért a távoli MCP-kiszolgálók használatával kapcsolatban.

Javasoljuk, hogy gondosan tekintse át és kövesse nyomon, hogy milyen MCP-kiszolgálókat ad hozzá az Agent Framework-alapú alkalmazásokhoz. Azt is javasoljuk, hogy a proxyk helyett inkább megbízható szolgáltatók által üzemeltetett kiszolgálókra támaszkodjanak.

Az MCP-eszköz lehetővé teszi olyan egyéni fejlécek, például hitelesítési kulcsok vagy sémák átadását, amelyekre egy távoli MCP-kiszolgálónak szüksége lehet. Javasoljuk, hogy tekintse át a távoli MCP-kiszolgálókkal megosztott összes adatot, és naplózza azokat az adatok auditálása céljából. Ügyeljen az adatok megőrzésére és elhelyezésére vonatkozó nem Microsoft-eljárásokra.

Fontos

A fejléceket csak úgy adhatja meg, ha minden futtatáskor tool_resources tartalmazza őket. Ily módon közvetlenül a kérésben elhelyezhet API-kulcsokat, OAuth-hozzáférési jogkivonatokat vagy más hitelesítő adatokat. Az átadott fejlécek csak az aktuális futtatáshoz érhetők el, és nem kerülnek tárolásra.

További információ az MCP biztonságáról:

Ajánlott biztonsági eljárások a Model Context Protocol webhelyén.
Az MCP-implementációk biztonsági kockázatainak megismerése és enyhítése a Microsoft Biztonsági Közösség blogjában.

Az Agent Framework .NET-verziója a hivatalos MCP C# SDK-val együtt használható, hogy az ügynök meghívhassa az MCP-eszközöket.

Az alábbi minta bemutatja, hogyan:

Beállítás és MCP-kiszolgáló
Az elérhető eszközök listájának lekérése az MCP-kiszolgálóról
Alakítsa át az MCP-eszközöket "s"-vé AIFunction, hogy hozzáadhatók legyenek egy ügynökhöz
Az eszközök meghívása egy ügynökből függvényhívással

MCP-ügyfél beállítása

Először hozzon létre egy MCP-ügyfelet, amely a kívánt MCP-kiszolgálóhoz csatlakozik:

// 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"],
}));

Ebben a példában:

Név: Az MCP-kiszolgáló kapcsolatának rövid neve
Parancs: Az MCP-kiszolgáló futtatásához futtatható végrehajtható fájl (itt npx használatával futtathat Node.js csomagot)
Argumentumok: Az MCP-kiszolgálónak átadott parancssori argumentumok

Elérhető eszközök lekérése

Csatlakozás után kérje le az MCP-kiszolgálóról elérhető eszközök listáját:

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

A ListToolsAsync() metódus az MCP-kiszolgáló által elérhetővé tesz eszközök gyűjteményét adja vissza. Ezek az eszközök automatikusan AITool-objektumokká alakulnak, amelyeket az ügynök használhat.

Ügynök létrehozása AZ MCP-eszközökkel

Hozza létre az ügynököt, és adja meg az MCP-eszközöket az inicializálás során:

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

Figyelmeztetés

DefaultAzureCredential a fejlesztéshez kényelmes, de az éles környezetben gondos megfontolást igényel. Éles környezetben fontolja meg egy adott hitelesítő adat (pl. ) használatát a ManagedIdentityCredentialkésési problémák, a nem szándékos hitelesítő adatok próbaüzeme és a tartalék mechanizmusok esetleges biztonsági kockázatainak elkerülése érdekében.

Összefoglalás:

Utasítások: Adjon meg egyértelmű utasításokat, amelyek összhangban vannak az MCP-eszközök képességeivel
Eszközök: Az MCP-eszközöket az objektumokra AITool veti, és elosztja azokat az eszköztömbbe
Az ügynök automatikusan hozzáfér az MCP-kiszolgáló által biztosított összes eszközhöz

Az ügynök használata

A konfigurálás után az ügynök automatikusan használhatja az MCP-eszközöket a felhasználói kérések teljesítéséhez:

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

Az ügynök a következőt fogja:

A felhasználó kérésének elemzése
Annak meghatározása, hogy mely MCP-eszközökre van szükség
A megfelelő eszközök meghívása az MCP-kiszolgálón keresztül
Az eredmények egységes válaszként való szintetizálása

Környezeti konfiguráció

Győződjön meg arról, hogy beállítja a szükséges környezeti változókat:

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";

Erőforrás-kezelés

Az MCP-ügyfélerőforrásokat mindig megfelelően szabadítsa fel:

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

A használat await using biztosítja, hogy az MCP-ügyfélkapcsolat megfelelően legyen lezárva, amikor kimegy a hatókörből.

Gyakori MCP-kiszolgálók

Népszerű MCP-kiszolgálók:

@modelcontextprotocol/server-github: GitHub-adattárak és adatok elérése
@modelcontextprotocol/server-filesystem: Fájlrendszerműveletek
@modelcontextprotocol/server-sqlite: SQLite-adatbázis-hozzáférés

Minden kiszolgáló különböző eszközöket és képességeket biztosít, amelyek kibővítik az ügynök funkcióit. Ez az integráció lehetővé teszi az ügynökök számára, hogy zökkenőmentesen hozzáférjenek a külső adatokhoz és szolgáltatásokhoz, miközben fenntartják a modellkörnyezeti protokoll biztonsági és szabványosítási előnyeit.

A minta futtatásához szükséges teljes forráskód és utasítások a következő címen https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Serverérhetők el: .

Jótanács

A teljes futtatható példákért tekintse meg a .NET-mintákat .

Ez lehetővé teszi az ügynökök számára, hogy zökkenőmentesen hozzáférjenek a külső eszközökhöz és szolgáltatásokhoz.

MCP eszköztípusok

Az Agent Framework háromféle MCP-kapcsolatot támogat:

MCPStdioTool – Helyi MCP-kiszolgálók

A helyi folyamatként futó MCP-kiszolgálókhoz való csatlakozáshoz használható MCPStdioTool standard bemenet/kimenet használatával:

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(
            chat_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-kiszolgálók

Az MCPStreamableHTTPTool MCP-kiszolgálókhoz http-en keresztüli csatlakozásra használható Server-Sent események használatával:

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

async def http_mcp_example():
    """Example using an HTTP-based MCP server."""
    async with (
        AzureCliCredential() as credential,
        MCPStreamableHTTPTool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
            headers={"Authorization": "Bearer your-token"},
        ) as mcp_server,
        Agent(
            chat_client=AzureAIAgentClient(async_credential=credential),
            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())

MCPWebsocketTool – WebSocket MCP-kiszolgálók

Az MCP-kiszolgálókhoz WebSocket-kapcsolatokon keresztüli csatlakozáshoz használható MCPWebsocketTool :

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(
            chat_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())

Népszerű MCP-kiszolgálók

A Python Agent Framework használatával használható gyakori MCP-kiszolgálók:

Számológép: uvx mcp-server-calculator - Matematikai számítások
Fájlrendszer: uvx mcp-server-filesystem – Fájlrendszer-műveletek
GitHub: npx @modelcontextprotocol/server-github – GitHub-adattár hozzáférése
SQLite: uvx mcp-server-sqlite – Adatbázis-műveletek

Minden kiszolgáló különböző eszközöket és képességeket biztosít, amelyek kibővítik az ügynök funkcióit, miközben fenntartják a modellkörnyezeti protokoll biztonsági és szabványosítási előnyeit.

Teljes példa

# Copyright (c) Microsoft. All rights reserved.

import os

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.openai import OpenAIResponsesClient
from httpx import AsyncClient

"""
MCP Authentication Example

This example demonstrates how to authenticate with MCP servers using API key headers.

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."""
    # Configuration
    mcp_server_url = os.getenv("MCP_SERVER_URL", "your-mcp-server-url")
    api_key = os.getenv("MCP_API_KEY")

    # Create authentication headers
    # Common patterns:
    # - Bearer token: "Authorization": f"Bearer {api_key}"
    # - API key header: "X-API-Key": api_key
    # - Custom header: "Authorization": f"ApiKey {api_key}"
    auth_headers = {
        "Authorization": f"Bearer {api_key}",
    }

    # Create HTTP client with authentication headers
    http_client = AsyncClient(headers=auth_headers)

    # Create MCP tool with the configured HTTP client
    async with (
        MCPStreamableHTTPTool(
            name="MCP tool",
            description="MCP tool description",
            url=mcp_server_url,
            http_client=http_client,  # Pass HTTP client with authentication headers
        ) as mcp_tool,
        Agent(
            client=OpenAIResponsesClient(),
            name="Agent",
            instructions="You are a helpful assistant.",
            tools=mcp_tool,
        ) as agent,
    ):
        query = "What tools are available to you?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Agent: {result.text}")

Ügynök felfedése MCP-kiszolgálóként

Az ügynököket mcp-kiszolgálóként is közzéteheti, így bármely MCP-kompatibilis ügyfél (például a VS Code GitHub Copilot-ügynökök vagy más ügynökök) eszközként használhatja. Az ügynök neve és leírása az MCP-kiszolgáló metaadataivá válik.

Csomagolja be az ügynököt egy függvényeszközbe .AsAIFunction(), hozzon létre egy McpServerTool, majd regisztrálja azt egy MCP-kiszolgálón:

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

// Create the agent
AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(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();

Telepítse a szükséges NuGet-csomagokat:

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

Hívja meg .as_mcp_server() az ügynököt, hogy tegye közzé MCP-kiszolgálóként:

from agent_framework.openai import OpenAIResponsesClient
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 = OpenAIResponsesClient().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()

Állítsa be az MCP-kiszolgálót a standard bemenet/kimenet figyeléséhez:

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)

Következő lépések

Munkafolyamatok használata ügynökökként

Visszacsatolás

Hasznos volt ez az oldal?

Last updated on 2026-02-13