Udostępnij przez

Korzystanie z narzędzi MCP z agentami

Model Context Protocol to otwarty standard, który definiuje sposób, w jaki aplikacje udostępniają narzędzia i dane kontekstowe dużym modelom językowym (LLMs). Umożliwia spójną, skalowalną integrację narzędzi zewnętrznych z przepływami pracy modelu.

Platforma Microsoft Agent Framework obsługuje integrację z serwerami PROTOKOŁU MCP (Model Context Protocol), umożliwiając agentom dostęp do zewnętrznych narzędzi i usług. W tym przewodniku pokazano, jak nawiązać połączenie z serwerem MCP i używać jego narzędzi w ramach agenta.

Zagadnienia dotyczące korzystania z serwerów MCP innych firm

Korzystanie z serwerów protokołu kontekstu modelu podlega warunkom między Użytkownik a dostawcą usług. Po nawiązaniu połączenia z usługą inną niż Microsoft niektóre dane (takie jak zawartość monitu) są przekazywane do usługi innej niż Microsoft lub aplikacja może odbierać dane z usługi innej firmy niż Microsoft. Ponosisz odpowiedzialność za korzystanie z usług i danych firm innych niż Microsoft wraz z wszelkimi opłatami skojarzonymi z tym użyciem.

Zdalne serwery MCP, których decydujesz się używać z narzędziem MCP opisanym w tym artykule, zostały utworzone przez inne firmy, a nie microsoft. Firma Microsoft nie przetestowała ani nie zweryfikowała tych serwerów. Firma Microsoft nie ponosi odpowiedzialności wobec Ciebie lub innych w związku z Twoim korzystaniem z jakichkolwiek zdalnych serwerów MCP.

Zalecamy dokładne przejrzenie i śledzenie serwerów MCP dodanych do aplikacji opartych na strukturze agentów. Zalecamy również poleganie na serwerach hostowanych przez zaufanych dostawców usług zamiast serwerów proxy.

Narzędzie MCP umożliwia przekazywanie niestandardowych nagłówków, takich jak klucze uwierzytelniania lub schematy, których może potrzebować zdalny serwer MCP. Zalecamy przejrzenie wszystkich danych udostępnionych zdalnym serwerom MCP i zarejestrowaniu danych w celach inspekcji. Bądź świadomy praktyk innych niż Microsoft dotyczących przechowywania i lokalizacji danych.

Ważne

Nagłówki można określić tylko przez uwzględnienie ich w tool_resources w każdym uruchomieniu. W ten sposób można umieścić klucze interfejsu API, tokeny dostępu OAuth lub inne poświadczenia bezpośrednio w żądaniu. Przekazane nagłówki są dostępne tylko dla obecnego uruchomienia i nie są utrwalane.

Aby uzyskać więcej informacji na temat zabezpieczeń MCP, zobacz:

Wersja platformy .NET programu Agent Framework może być używana razem z oficjalnym zestawem SDK mcp języka C# , aby umożliwić agentowi wywoływanie narzędzi MCP.

W poniższym przykładzie pokazano, jak:

  1. Konfigurowanie i serwer MCP
  2. Pobieranie listy dostępnych narzędzi z serwera MCP
  3. Przekonwertuj narzędzia MCP na AIFunction"s", aby można je było dodać do agenta
  4. Wywoływanie narzędzi z agenta przy użyciu wywoływania funkcji

Konfigurowanie klienta MCP

Najpierw utwórz klienta MCP, który łączy się z żądanym serwerem 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"],
}));

W tym przykładzie:

  • Nazwa: przyjazna nazwa połączenia serwera MCP
  • Polecenie: plik wykonywalny do uruchomienia serwera MCP (tutaj przy użyciu narzędzia npx do uruchomienia pakietu Node.js)
  • Argumenty: argumenty wiersza polecenia przekazane do serwera MCP

Pobieranie dostępnych narzędzi

Po nawiązaniu połączenia pobierz listę narzędzi dostępnych z serwera MCP:

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

Metoda ListToolsAsync() zwraca kolekcję narzędzi udostępnianych przez serwer MCP. Te narzędzia są automatycznie konwertowane na obiekty AITool, które mogą być używane przez agenta.

Tworzenie agenta za pomocą narzędzi MCP

Utwórz agenta i podaj narzędzia MCP podczas inicjowania:

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>()]);

Ostrzeżenie

DefaultAzureCredential jest wygodne do programowania, ale wymaga starannego rozważenia w środowisku produkcyjnym. W środowisku produkcyjnym rozważ użycie określonego poświadczenia (np ManagedIdentityCredential. ) w celu uniknięcia problemów z opóźnieniami, niezamierzonego sondowania poświadczeń i potencjalnego ryzyka związanego z bezpieczeństwem z mechanizmów rezerwowych.

Najważniejsze kwestie:

  • Instrukcje: Podaj jasne instrukcje, które są zgodne z możliwościami narzędzi MCP
  • Narzędzia: rzutowanie narzędzi MCP na AITool obiekty i rozmieszczanie ich w tablicy narzędzi
  • Agent będzie automatycznie miał dostęp do wszystkich narzędzi udostępnianych przez serwer MCP

Korzystanie z agenta

Po skonfigurowaniu agent może automatycznie używać narzędzi MCP do realizacji żądań użytkowników:

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

Agent będzie:

  1. Analizowanie żądania użytkownika
  2. Określanie, które narzędzia MCP są potrzebne
  3. Wywoływanie odpowiednich narzędzi za pośrednictwem serwera MCP
  4. Syntetyzowanie wyników w spójną odpowiedź

Konfiguracja środowiska

Upewnij się, że skonfigurowaliśmy wymagane zmienne środowiskowe:

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

Zarządzanie zasobami

Zawsze prawidłowo usuwaj zasoby klienta MCP:

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

Użycie await using zapewnia prawidłowe zamknięcie połączenia klienta MCP, gdy wykracza poza zakres.

Typowe serwery MCP

Popularne serwery MCP obejmują:

  • @modelcontextprotocol/server-github: Uzyskiwanie dostępu do repozytoriów i danych usługi GitHub
  • @modelcontextprotocol/server-filesystem: Operacje systemu plików
  • @modelcontextprotocol/server-sqlite: dostęp do bazy danych SQLite

Każdy serwer udostępnia różne narzędzia i możliwości, które rozszerzają funkcjonalność agenta. Ta integracja umożliwia agentom bezproblemowy dostęp do danych i usług zewnętrznych przy zachowaniu zalet zabezpieczeń i standaryzacji protokołu kontekstu modelu.

Pełny kod źródłowy i instrukcje uruchamiania tego przykładu są dostępne pod adresem https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server.

Tip

Zobacz przykłady dla platformy .NET , aby uzyskać pełne przykłady możliwych do uruchomienia.

Dzięki temu agenci mogą bezproblemowo uzyskiwać dostęp do zewnętrznych narzędzi i usług.

Typy narzędzi MCP

Struktura agenta obsługuje trzy typy połączeń MCP:

MCPStdioTool — lokalne serwery MCP

Użyj MCPStdioTool polecenia , aby nawiązać połączenie z serwerami MCP, które działają jako procesy lokalne przy użyciu standardowych danych wejściowych/wyjściowych:

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 — serwery HTTP/SSE MCP

Użyj MCPStreamableHTTPTool polecenia , aby nawiązać połączenie z serwerami MCP za pośrednictwem protokołu HTTP za pomocą zdarzeń Server-Sent:

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 — serwery MCP WebSocket

Użyj MCPWebsocketTool polecenia , aby nawiązać połączenie z serwerami MCP za pośrednictwem połączeń protokołu 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(
            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())

Typowe serwery MCP, których można używać z platformą Agent Framework języka Python:

  • Kalkulator: uvx mcp-server-calculator — Obliczenia matematyczne
  • System plików: uvx mcp-server-filesystem — Operacje systemu plików
  • GitHub: npx @modelcontextprotocol/server-github — dostęp do repozytorium GitHub
  • SQLite: uvx mcp-server-sqlite — Operacje bazy danych

Każdy serwer udostępnia różne narzędzia i możliwości, które rozszerzają funkcjonalność agenta przy zachowaniu zalet zabezpieczeń i standaryzacji protokołu kontekstu modelu.

Kompletny przykład

# 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}")

Uwidacznianie agenta jako serwera MCP

Agenta można uwidocznić jako serwer MCP, dzięki czemu może być używany jako narzędzie przez dowolnego klienta zgodnego z mcP (takiego jak vs Code GitHub Copilot Agents lub innych agentów). Nazwa i opis agenta stają się metadanymi serwera MCP.

Zawijaj agenta w narzędziu funkcji przy użyciu polecenia .AsAIFunction(), utwórz element McpServerTooli zarejestruj go na serwerze MCP:

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

Zainstaluj wymagane pakiety NuGet:

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

Wywołaj .as_mcp_server() agenta, aby uwidocznić go jako serwer MCP:

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

Skonfiguruj serwer MCP, aby nasłuchiwać danych wejściowych/wyjściowych w warstwie Standardowa:

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)

Dalsze kroki

Używanie przepływów pracy jako agentów

  • Last updated on