Использование средств MCP с агентами

Протокол контекста модели — это открытый стандарт, определяющий, как приложения предоставляют средства и контекстные данные для больших языковых моделей (LLM). Она обеспечивает согласованную масштабируемую интеграцию внешних инструментов с рабочими процессами модели.

Microsoft Agent Framework поддерживает интеграцию с серверами ПРОТОКОЛА MCP модели, позволяя агентам получать доступ к внешним средствам и службам. В этом руководстве показано, как подключиться к серверу MCP и использовать его средства в агенте.

Рекомендации по использованию сторонних серверов MCP

Использование серверов протокола контекста модели зависит от условий между вами и поставщиком услуг. При подключении к службе, отличной от Майкрософт, некоторые данные (например, содержимое запроса) передаются в службу, не являющейся корпорацией Майкрософт, или ваше приложение может получать данные из службы, отличной от Майкрософт. Вы несете ответственность за использование служб и данных, отличных от Майкрософт, а также за любые расходы, связанные с этим использованием.

Удаленные серверы MCP, которые вы решили использовать с средством MCP, описанным в этой статье, были созданы сторонними лицами, а не корпорацией Майкрософт. Корпорация Майкрософт не тестировала или проверяла эти серверы. Корпорация Майкрософт не несет ответственности за вас или других пользователей в отношении использования любых удаленных серверов MCP.

Мы рекомендуем тщательно проверить и отслеживать, какие серверы MCP добавляются в приложения на основе Agent Framework. Мы также рекомендуем полагаться на серверы, размещенные доверенными поставщиками услуг, а не прокси-серверами.

Средство MCP позволяет передавать пользовательские заголовки, такие как ключи проверки подлинности или схемы, которые может потребоваться удаленному серверу MCP. Рекомендуется просмотреть все данные, к которым предоставлен общий доступ с удаленными серверами MCP, и записывать данные в журнал для целей аудита. Будьте осведомлены о практиках, отличных от Майкрософт, о хранении и расположении данных.

Это важно

Заголовки можно указать только в tool_resources при каждом запуске. Таким образом вы можете поместить ключи API, маркеры доступа OAuth или другие учетные данные непосредственно в запросе. Заголовки, переданные вами, доступны только для текущего запуска и не сохраняются.

Дополнительные сведения о безопасности MCP см. в следующем разделе:

• Рекомендации по обеспечению безопасности на веб-сайте протокола контекста модели.
• Понимание и устранение рисков безопасности в реализации MCP в блоге сообщества майкрософт.

Версию .NET Agent Framework можно использовать вместе с официальным пакетом SDK MCP C# , чтобы разрешить агенту вызывать инструменты MCP.

В следующем примере показано, как:

1. Настройка и сервер MCP
2. Получение списка доступных средств с сервера MCP
3. Преобразование средств AIFunctionMCP в "так, чтобы их можно было добавить в агент"
4. Вызов средств из агента с помощью вызова функции

Настройка клиента MCP

Сначала создайте клиент MCP, который подключается к нужному серверу MCP:

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

В этом примере:

• Имя: понятное имя для подключения сервера MCP
• Команда: исполняемый файл для запуска сервера MCP (здесь используется npx для запуска пакета Node.js)
• Аргументы: аргументы командной строки, передаваемые серверу MCP

Получение доступных средств

После подключения получите список инструментов, доступных на сервере MCP:

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

Метод ListToolsAsync() возвращает коллекцию инструментов, предоставляемых сервером MCP. Эти средства автоматически преобразуются в объекты AITool, которые можно использовать агентом.

Создание агента с помощью средств MCP

Создайте агент и предоставьте средства MCP во время инициализации:

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

Предупреждение

DefaultAzureCredential удобно для разработки, но требует тщательного рассмотрения в рабочей среде. В рабочей среде рекомендуется использовать определенные учетные данные (например, ManagedIdentityCredential), чтобы избежать проблем с задержкой, непреднамеренного проверки учетных данных и потенциальных рисков безопасности из резервных механизмов.

Основные моменты:

• Инструкции. Укажите четкие инструкции, которые соответствуют возможностям средств MCP
• Средства. Приведение средств MCP к AITool объектам и их распространение в массив инструментов
• Агент автоматически получит доступ ко всем средствам, предоставляемым сервером MCP

Использование агента

После настройки агент может автоматически использовать средства MCP для выполнения запросов пользователей:

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

Агент:

1. Анализ запроса пользователя
2. Определение необходимых средств MCP
3. Вызов соответствующих средств с помощью сервера MCP
4. Синтезирование результатов в последовательный ответ

Конфигурация среды

Обязательно настройте необходимые переменные среды:

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

Управление ресурсами

Всегда правильно удалять клиентские ресурсы MCP:

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

Использование await using обеспечивает правильное закрытие подключения клиента MCP при выходе из области.

Общие серверы MCP

Популярные серверы MCP включают:

• @modelcontextprotocol/server-github: доступ к репозиториям и данным GitHub
• @modelcontextprotocol/server-filesystem: операции файловой системы
• @modelcontextprotocol/server-sqlite: доступ к базе данных SQLite

Каждый сервер предоставляет различные средства и возможности, расширяющие функциональные возможности агента. Эта интеграция позволяет агентам легко получать доступ к внешним данным и службам, сохраняя преимущества безопасности и стандартизации протокола контекста модели.

Подсказка

Полный исходный код и инструкции по выполнению этого примера доступны по https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/ModelContextProtocol/Agent_MCP_Serverадресу.

Это позволяет агентам легко получать доступ к внешним средствам и службам.

Замечание

При минимальных установках Python может потребоваться установить поддержку MCP вручную. Установите mcp --pre для использования MCPStdioTool, MCPStreamableHTTPToolили Agent.as_mcp_server(). Установите, mcp[ws] --pre если вам также нужно MCPWebsocketTool.

Типы инструментов MCP

Платформа агента поддерживает три типа подключений MCP:

MCPStdioTool — локальные серверы MCP

Используйте MCPStdioTool для подключения к серверам MCP, которые выполняются в качестве локальных процессов с помощью стандартных входных и выходных данных:

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 — серверы HTTP/SSE MCP

Используется MCPStreamableHTTPTool для подключения к серверам MCP по протоколу HTTP с помощью событий 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())

Для конечных точек HTTP, прошедших проверку подлинности, предпочитайте header_provider вместе с function_invocation_kwargs тем, чтобы секреты оставались в контексте среды выполнения, а не запекаться в общем HTTP-клиенте.

MCPWebsocketTool — серверы WebSocket MCP

Используйте MCPWebsocketTool для подключения к серверам MCP через подключения 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())

Популярные серверы MCP

Общие серверы MCP, которые можно использовать с платформой агента Python:

• Калькулятор: uvx mcp-server-calculator — математические вычисления
• Файловая система: uvx mcp-server-filesystem — операции файловой системы
• GitHub: npx @modelcontextprotocol/server-github — доступ к репозиторию GitHub
• SQLite: uvx mcp-server-sqlite — операции базы данных

Каждый сервер предоставляет различные средства и возможности, расширяющие функциональные возможности агента, сохраняя преимущества безопасности и стандартизации протокола контекста модели.

Полный пример

# 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 the runtime `header_provider` pattern for authenticating with MCP servers.

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 {kwargs['mcp_api_key']}"},
        ),
    ) as agent:
        query = "What tools are available to you?"
        print(f"User: {query}")
        result = await agent.run(
            query,
            function_invocation_kwargs={"mcp_api_key": api_key},
        )
        print(f"Agent: {result.text}")

if __name__ == "__main__":
    asyncio.run(api_key_auth_example())

Предоставление агента в качестве сервера MCP

Агент можно предоставлять в качестве сервера MCP, позволяя использовать его в качестве средства любым клиентом, совместимым с MCP (например, агентами GitHub Copilot или другими агентами VS Code). Имя и описание агента становятся метаданными сервера MCP.

Обтекайте агент в инструменте функции, .AsAIFunction()создайте McpServerToolи зарегистрируйте его на сервере 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();

Предупреждение

DefaultAzureCredential удобно для разработки, но требует тщательного рассмотрения в рабочей среде. В рабочей среде рекомендуется использовать определенные учетные данные (например, ManagedIdentityCredential), чтобы избежать проблем с задержкой, непреднамеренного проверки учетных данных и потенциальных рисков безопасности из резервных механизмов.

Установите необходимые пакеты NuGet:

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

Вызов .as_mcp_server() агента для предоставления его в качестве сервера MCP:

Замечание

Python agent.as_mcp_server() также зависит от необязательного mcp пакета. Если вы используете установку на основе тонких и ядер, запустите сначала pip install mcp --pre .

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

Настройте сервер MCP для прослушивания стандартных входных и выходных данных:

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)

Дальнейшие шаги

Беседы и память