Dela via

Använda MCP-verktyg med agenter

Model Context Protocol är en öppen standard som definierar hur program tillhandahåller verktyg och kontextuella data till stora språkmodeller (LLM). Det möjliggör konsekvent och skalbar integrering av externa verktyg i modellarbetsflöden.

Microsoft Agent Framework stöder integrering med MCP-servrar (Model Context Protocol) så att dina agenter kan komma åt externa verktyg och tjänster. Den här guiden visar hur du ansluter till en MCP-server och använder dess verktyg i din agent.

Överväganden för att använda MCP-servrar från tredje part

Din användning av Model Context Protocol-servrar omfattas av villkoren mellan dig och tjänstleverantören. När du ansluter till en tjänst som inte kommer från Microsoft skickas en del av dina data (till exempel frågat innehåll) till tjänsten som inte kommer från Microsoft, eller så kan ditt program ta emot data från tjänsten som inte kommer från Microsoft. Du ansvarar för din användning av tjänster och data som inte kommer från Microsoft, tillsammans med eventuella avgifter som är kopplade till den användningen.

De MCP-fjärrservrar som du bestämmer dig för att använda med MCP-verktyget som beskrivs i den här artikeln har skapats av tredje part, inte Microsoft. Microsoft har inte testat eller verifierat dessa servrar. Microsoft har inget ansvar för dig eller andra när det gäller din användning av fjärr-MCP-servrar.

Vi rekommenderar att du noggrant granskar och spårar vilka MCP-servrar du lägger till i dina Agent Framework-baserade program. Vi rekommenderar också att du förlitar dig på servrar som hanteras av betrodda tjänstleverantörer själva i stället för proxyservrar.

Med MCP-verktyget kan du skicka anpassade huvuden, till exempel autentiseringsnycklar eller scheman, som en fjärr-MCP-server kan behöva. Vi rekommenderar att du granskar alla data som delas med fjärranslutna MCP-servrar och att du loggar data i granskningssyfte. Var medveten om icke-Microsoft-metoder för lagring och placering av data.

Viktigt!

Du kan bara ange rubriker genom att inkludera dem i tool_resources vid varje körning. På så sätt kan du placera API-nycklar, OAuth-åtkomsttoken eller andra autentiseringsuppgifter direkt i din begäran. Rubriker som du skickar in är endast tillgängliga för den aktuella körningen och sparas inte.

Mer information om MCP-säkerhet finns i:

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

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

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:

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

Varning

DefaultAzureCredential är praktiskt för utveckling men kräver noggrant övervägande i produktion. I produktion bör du överväga att använda en specifik autentiseringsuppgift (t.ex. ManagedIdentityCredential) för att undvika problem med svarstid, oavsiktlig avsökning av autentiseringsuppgifter och potentiella säkerhetsrisker från reservmekanismer.

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

Den fullständiga källkoden och instruktionerna för att köra det här exemplet finns på https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server.

Tips/Råd

Se .NET-exemplen för fullständiga körbara exempel.

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

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

Exponera en agent som en MCP-server

Du kan exponera en agent som en MCP-server, så att den kan användas som ett verktyg av alla MCP-kompatibla klienter (till exempel VS Code GitHub Copilot-agenter eller andra agenter). Agentens namn och beskrivning blir MCP-servermetadata.

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

Installera nödvändiga NuGet-paket:

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

Anropa .as_mcp_server() en agent för att exponera den som en 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()

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)

Nästa steg

Använda arbetsflöden som agenter

  • Last updated on