Delen via

MCP-hulpprogramma's gebruiken met agents

Model Context Protocol is een open standaard die definieert hoe toepassingen hulpprogramma's en contextuele gegevens bieden aan grote taalmodellen (LLM's). Het maakt consistente, schaalbare integratie van externe hulpprogramma's mogelijk in modelwerkstromen.

Microsoft Agent Framework biedt ondersteuning voor integratie met MCP-servers (Model Context Protocol), zodat uw agents toegang hebben tot externe hulpprogramma's en services. Deze handleiding laat zien hoe u verbinding maakt met een MCP-server en de bijbehorende hulpprogramma's binnen uw agent gebruikt.

Overwegingen voor het gebruik van MCP-servers van derden

Uw gebruik van Model Context Protocol-servers is onderhevig aan de voorwaarden tussen u en de serviceprovider. Wanneer u verbinding maakt met een niet-Microsoft-service, worden sommige gegevens (zoals promptinhoud) doorgegeven aan de service die niet van Microsoft is, of ontvangt uw toepassing mogelijk gegevens van de niet-Microsoft-service. U bent verantwoordelijk voor uw gebruik van niet-Microsoft-services en -gegevens, samen met eventuele kosten voor dat gebruik.

De externe MCP-servers die u wilt gebruiken met het MCP-hulpprogramma dat in dit artikel wordt beschreven, zijn gemaakt door derden, niet door Microsoft. Microsoft heeft deze servers niet getest of geverifieerd. Microsoft heeft geen verantwoordelijkheid voor u of anderen met betrekking tot uw gebruik van externe MCP-servers.

We raden u aan zorgvuldig te controleren en bij te houden welke MCP-servers u toevoegt aan uw Agent Framework-toepassingen. We raden u ook aan om te vertrouwen op servers die worden gehost door vertrouwde serviceproviders zelf in plaats van proxy's.

Met het hulpprogramma MCP kunt u aangepaste headers, zoals verificatiesleutels of schema's, doorgeven die een externe MCP-server mogelijk nodig heeft. We raden u aan alle gegevens te bekijken die worden gedeeld met externe MCP-servers en dat u de gegevens voor controledoeleinden aanmeldt. Wees cognizant van niet-Microsoft-procedures voor retentie en locatie van gegevens.

Belangrijk

U kunt alleen headers opgeven door ze op te slaan in tool_resources tijdens elke uitvoering. Op deze manier kunt u API-sleutels, OAuth-toegangstokens of andere referenties rechtstreeks in uw aanvraag plaatsen. Headers die u doorgeeft, zijn alleen beschikbaar voor de huidige uitvoering en blijven niet behouden.

Zie voor meer informatie over MCP-beveiliging:

De .NET-versie van Agent Framework kan samen met de officiële MCP C#-SDK worden gebruikt, zodat uw agent MCP-hulpprogramma's kan aanroepen.

In het volgende voorbeeld ziet u hoe u:

  1. Instellen en MCP-server
  2. De lijst met beschikbare hulpprogramma's ophalen van de MCP-server
  3. De MCP-hulpprogramma's converteren naar AIFunction's, zodat ze kunnen worden toegevoegd aan een agent
  4. De hulpprogramma's aanroepen van een agent met behulp van functieaanroepen

Een MCP-client instellen

Maak eerst een MCP-client die verbinding maakt met de gewenste MCP-server:

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

In dit voorbeeld:

  • Naam: een beschrijvende naam voor uw MCP-serververbinding
  • Opdracht: het uitvoerbare bestand om de MCP-server uit te voeren (hier met behulp van NPX om een Node.js-pakket uit te voeren)
  • Argumenten: Opdrachtregelargumenten die worden doorgegeven aan de MCP-server

Beschikbare hulpprogramma's ophalen

Nadat u verbinding hebt gemaakt, haalt u de lijst met hulpprogramma's op die beschikbaar zijn op de MCP-server:

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

De ListToolsAsync() methode retourneert een verzameling hulpprogramma's die door de MCP-server worden weergegeven. Deze hulpprogramma's worden automatisch geconverteerd naar AITool-objecten die door uw agent kunnen worden gebruikt.

Een agent maken met MCP Tools

Maak uw agent en geef de MCP-hulpprogramma's op tijdens de initialisatie:

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

Waarschuwing

DefaultAzureCredential is handig voor ontwikkeling, maar vereist zorgvuldige overwegingen in de productieomgeving. Overweeg in productie een specifieke referentie te gebruiken (bijvoorbeeld ManagedIdentityCredential) om latentieproblemen, onbedoelde referentieprobing en potentiële beveiligingsrisico's van terugvalmechanismen te voorkomen.

Belangrijke punten:

  • Instructies: Geef duidelijke instructies op die overeenkomen met de mogelijkheden van uw MCP-hulpprogramma's
  • Hulpprogramma's: Cast the MCP tools to AITool objects and spread them into the tools array
  • De agent heeft automatisch toegang tot alle hulpprogramma's van de MCP-server

De agent gebruiken

Zodra de agent is geconfigureerd, kan uw agent automatisch de MCP-hulpprogramma's gebruiken om te voldoen aan gebruikersaanvragen:

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

De agent doet het volgende:

  1. De aanvraag van de gebruiker analyseren
  2. Bepalen welke MCP-hulpprogramma's nodig zijn
  3. De juiste hulpprogramma's aanroepen via de MCP-server
  4. De resultaten omzetten in een coherent antwoord

Omgevingsconfiguratie

Zorg ervoor dat u de vereiste omgevingsvariabelen instelt:

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

Resourcebeheer

Altijd goed verwijderen van MCP-clientbronnen:

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

Het gebruik await using zorgt ervoor dat de MCP-clientverbinding correct wordt gesloten wanneer deze buiten het bereik valt.

Algemene MCP-servers

Populaire MCP-servers zijn onder andere:

  • @modelcontextprotocol/server-github: Toegang tot GitHub-opslagplaatsen en -gegevens
  • @modelcontextprotocol/server-filesystem: Bestandssysteembewerkingen
  • @modelcontextprotocol/server-sqlite: SQLite-databasetoegang

Elke server biedt verschillende hulpprogramma's en mogelijkheden waarmee de functionaliteit van uw agent wordt uitgebreid. Dankzij deze integratie kunnen uw agents naadloos toegang krijgen tot externe gegevens en services, terwijl de beveiligings- en standaardiseringsvoordelen van het Model Context Protocol behouden blijven.

De volledige broncode en instructies voor het uitvoeren van dit voorbeeld zijn beschikbaar op https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server.

Aanbeveling

Zie de .NET-voorbeelden voor volledige runnable voorbeelden.

Hierdoor hebben uw agents naadloos toegang tot externe hulpprogramma's en services.

MCP-hulpprogrammatypen

Het Agent Framework ondersteunt drie typen MCP-verbindingen:

MCPStdioTool - Lokale MCP-servers

Gebruik MCPStdioTool dit om verbinding te maken met MCP-servers die als lokale processen worden uitgevoerd met behulp van standaardinvoer/uitvoer:

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

Gebruik MCPStreamableHTTPTool dit om via HTTP verbinding te maken met MCP-servers met Server-Sent gebeurtenissen:

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

Gebruik MCPWebsocketTool dit om verbinding te maken met MCP-servers via WebSocket-verbindingen:

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

Algemene MCP-servers die u kunt gebruiken met Python Agent Framework:

  • Rekenmachine: uvx mcp-server-calculator - Wiskundige berekeningen
  • Bestandssysteem: uvx mcp-server-filesystem - Bestandssysteembewerkingen
  • GitHub: npx @modelcontextprotocol/server-github - Toegang tot GitHub-opslagplaats
  • SQLite: uvx mcp-server-sqlite - Databasebewerkingen

Elke server biedt verschillende hulpprogramma's en mogelijkheden die de functionaliteit van uw agent uitbreiden en tegelijkertijd de voordelen van beveiliging en standaardisatie van het Model Context Protocol behouden.

Volledig voorbeeld

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

Een agent beschikbaar maken als een MCP-server

U kunt een agent beschikbaar maken als een MCP-server, zodat deze kan worden gebruikt als een hulpprogramma door elke MCP-compatibele client (zoals VS Code GitHub Copilot Agents of andere agents). De naam en beschrijving van de agent worden de metagegevens van de MCP-server.

Wrap the agent in a function tool using .AsAIFunction(), create an McpServerTool, and register it with an MCP server:

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

Installeer de vereiste NuGet-pakketten:

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

Roep .as_mcp_server() een agent aan om deze beschikbaar te maken als een MCP-server:

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

Stel de MCP-server in om te luisteren naar standaardinvoer/uitvoer:

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)

Volgende stappen

Werkstromen gebruiken als agents

  • Last updated on