Uso de herramientas de MCP con agentes

El protocolo de contexto de modelo es un estándar abierto que define cómo las aplicaciones proporcionan herramientas y datos contextuales a modelos de lenguaje grandes (LLM). Permite una integración coherente y escalable de herramientas externas en flujos de trabajo de modelo.

Microsoft Agent Framework admite la integración con servidores de Protocolo de contexto de modelo (MCP), lo que permite a los agentes acceder a servicios y herramientas externos. En esta guía se muestra cómo conectarse a un servidor MCP y usar sus herramientas dentro del agente.

Consideraciones para usar servidores MCP de terceros

El uso de servidores de Protocolo de contexto de modelo está sujeto a los términos entre usted y el proveedor de servicios. Cuando se conecta a un servicio que no es de Microsoft, algunos de los datos (como el contenido del mensaje) se pasan al servicio que no es de Microsoft o la aplicación puede recibir datos del servicio que no es de Microsoft. Usted es responsable del uso de datos y servicios que no son de Microsoft, junto con los cargos asociados a ese uso.

Los servidores MCP remotos que decide usar con la herramienta MCP que se describe en este artículo se crearon mediante terceros, no Microsoft. Microsoft no ha probado ni comprobado estos servidores. Microsoft no tiene ninguna responsabilidad para usted u otros usuarios en relación con el uso de cualquier servidor MCP remoto.

Le recomendamos que revise detenidamente y realice un seguimiento de los servidores MCP que agregue a las aplicaciones basadas en Agent Framework. También se recomienda confiar en servidores hospedados por proveedores de servicios de confianza en lugar de servidores proxy.

La herramienta MCP permite pasar encabezados personalizados, como claves de autenticación o esquemas, que podría necesitar un servidor MCP remoto. Se recomienda revisar todos los datos que se comparten con servidores MCP remotos y que registre los datos con fines de auditoría. Sea consciente de las prácticas que no son de Microsoft para la retención y la ubicación de los datos.

Importante

Solo puede especificar encabezados incluyéndolas en tool_resources en cada ejecución. De este modo, puede colocar claves de API, tokens de acceso de OAuth u otras credenciales directamente en la solicitud. Los encabezados que se pasan solo están disponibles para la ejecución actual y no se conservan.

Para obtener más información sobre la seguridad de MCP, consulte:

Procedimientos recomendados de seguridad en el sitio web del Protocolo de contexto de modelo.
Descripción y mitigación de los riesgos de seguridad en las implementaciones de MCP en el blog de la comunidad de seguridad de Microsoft.

La versión de .NET de Agent Framework se puede usar junto con el SDK oficial de C# de MCP para permitir que el agente llame a las herramientas de MCP.

En el ejemplo siguiente se muestra cómo:

Configuración y servidor MCP
Recuperar la lista de herramientas disponibles del servidor MCP
Convertir las herramientas de MCP en AIFunctionpara que se puedan agregar a un agente
Invocación de las herramientas desde un agente mediante la llamada a funciones

Configuración de un cliente MCP

En primer lugar, cree un cliente MCP que se conecte al servidor MCP deseado:

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

En este ejemplo:

Nombre: nombre descriptivo para la conexión del servidor MCP
Comando: ejecutable para ejecutar el servidor MCP (aquí mediante npx para ejecutar un paquete de Node.js)
Argumentos: argumentos de línea de comandos pasados al servidor MCP

Recuperación de herramientas disponibles

Una vez conectado, recupere la lista de herramientas disponibles en el servidor MCP:

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

El ListToolsAsync() método devuelve una colección de herramientas que expone el servidor MCP. Estas herramientas se convierten automáticamente en objetos AITool que el agente puede usar.

Creación de un agente con herramientas de MCP

Cree el agente y proporcione las herramientas de MCP durante la inicialización:

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

Advertencia

DefaultAzureCredential es conveniente para el desarrollo, pero requiere una consideración cuidadosa en producción. En producción, considere la posibilidad de usar una credencial específica (por ejemplo, ManagedIdentityCredential) para evitar problemas de latencia, sondeos de credenciales no deseados y posibles riesgos de seguridad de los mecanismos de reserva.

Puntos clave:

Instrucciones: Proporcione instrucciones claras que se adapten a las funcionalidades de las herramientas de MCP.
Herramientas: convertir las herramientas de MCP en AITool objetos y distribuirlas en la matriz de herramientas
El agente tendrá acceso automáticamente a todas las herramientas proporcionadas por el servidor MCP.

Uso del agente

Una vez configurado, el agente puede usar automáticamente las herramientas de MCP para satisfacer las solicitudes de usuario:

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

El agente hará lo siguiente:

Análisis de la solicitud del usuario
Determinar qué herramientas de MCP son necesarias
Llamar a las herramientas adecuadas a través del servidor MCP
Síntesis de los resultados en una respuesta coherente

Configuración del entorno

Asegúrese de configurar las variables de entorno necesarias:

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

Administración de recursos

Elimine siempre correctamente los recursos de cliente de MCP:

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

El uso await using garantiza que la conexión de cliente MCP se cierre correctamente cuando se quede fuera del ámbito.

Servidores MCP comunes

Entre los servidores MCP populares se incluyen:

@modelcontextprotocol/server-github: acceso a repositorios y datos de GitHub
@modelcontextprotocol/server-filesystem: Operaciones del sistema de archivos
@modelcontextprotocol/server-sqlite: acceso a la base de datos de SQLite

Cada servidor proporciona diferentes herramientas y funcionalidades que amplían la funcionalidad del agente. Esta integración permite a los agentes acceder sin problemas a los datos y servicios externos, a la vez que mantiene las ventajas de seguridad y normalización del protocolo de contexto de modelo.

El código fuente completo e instrucciones para ejecutar este ejemplo está disponible en https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server.

Sugerencia

Consulte los ejemplos de .NET para obtener ejemplos completos de ejecución.

Esto permite a los agentes acceder sin problemas a herramientas y servicios externos.

Tipos de herramientas de MCP

Agent Framework admite tres tipos de conexiones MCP:

MCPStdioTool: servidores MCP locales

Use MCPStdioTool para conectarse a servidores MCP que se ejecutan como procesos locales mediante la entrada y salida estándar:

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

Use MCPStreamableHTTPTool para conectarse a servidores MCP a través de HTTP con eventos de 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: servidores MCP de WebSocket

Use MCPWebsocketTool para conectarse a servidores MCP a través de conexiones de 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())

Servidores MCP populares

Servidores MCP comunes que puede usar con python Agent Framework:

Calculadora: uvx mcp-server-calculator - Cálculos matemáticos
Sistema de archivos: uvx mcp-server-filesystem - Operaciones del sistema de archivos
GitHub: npx @modelcontextprotocol/server-github - Acceso al repositorio de GitHub
SQLite: uvx mcp-server-sqlite - Operaciones de base de datos

Cada servidor proporciona diferentes herramientas y funcionalidades que amplían la funcionalidad del agente al tiempo que mantienen las ventajas de seguridad y normalización del protocolo de contexto de modelo.

Ejemplo completo

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

Exponer un agente como un servidor MCP

Puede exponer un agente como un servidor MCP, lo que le permite usarlo como herramienta por cualquier cliente compatible con MCP (como agentes copilot de GITHub de VS Code u otros agentes). El nombre y la descripción del agente se convierten en los metadatos del servidor MCP.

Encapsular el agente en una herramienta de función mediante .AsAIFunction(), cree un McpServerTooly regístrelo con un servidor 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();

Instale los paquetes NuGet necesarios:

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

Llame .as_mcp_server() a en un agente para exponerlo como un servidor 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()

Configure el servidor MCP para que escuche a través de la entrada y salida estándar:

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)

Pasos siguientes

Uso de flujos de trabajo como agentes

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-02-13