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é ni 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 par exécution en les incluant dans des ressources d’outil à chaque exécution ou en configurant un header_provider sur Python outils MCP locaux. Passez en revue les clés API, les jetons d’accès OAuth ou d’autres informations d’identification partagées avec des serveurs MCP distants.

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

Meilleures pratiques de sécurité sur le site web du protocole de contexte de modèle.
Comprendre et atténuer les risques de sécurité dans les implémentations MCP dans le blog de la communauté de sécurité Microsoft.

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 :

Configurer et serveur MCP
Récupérer la liste des outils disponibles à partir du serveur MCP
Convertir les outils MCP en AIFunction' afin qu’ils puissent être ajoutés à un agent
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 AIProjectClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .AsAIAgent(
         model: deploymentName,
         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 :

Analyser la demande de l’utilisateur
Déterminer les outils MCP nécessaires
Appeler les outils appropriés via le serveur MCP
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.

Tip

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/02-agents/ModelContextProtocol/Agent_MCP_Server.

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

Note

Lors d’installations Python minimales, la prise en charge de MCP peut être nécessaire pour être installée manuellement. Installer mcp --pre pour utiliser MCPStdioTool, MCPStreamableHTTPToolou Agent.as_mcp_server(). Installez mcp[ws] --pre si vous avez également besoin MCPWebsocketToolde .

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

Le client HTTP qui MCPStreamableHTTPTool crée ne conserve pas les cookies de réponse. Si le serveur requiert des cookies pour l’authentification, les sessions ou l’affinité de l’équilibreur de charge, passez un fichier configuré httpx.AsyncClient via http_client=. Le client fourni conserve son comportement de cookie et reste propriétaire de l’appelant. Étendue d’un client porteur de cookie et de sa session d’outils MCP à un principal authentifié.

Pour les points de terminaison HTTP authentifiés, utilisez static_headers les informations d’identification fixes ou header_provider pour les valeurs dérivées de chaque exécution. Les deux chemins ajoutent des en-têtes uniquement aux demandes d’origine configurée et suppriment-les des redirections entre origines. Les en-têtes fixes sont copiés lorsque l’outil est créé et ne sérialisent pas les appels simultanés. Lorsque les deux options fournissent le même en-tête, la valeur dynamique est header_provider prioritaire.

Pendant les appels d’outil générés, header_provider reçoit uniquement l’hôte function_invocation_kwargsde l’exécution. Il ne reçoit pas d’arguments d’outil fournis par le modèle, même lorsqu’un argument de modèle a le même nom. Un appel direct call_tool(...) transmet ses arguments de mot clé fournis par l’appelant au fournisseur. Les valeurs de modèle peuvent toujours être prioritaires dans les arguments d’outil sortant fusionnés séparément, mais elles ne contrôlent pas les en-têtes d’authentification.

Les en-têtes fixes et dynamiques forment ensemble l’identité effective de la session HTTP. Les noms d’en-tête sont comparés sans respect de la casse, tandis que les valeurs restent sensibles à la casse. Les arguments de mot clé runtime sont également éligibles pour les arguments d’outil sortant lorsque le schéma du serveur autorise le même nom. Pour empêcher les informations d’identification des arguments de l’outil, capturez-les dans le fournisseur via une fermeture ou ContextVar, utilisez static_headersou fournissez un client HTTP personnalisé.

Les sessions appartenant à l’infrastructure lient cette identité effective lorsqu’elles se connectent. Si une exécution ultérieure génère une identité différente, l’outil se reconnecte avant d’envoyer l’appel et actualise l’outil dérivé de session et invite la découverte. L’initialisation, la découverte, le test ping en arrière-plan et d’autres demandes de durée de vie des connexions continuent d’utiliser les en-têtes liés à cette session.

Les sessions fournies par l’appelant restent détenues par l’appelant. Étant donné que le wrapper ne peut pas établir ou reconnecter une identité inconnue pour ces sessions, la résolution d’en-tête dynamique avec une identité inconnue est rejetée. Une identité modifiée est également rejetée ; utilisez une instance d’outil gérée par l’infrastructure distincte.

Si l’outil se connecte avec impatience avant une exécution, le fournisseur reçoit un mappage vide pour les demandes de durée de vie de connexion. Capturez ou actualisez les informations d’identification au moment de la construction dans le fournisseur pour ce cas. Si des informations d’identification arrivent uniquement au moment de l’exécution, passez l’outil run(tools=[...]) non connecté avec function_invocation_kwargs lequel l’exécution établit la connexion.

Un KeyError fournisseur est toléré uniquement lorsqu’aucune exécution n’a amorçage la connexion et que la requête continue sans en-têtes de fournisseur. Après une exécution, une clé manquante est une erreur de configuration et l’exception est exposée.

Sélectionner des outils par nom non ambiguïté

Lorsque vous définissez ou répertoriez allowed_tools des outils dans approval_mode, utilisez le nom brut de l’outil distant ou un nom préfixé non ambigu. Si un nom configuré correspond à plusieurs noms distants bruts après la normalisation, Agent Framework déclenche ToolExecutionException. Utilisez un nom brut exact ou une modification tool_name_prefix pour rendre les noms locaux uniques.

Dépréciation de l’échantillonnage MCP

Avertissement

L’échantillonnage MCP initié par le serveur et sampling_callback est déconseillé à partir de la version 2026-07-28 de la spécification MCP et sont supprimés pas plus tard que 2027-07-28. Ne créez pas de nouvelles intégrations sur cette fonctionnalité. Les serveurs MCP doivent appeler directement les API du fournisseur de modèles.

Contrôler la rétention de la charge utile de l’hôte

Lorsqu’un transport hôte, tel que AG-UI, consomme un résultat d’outil MCP, Agent Framework conserve le résultat json sécurisé complet séparément de la valeur orientée modèle analysé. Cela permet à l’hôte de recevoir des champs tels que structuredContent sans ajouter de données Host uniquement à l’historique des modèles.

Utilisez tool_result_content sur n’importe quel transport MCP pour sélectionner la valeur visible par le modèle lorsqu’un résultat contient les deux content et structuredContent:

Valeur	Résultat visible par modèle
`structured_first`	Utilise `structuredContent` lorsqu’il est présent, sinon `content`. Cette valeur est la valeur par défaut.
`content_first`	Utilise nonempty `content`, sinon `structuredContent`.
`content_only`	`structuredContent`Ignore .
`structured_only`	`content`Ignore .
`both`	Ajoute sérialisé `structuredContent` après les `content` blocs.

Cette sélection ne modifie pas la charge utile de l’hôte conservée. parse_tool_results remplace la stratégie de sélection.

Chaque transport MCP limite par défaut une charge utile hôte conservée à 1 Mio. Les charges utiles surdimensionnées sont omises à partir du canal hôte, tandis que le résultat analysé atteint toujours le modèle. Définissez une limite d’octets positive différente sur le transport ou utilisez None uniquement lorsque l’hôte en aval applique sa propre limite :

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

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

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

Types d’outils MCP

Le mcptool package permet aux agents d’utiliser des outils à partir de serveurs MCP (Model Context Protocol).

Se connecter à un serveur MCP

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

Répertorier et utiliser les outils MCP

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

Transports pris en charge

HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
Stdio - Lancer un processus de serveur MCP local

Tip

Consultez l’exemple d’outils MCP pour obtenir un exemple d’exécution complet.

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

Avertissement

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 :

Note

Python agent.as_mcp_server() dépend également du package facultatif mcp . Si vous utilisez une installation mince/core, exécutez pip install mcp --pre d’abord.

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

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)

Encapsulez l’agent avec agenttool.New, inscrivez-le auprès d’un serveur MCP à l’aide mcptool.AddToolde , puis exécutez le serveur sur 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

Consultez l’agent comme exemple d’outil MCP pour obtenir un exemple d’exécution complet.

Étapes suivantes

Conversations & Mémoire

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-09-23

Utilisation d’outils MCP avec des agents

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

Configuration d’un client MCP

Récupération des outils disponibles

Créer un agent avec les outils MCP

Utilisation de l’agent

Configuration de l’environnement

Gestion des ressources

Serveurs MCP courants

Types d’outils MCP

MCPStdioTool - Serveurs MCP locaux

MCPStreamableHTTPTool - Serveurs HTTP/SSE MCP

Sélectionner des outils par nom non ambiguïté

Dépréciation de l’échantillonnage MCP

Contrôler la rétention de la charge utile de l’hôte

MCPWebsocketTool - Serveurs MCP WebSocket

Serveurs MCP populaires

Exemple complet

Types d’outils MCP

Se connecter à un serveur MCP

Répertorier et utiliser les outils MCP

Transports pris en charge

Exposition d’un agent en tant que serveur MCP

Étapes suivantes

Commentaires

Ressources supplémentaires