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 de MCP-tool kunt u aangepaste headers, zoals verificatiesleutels of schema's, doorgeven die een externe MCP-server nodig kan hebben. 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 headers per uitvoering opgeven door ze op te slaan in hulpprogrammabronnen tijdens elke uitvoering of een header_provider op Python lokale MCP-hulpprogramma's te configureren. Controleer alle API-sleutels, OAuth-toegangstokens of andere referenties die worden gedeeld met externe MCP-servers.

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 AIProjectClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .AsAIAgent(
         model: deploymentName,
         instructions: "You answer questions related to GitHub repositories only.",
         tools: [.. mcpTools.Cast<AITool>()]);

Warning

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.

Belangrijkste 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.

Tip

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

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

Opmerking

Bij minimale Python-installaties moet MCP-ondersteuning mogelijk handmatig worden geïnstalleerd. Installeren mcp --pre om te gebruiken MCPStdioTool, MCPStreamableHTTPToolof Agent.as_mcp_server(). Installeer mcp[ws] --pre deze als u ook nodig hebt MCPWebsocketTool.

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

De HTTP-client die MCPStreamableHTTPTool maakt, houdt geen reactiecookies vast. Als de server cookies vereist voor verificatie, sessies of load balanceraffiniteit, geeft u een geconfigureerde httpx.AsyncClient door http_client=. De opgegeven client behoudt het cookiegedrag en blijft eigendom van de beller. Bereik een cookie-lager client en de MCP-hulpprogrammasessie met één geverifieerde principal.

Gebruik voor geverifieerde HTTP-eindpunten static_headers voor vaste referenties of header_provider voor waarden die zijn afgeleid van elke uitvoering. Beide paden voegen alleen headers toe aan aanvragen voor de geconfigureerde oorsprong en verwijderen van cross-origin-omleidingen. Vaste headers worden gekopieerd wanneer het hulpprogramma wordt gemaakt en geen gelijktijdige aanroepen serialiseren. Wanneer beide opties dezelfde header leveren, heeft de dynamische waarde header_provider voorrang.

Tijdens gegenereerde hulpprogramma-aanroepen header_provider ontvangt u alleen de host function_invocation_kwargsvan de run. Er worden geen door het model geleverde hulpprogrammaargumenten ontvangen, zelfs niet wanneer een modelargument dezelfde naam heeft. Een directe call_tool(...) aanroep geeft de door de aanroeper verstrekte trefwoordargumenten door aan de provider. Modelwaarden kunnen nog steeds prioriteit hebben in de afzonderlijk samengevoegde argumenten voor uitgaande hulpprogramma's, maar ze beheren geen verificatieheaders.

De vaste en dynamische headers vormen samen de effectieve identiteit van de HTTP-sessie. Headernamen worden hoofdlettergevoelig vergeleken, terwijl waarden hoofdlettergevoelig blijven. Trefwoordargumenten voor runtime komen ook in aanmerking voor uitgaande hulpprogrammaargumenten wanneer het serverschema dezelfde naam toestaat. Als u referenties buiten hulpprogrammaargumenten wilt houden, legt u deze vast in de provider via een sluiting of ContextVargebruikt static_headersu of geeft u een aangepaste HTTP-client op.

Framework-sessies binden deze effectieve identiteit wanneer ze verbinding maken. Als een latere uitvoering een andere identiteit produceert, wordt het hulpprogramma opnieuw verbonden voordat het gesprek wordt verzonden en het afgeleide hulpprogramma voor sessies wordt vernieuwd en detectie wordt gevraagd. Initialiseer, detectie, achtergrond ping en andere aanvragen voor de levensduur van verbindingen blijven de headers gebruiken die aan die sessie zijn gebonden.

Door de beller geleverde sessies blijven eigendom van de beller. Omdat de wrapper een onbekende identiteit voor deze sessies niet tot stand kan brengen of opnieuw kan verbinden, wordt dynamische headeromzetting met een onbekende identiteit geweigerd. Een gewijzigde identiteit wordt ook geweigerd; gebruik een afzonderlijk exemplaar van een door framework beheerd hulpprogramma.

Als het hulpprogramma gretig verbinding maakt voordat een uitvoering wordt uitgevoerd, ontvangt de provider een lege toewijzing voor aanvragen voor de levensduur van de verbinding. Leg een referentie voor de bouwtijd vast of vernieuw deze in de provider voor dit geval. Als een referentie alleen op runtime aankomt, geeft u het niet-verbonden hulpprogramma door run(tools=[...]) , function_invocation_kwargs zodat de verbinding tot stand wordt gebracht.

Een KeyError van de provider wordt alleen getolereerd wanneer de verbinding niet wordt uitgevoerd en de aanvraag wordt voortgezet zonder providerheaders. Nadat een uitvoering de verbinding heeft geactiveerd, is een ontbrekende sleutel een configuratiefout en wordt de uitzondering weergegeven.

Hulpmiddelen selecteren op ondubbelzinnige naam

Wanneer u hulpprogramma's instelt allowed_toolsapproval_modeof vermeldt, gebruikt u de naam van het onbewerkte externe hulpprogramma of een ondubbelzinnige voorvoegselnaam. Als één geconfigureerde naam overeenkomt met meerdere onbewerkte externe namen na normalisatie, genereert ToolExecutionExceptionAgent Framework. Gebruik een exacte onbewerkte naam of wijzig tool_name_prefix deze om de lokale namen uniek te maken.

Afschaffing van MCP-steekproeven

Warning

Door de server geïnitieerde MCP-steekproeven en sampling_callback worden afgeschaft vanaf MCP-specificatieversie 2026-07-28 en worden uiterlijk 2027-07-28 verwijderd. Bouw geen nieuwe integraties voor deze functie. MCP-servers moeten api's van modelproviders rechtstreeks aanroepen.

Retentie van nettolading van host beheren

Wanneer een hosttransport, zoals AG-UI, een MCP-hulpprogrammaresultaat verbruikt, behoudt Agent Framework het volledige JSON-veilige resultaat afzonderlijk van de geparseerde modelgerichte waarde. Hierdoor kan de host velden ontvangen, zoals structuredContent zonder dat alleen-hostgegevens aan de modelgeschiedenis worden toegevoegd.

Gebruik tool_result_content op elk MCP-transport om de modelbare waarde te selecteren wanneer een resultaat zowel contentstructuredContentals :

Value Model zichtbaar resultaat
structured_first Gebruikt structuredContent indien aanwezig, anders content. Dit is de standaardwaarde.
content_first Maakt gebruik van niets, contentanders structuredContent.
content_only Negeert structuredContent.
structured_only Negeert content.
both Voegt geserialiseerd structuredContent na de content blokken.

Met deze selectie wordt de nettolading van de bewaarde host niet gewijzigd. parse_tool_results overschrijft het selectiebeleid.

Elk MCP-transport beperkt standaard een bewaarde hostpayload tot 1 MiB. Oversized nettoladingen worden weggelaten uit het hostkanaal, terwijl het geparseerde resultaat het model nog steeds bereikt. Stel een andere positieve bytelimiet voor het transport in of gebruik None alleen wanneer de downstreamhost een eigen afhankelijke host toepast:

mcp_server = MCPStreamableHTTPTool(
    name="Microsoft Learn MCP",
    url="https://learn.microsoft.com/api/mcp",
    max_host_payload_size_bytes=256 * 1024,
)

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

Met het mcptool pakket kunnen agents hulpprogramma's van MCP-servers (Model Context Protocol) gebruiken.

Verbinding maken met een MCP-server

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-hulpprogramma's weergeven en gebruiken

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

Ondersteunde transporten

  • HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
  • Stdio - Een lokaal MCP-serverproces starten

Tip

Zie het voorbeeld van MCP-hulpprogramma's voor een volledig voorbeeld dat kan worden uitgevoerd.

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

Warning

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.

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:

Opmerking

Python agent.as_mcp_server() is ook afhankelijk van het optionele mcp pakket. Als u een slim/core-gebaseerde installatie gebruikt, voert u eerst uit 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()

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)

Verpakt de agent met agenttool.New, registreer deze bij een MCP-server met behulp van mcptool.AddToolen voer de server uit via 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

Zie de agent als voorbeeld van het MCP-hulpprogramma voor een volledig voorbeeld dat kan worden uitgevoerd.

Volgende stappen 

Gesprekken en geheugen

  • Last updated on