Partager via

Utilisation d’outils MCP avec des agents

Le protocole de contexte de modèle est une norme ouverte qui définit la façon dont les applications fournissent des outils et des données contextuelles aux modèles de langage volumineux (LLMs). Il permet une intégration cohérente et évolutive d’outils externes dans des flux de travail de modèle.

Microsoft Agent Framework prend en charge l’intégration avec les serveurs MCP (Model Context Protocol), ce qui permet à vos agents d’accéder à des outils et services externes. Ce guide montre comment se connecter à un serveur MCP et utiliser ses outils au sein de votre agent.

Considérations relatives à l’utilisation de serveurs MCP tiers

Votre utilisation des serveurs Model Context Protocol est soumise aux conditions entre vous et le fournisseur de services. Lorsque vous vous connectez à un service non-Microsoft, certaines de vos données (telles que le contenu d’invite) sont transmises au service non-Microsoft, ou votre application peut recevoir des données du service non-Microsoft. Vous êtes responsable de votre utilisation de services et de données non-Microsoft, ainsi que des frais associés à cette utilisation.

Les serveurs MCP distants que vous décidez d’utiliser avec l’outil MCP décrit dans cet article ont été créés par des tiers, et non par Microsoft. Microsoft n’a pas testé ou vérifié ces serveurs. Microsoft n’a aucune responsabilité vis-à-vis de vous ou d’autres en ce qui concerne votre utilisation de serveurs MCP distants.

Nous vous recommandons de passer en revue et de suivre attentivement les serveurs MCP que vous ajoutez à vos applications Basées sur Agent Framework. Nous vous recommandons également de vous appuyer sur des serveurs hébergés par des fournisseurs de services approuvés eux-mêmes plutôt que des proxys.

L’outil MCP vous permet de transmettre des en-têtes personnalisés, tels que des clés d’authentification ou des schémas, dont un serveur MCP distant peut avoir besoin. Nous vous recommandons de passer en revue toutes les données partagées avec des serveurs MCP distants et de consigner les données à des fins d’audit. Soyez conscient des pratiques non-Microsoft en matière de rétention et d’emplacement des données.

Important

Vous pouvez spécifier des en-têtes uniquement en les incluant dans tool_resources à chaque exécution. De cette façon, vous pouvez placer des clés API, des jetons d’accès OAuth ou d’autres informations d’identification directement dans votre demande. Les en-têtes que vous passez sont disponibles seulement pour l’exécution en cours et ne sont pas conservés.

Pour plus d’informations sur la sécurité MCP, consultez :

La version .NET d’Agent Framework peut être utilisée avec le SDK C# MCP officiel pour permettre à votre agent d’appeler des outils MCP.

L’exemple suivant montre comment :

  1. Configurer et serveur MCP
  2. Récupérer la liste des outils disponibles à partir du serveur MCP
  3. Convertir les outils MCP en AIFunction' afin qu’ils puissent être ajoutés à un agent
  4. Appeler les outils d’un agent à l’aide de l’appel de fonction

Configuration d’un client MCP

Tout d’abord, créez un client MCP qui se connecte à votre serveur MCP souhaité :

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

Dans cet exemple :

  • Nom : Nom convivial de votre connexion de serveur MCP
  • Commande : exécutable pour exécuter le serveur MCP (ici, à l’aide de npx pour exécuter un package Node.js)
  • Arguments : arguments de ligne de commande passés au serveur MCP

Récupération des outils disponibles

Une fois connecté, récupérez la liste des outils disponibles à partir du serveur MCP :

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

La ListToolsAsync() méthode retourne une collection d’outils exposés par le serveur MCP. Ces outils sont automatiquement convertis en objets AITool qui peuvent être utilisés par votre agent.

Créer un agent avec les outils MCP

Créez votre agent et fournissez les outils MCP lors de l’initialisation :

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

Avertissement

DefaultAzureCredential est pratique pour le développement, mais nécessite une considération minutieuse en production. En production, envisagez d’utiliser des informations d’identification spécifiques (par exemple ManagedIdentityCredential) pour éviter les problèmes de latence, la détection involontaire des informations d’identification et les risques de sécurité potentiels liés aux mécanismes de secours.

Points clés :

  • Instructions : fournissez des instructions claires qui s’alignent sur les fonctionnalités de vos outils MCP
  • Outils : cassez les outils MCP en AITool objets et répartissez-les dans le tableau d’outils
  • L’agent aura automatiquement accès à tous les outils fournis par le serveur MCP

Utilisation de l’agent

Une fois configuré, votre agent peut utiliser automatiquement les outils MCP pour répondre aux demandes des utilisateurs :

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

L’agent :

  1. Analyser la demande de l’utilisateur
  2. Déterminer les outils MCP nécessaires
  3. Appeler les outils appropriés via le serveur MCP
  4. Synthétiser les résultats dans une réponse cohérente

Configuration de l’environnement

Veillez à configurer les variables d’environnement requises :

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

Gestion des ressources

Supprimez toujours correctement les ressources clientes MCP :

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

L’utilisation await using garantit que la connexion du client MCP est correctement fermée lorsqu’elle sort de l’étendue.

Serveurs MCP courants

Les serveurs MCP populaires sont les suivants :

  • @modelcontextprotocol/server-github: Accéder aux référentiels et données GitHub
  • @modelcontextprotocol/server-filesystem: Opérations du système de fichiers
  • @modelcontextprotocol/server-sqlite: accès à la base de données SQLite

Chaque serveur fournit différents outils et fonctionnalités qui étendent les fonctionnalités de votre agent. Cette intégration permet à vos agents d’accéder en toute transparence aux données et services externes tout en conservant les avantages de sécurité et de normalisation du protocole de contexte de modèle.

Le code source complet et les instructions permettant d’exécuter cet exemple sont disponibles à l’adresse https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server.

Conseil / Astuce

Consultez les exemples .NET pour obtenir des exemples exécutables complets.

Cela permet à vos agents d’accéder en toute transparence aux outils et services externes.

Types d’outils MCP

Agent Framework prend en charge trois types de connexions MCP :

MCPStdioTool - Serveurs MCP locaux

Permet MCPStdioTool de se connecter aux serveurs MCP qui s’exécutent en tant que processus locaux à l’aide de l’entrée/sortie standard :

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

Permet MCPStreamableHTTPTool de se connecter à des serveurs MCP via HTTP avec des événements 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 - Serveurs MCP WebSocket

Permet MCPWebsocketTool de se connecter à des serveurs MCP via des connexions 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())

Serveurs MCP courants que vous pouvez utiliser avec Python Agent Framework :

  • Calculatrice : uvx mcp-server-calculator - Calculs mathématiques
  • Système de fichiers : uvx mcp-server-filesystem - Opérations du système de fichiers
  • GitHub : npx @modelcontextprotocol/server-github - Accès au référentiel GitHub
  • SQLite : uvx mcp-server-sqlite - Opérations de base de données

Chaque serveur fournit différents outils et fonctionnalités qui étendent les fonctionnalités de votre agent tout en conservant les avantages de sécurité et de normalisation du protocole de contexte de modèle.

Exemple complet

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

Exposition d’un agent en tant que serveur MCP

Vous pouvez exposer un agent en tant que serveur MCP, ce qui lui permet d’être utilisé en tant qu’outil par n’importe quel client compatible MCP (tel que vs Code GitHub Copilot Agents ou d’autres agents). Le nom et la description de l’agent deviennent les métadonnées du serveur MCP.

Encapsulez l’agent dans un outil de fonction à l’aide .AsAIFunction()de , créez-le McpServerToolet inscrivez-le auprès d’un serveur 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();

Installez les packages NuGet requis :

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

Appelez .as_mcp_server() un agent pour l’exposer en tant que serveur 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()

Configurez le serveur MCP pour écouter les entrées/sorties standard :

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)

Prochaines étapes

Utilisation de flux de travail en tant qu’agents

  • Last updated on