Använda MCP-verktyg med agenter

.NET-versionen av Agent Framework kan användas tillsammans med den officiella MCP C# SDK :t så att din agent kan anropa MCP-verktyg.

Följande exempel visar hur du:

1. Konfigurera och MCP-server
2. Hämta listan över tillgängliga verktyg från MCP-servern
3. Konvertera MCP-verktygen till 's så att AIFunctionde kan läggas till i en agent
4. Anropa verktygen från en agent med hjälp av funktionsanrop

Konfigurera en MCP-klient

Skapa först en MCP-klient som ansluter till din önskade MCP-server:

using ModelContextProtocol.Client;

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

I det här exemplet:

• Namn: Ett eget namn för MCP-serveranslutningen
• Kommando: Den körbara filen för att köra MCP-servern (här använder du npx för att köra ett Node.js-paket)
• Argument: Kommandoradsargument som skickas till MCP-servern

Hämtar tillgängliga verktyg

När du är ansluten hämtar du listan över verktyg som är tillgängliga från MCP-servern:

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

Metoden ListToolsAsync() returnerar en samling verktyg som MCP-servern exponerar. Dessa verktyg konverteras automatiskt till AITool-objekt som kan användas av din agent.

Skapa en agent med MCP-verktyg

Skapa din agent och ange MCP-verktygen under initieringen:

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

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

Viktiga punkter:

• Instruktioner: Ge tydliga instruktioner som överensstämmer med funktionerna i mcp-verktygen
• Verktyg: Omvandla MCP-verktygen till AITool objekt och sprida dem till verktygsmatrisen
• Agenten har automatiskt åtkomst till alla verktyg som tillhandahålls av MCP-servern

Använda agenten

När agenten har konfigurerats kan den automatiskt använda MCP-verktygen för att uppfylla användarbegäranden:

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

Agenten kommer att:

1. Analysera användarens begäran
2. Avgöra vilka MCP-verktyg som behövs
3. Anropa lämpliga verktyg via MCP-servern
4. Syntetisera resultatet till ett sammanhängande svar

Miljökonfiguration

Se till att konfigurera nödvändiga miljövariabler:

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

Resurshantering

Ta alltid bort MCP-klientresurser korrekt:

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

Genom att använda await using ser du till att MCP-klientanslutningen stängs korrekt när den hamnar utanför omfånget.

Vanliga MCP-servrar

Populära MCP-servrar är:

• @modelcontextprotocol/server-github: Få åtkomst till GitHub-lagringsplatser och data
• @modelcontextprotocol/server-filesystem: Filsystemåtgärder
• @modelcontextprotocol/server-sqlite: SQLite-databasåtkomst

Varje server har olika verktyg och funktioner som utökar agentens funktioner. Med den här integreringen kan dina agenter sömlöst komma åt externa data och tjänster samtidigt som säkerhets- och standardiseringsfördelarna med modelkontextprotokollet bibehålls.

På så sätt kan dina agenter få sömlös åtkomst till externa verktyg och tjänster.

MCP-verktygstyper

Agent Framework stöder tre typer av MCP-anslutningar:

MCPStdioTool – lokala MCP-servrar

Använd MCPStdioTool för att ansluta till MCP-servrar som körs som lokala processer med standardindata/utdata:

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

Använd MCPStreamableHTTPTool för att ansluta till MCP-servrar via HTTP med Server-Sent-händelser:

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-klienten som MCPStreamableHTTPTool skapar bevarar inte svarscookies. Om servern kräver cookies för autentisering, sessioner eller lastbalanseringstillhörighet skickar du en konfigurerad httpx.AsyncClient via http_client=. Den angivna klienten behåller sitt cookiebeteende och förblir uppringarägd. Omfång för en cookiebärande klient och dess MCP-verktygssession till ett autentiserat huvudnamn.

För autentiserade HTTP-slutpunkter använder du static_headers för fasta autentiseringsuppgifter eller header_provider för värden som härleds från varje körning. Båda sökvägarna lägger bara till rubriker i begäranden för det konfigurerade ursprunget och tar bort dem från korsande omdirigeringar. Fasta rubriker kopieras när verktyget skapas och serialiserar inte samtidiga anrop. När båda alternativen anger samma rubrik har det dynamiska värdet från header_provider företräde.

Under genererade verktygsanrop header_provider tar endast emot körningens värd function_invocation_kwargs. Den tar inte emot verktygsargument som tillhandahålls av modellen, även om ett modellargument har samma namn. Ett direktanrop call_tool(...) skickar nyckelordsargumenten från anroparen till providern. Modellvärden kan fortfarande ha företräde i de separat sammanfogade argumenten för utgående verktyg, men de styr inte autentiseringshuvuden.

De fasta och dynamiska rubrikerna utgör tillsammans HTTP-sessionens effektiva identitet. Rubriknamn jämförs skiftlägesokänsligt, medan värden förblir skiftlägeskänsliga. Nyckelordsargument för körning är också berättigade till argument för utgående verktyg när serverschemat tillåter samma namn. Om du vill hålla autentiseringsuppgifterna borta från verktygsargumenten samlar du in dem i providern via en stängning eller ContextVar, använder static_headerseller anger en anpassad HTTP-klient.

Ramverksägda sessioner binder den här effektiva identiteten när de ansluter. Om en senare körning genererar en annan identitet återansluter verktyget innan det skickar anropet och uppdaterar det sessionsbaserade verktyget och identifieringen av prompten. Initiera, identifiera, bakgrunds-ping och andra begäranden om anslutningslivslängd fortsätter att använda rubrikerna som är bundna till den sessionen.

Sessioner som tillhandahålls av uppringaren förblir uppringarägda. Eftersom omslutningen inte kan upprätta eller återansluta en okänd identitet för dessa sessioner avvisas dynamisk rubrikmatchning med en okänd identitet. En ändrad identitet avvisas också. använd en separat ramverkshanterad verktygsinstans.

Om verktyget ansluter ivrigt före en körning får providern en tom mappning för förfrågningar om anslutningslivslängd. Samla in eller uppdatera en autentiseringsuppgift för byggtid i providern för det här fallet. Om en autentiseringsuppgift endast anländer vid körningen skickar du det oanslutna verktyget med run(tools=[...])function_invocation_kwargs så att körningen upprättar anslutningen.

En KeyError från providern tolereras endast när ingen körning har kopplat anslutningen och begäran fortsätter utan providerhuvuden. När en körning har skapat anslutningen är en nyckel som saknas ett konfigurationsfel och undantaget visas.

Välj verktyg efter entydigt namn

När du anger allowed_tools eller listar verktyg i approval_modeanvänder du fjärrverktygets rånamn eller ett entydigt prefixnamn. Om ett konfigurerat namn matchar flera råa fjärrnamn efter normaliseringen genererar ToolExecutionExceptionAgent Framework . Använd ett exakt rånamn eller en ändring tool_name_prefix för att göra de lokala namnen unika.

UTfasning av MCP-sampling

Kontrollera kvarhållning av värdnyttolast

När en värdtransport, till exempel AG-UI, förbrukar ett MCP-verktygsresultat behåller Agent Framework det fullständiga JSON-säkra resultatet separat från det parsade modelluppkopplade värdet. På så sätt kan värden ta emot fält, till exempel structuredContent utan att lägga till endast värddata i modellhistoriken.

Använd tool_result_content på alla MCP-transporter för att välja det modell synliga värdet när ett resultat innehåller både content och structuredContent:

Det här valet ändrar inte den behållna värdnyttolasten. parse_tool_results åsidosätter urvalsprincipen.

Varje MCP-transport begränsar en behållen värdnyttolast till 1 MiB som standard. Överdimensionerade nyttolaster utelämnas från värdkanalen, medan det parsade resultatet fortfarande når modellen. Ange en annan positiv bytegräns för transporten eller använd None endast när den underordnade värden tillämpar sin egen bindning:

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

MCPWebsocketTool – WebSocket MCP-servrar

Använd MCPWebsocketTool för att ansluta till MCP-servrar via WebSocket-anslutningar:

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

Populära MCP-servrar

Vanliga MCP-servrar som du kan använda med Python Agent Framework:

• Kalkylator: uvx mcp-server-calculator – Matematiska beräkningar
• Filsystem: uvx mcp-server-filesystem – Filsystemåtgärder
• GitHub: npx @modelcontextprotocol/server-github – Åtkomst till GitHub-lagringsplats
• SQLite: uvx mcp-server-sqlite – Databasåtgärder

Varje server har olika verktyg och funktioner som utökar agentens funktioner samtidigt som säkerhets- och standardiseringsfördelarna med Model Context Protocol bibehålls.

Fullständigt exempel

# 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-verktygstyper

Paketet mcptool låter agenter använda verktyg från MCP-servrar (Model Context Protocol).

Ansluta till en 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()

Lista och använda MCP-verktyg

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

Transporter som stöds

• HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
• Stdio – Starta en lokal MCP-serverprocess

Omslut agenten i ett funktionsverktyg med hjälp av .AsAIFunction(), skapa en McpServerTooloch registrera den med en 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();

Installera nödvändiga NuGet-paket:

dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Microsoft.Extensions.Hosting
dotnet add package ModelContextProtocol

Anropa .as_mcp_server() en agent för att exponera den som en MCP-server:

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

Konfigurera MCP-servern för att lyssna över standardindata/utdata:

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)

Omslut agenten med agenttool.New, registrera den med en MCP-server med och mcptool.AddToolkör servern 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)
}