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 de su uso de servicios y datos que no son de Microsoft, junto con los cargos asociados con ese uso.

Los servidores MCP remotos que decide usar con la herramienta MCP descrita en este artículo se crearon por 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.

Important

Puede especificar encabezados por ejecución incluyéndolas en recursos de herramientas en cada ejecución o configurando un header_provider en Python herramientas de MCP locales. Revise las claves de API, los tokens de acceso de OAuth u otras credenciales compartidas con servidores MCP remotos.

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

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:

  1. Configuración y servidor MCP
  2. Recuperar la lista de herramientas disponibles del servidor MCP
  3. Convertir las herramientas de MCP en AIFunctionpara que se puedan agregar a un agente
  4. 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:

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

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:

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

Warning

DefaultAzureCredential es conveniente para el desarrollo, pero requiere una consideración cuidadosa en producción. En producción, considere 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 respaldo.

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:

  1. Análisis de la solicitud del usuario
  2. Determinar qué herramientas de MCP son necesarias
  3. Llamar a las herramientas adecuadas a través del servidor MCP
  4. 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 McpClient.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.

Tip

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

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

Note

En las instalaciones mínimas de Python, es posible que sea necesario instalar manualmente la compatibilidad con MCP. Instale mcp --pre para usar MCPStdioTool, MCPStreamableHTTPToolo Agent.as_mcp_server(). Instale mcp[ws] --pre si también necesita MCPWebsocketTool.

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

El cliente HTTP que MCPStreamableHTTPTool crea no conserva las cookies de respuesta. Si el servidor requiere cookies para la autenticación, las sesiones o la afinidad del equilibrador de carga, pase un configurado httpx.AsyncClient a través de http_client=. El cliente proporcionado conserva su comportamiento de cookies y sigue siendo propiedad del autor de la llamada. Ámbito de un cliente de rodamiento de cookies y su sesión de herramientas MCP en una entidad de seguridad autenticada.

Para los puntos de conexión HTTP autenticados, use static_headers para credenciales fijas o header_provider para valores derivados de cada ejecución. Ambas rutas de acceso agregan encabezados solo a las solicitudes del origen configurado y los quitan de redirecciones entre orígenes. Los encabezados fijos se copian cuando se crea la herramienta y no serializan llamadas simultáneas. Cuando ambas opciones proporcionan el mismo encabezado, el valor dinámico de header_provider tiene prioridad.

Durante las llamadas de herramienta generadas, header_provider solo recibe el host function_invocation_kwargsde la ejecución. No recibe argumentos de herramienta proporcionados por el modelo, incluso cuando un argumento de modelo tiene el mismo nombre. Una llamada directa call_tool(...) pasa sus argumentos de palabra clave proporcionados por el autor de la llamada al proveedor. Los valores del modelo todavía pueden tener prioridad en los argumentos de la herramienta de salida combinadas por separado, pero no controlan los encabezados de autenticación.

Los encabezados fijos y dinámicos forman juntos la identidad efectiva de la sesión HTTP. Los nombres de encabezado se comparan sin distinción entre mayúsculas y minúsculas, mientras que los valores siguen distinguen mayúsculas de minúsculas. Los argumentos de palabra clave runtime también son aptos para los argumentos de la herramienta de salida cuando el esquema del servidor permite el mismo nombre. Para mantener las credenciales fuera de los argumentos de la herramienta, capturelas en el proveedor a través de un cierre o ContextVar, use static_headerso proporcione un cliente HTTP personalizado.

Las sesiones de propiedad del marco enlazan esta identidad efectiva cuando se conectan. Si una ejecución posterior genera una identidad diferente, la herramienta se vuelve a conectar antes de enviar la llamada y actualiza la herramienta derivada de la sesión y solicita la detección. Inicializar, detectar, hacer ping en segundo plano y otras solicitudes de duración de conexión siguen usando los encabezados enlazados a esa sesión.

Las sesiones proporcionadas por el autor de la llamada siguen siendo propiedad del autor de la llamada. Dado que el contenedor no puede establecer ni volver a conectar una identidad desconocida para esas sesiones, se rechaza la resolución dinámica de encabezados con una identidad desconocida. También se rechaza una identidad modificada; use una instancia de herramienta administrada por marco independiente.

Si la herramienta se conecta diligentemente antes de una ejecución, el proveedor recibe una asignación vacía para las solicitudes de duración de la conexión. Capture o actualice una credencial en tiempo de construcción en el proveedor para este caso. Si una credencial solo llega en tiempo de ejecución, pase la herramienta no conectada con run(tools=[...]) para function_invocation_kwargs que la ejecución establezca la conexión.

Un KeyError elemento del proveedor solo se tolera cuando no se ha inicializado ninguna ejecución de la conexión y la solicitud continúa sin encabezados de proveedor. Después de ejecutar la conexión, falta una clave es un error de configuración y se muestra la excepción.

Selección de herramientas por nombre no ambiguo

Al establecer allowed_tools o enumerar herramientas en approval_mode, use el nombre de la herramienta remota sin procesar o un nombre prefijo no ambiguo. Si un nombre configurado coincide con varios nombres remotos ToolExecutionExceptionsin procesar después de la normalización, Agent Framework genera . Use un nombre sin formato exacto o un cambio tool_name_prefix para que los nombres locales sean únicos.

Desuso de muestreo de MCP

Warning

El muestreo mcP iniciado por el servidor y sampling_callback está en desuso a partir de la versión 2026-07-28 de la especificación MCP y se quitan a más tardar 2027-07-28. No cree nuevas integraciones en esta característica. Los servidores MCP deben llamar directamente a las API del proveedor de modelos.

Controlar la retención de la carga del host

Cuando un transporte de host, como AG-UI, consume un resultado de la herramienta MCP, Agent Framework conserva el resultado completo seguro de JSON por separado del valor orientado al modelo analizado. Esto permite que el host reciba campos como, por structuredContent ejemplo, sin agregar datos de solo host al historial del modelo.

Use tool_result_content en cualquier transporte MCP para seleccionar el valor visible del modelo cuando un resultado contiene y contentstructuredContent:

Value Resultado visible del modelo
structured_first Usa structuredContent cuando está presente; de lo contrario content, . Este valor es el predeterminado.
content_first Usa noempty content; en caso contrario structuredContent, .
content_only structuredContentOmite .
structured_only contentOmite .
both Anexa serializados structuredContent después de los content bloques.

Esta selección no cambia la carga del host retenido. parse_tool_results invalida la directiva de selección.

Cada transporte de MCP limita una carga de host retenido a 1 MiB de forma predeterminada. Las cargas sobredimensionadas se omiten del canal host, mientras que el resultado analizado sigue alcanzando el modelo. Establezca un límite de bytes positivo diferente en el transporte o use None solo cuando el host de bajada aplique su propio límite:

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

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

Tipos de herramientas de MCP

El mcptool paquete permite a los agentes usar herramientas de servidores del Protocolo de contexto de modelo (MCP).

Conexión a un servidor 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()

Enumerar y usar herramientas de 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()

Transportes compatibles

  • HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
  • Stdio : inicio de un proceso de servidor MCP local

Tip

Consulte el ejemplo de herramientas de MCP para obtener un ejemplo completo de ejecución.

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

Warning

DefaultAzureCredential es conveniente para el desarrollo, pero requiere una consideración cuidadosa en producción. En producción, considere 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 respaldo.

Instale los paquetes NuGet necesarios:

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

Llame .as_mcp_server() a en un agente para exponerlo como un servidor MCP:

Note

Python agent.as_mcp_server() también depende del paquete opcional mcp . Si usa una instalación basada en slim/core, ejecute pip install mcp --pre primero.

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

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)

Encapsula el agente con agenttool.New, regístrelo con un servidor MCP mediante mcptool.AddTooly ejecute el servidor a través de 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

Consulte el ejemplo de herramienta MCP como agente para obtener un ejemplo completo de ejecución.

Pasos siguientes

Conversaciones y memoria

  • Last updated on