Использование средств 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 AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         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/GettingStarted/ModelContextProtocol/Agent_MCP_Serverадресу.

Подсказка

Полные примеры запуска см. в примерах .NET .

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

Типы инструментов 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(
            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 — серверы HTTP/SSE MCP

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

Популярные серверы 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 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}")

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

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

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

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

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

Вызов .as_mcp_server() агента для предоставления его в качестве сервера 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()

Настройте сервер 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)

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

Использование рабочих процессов в качестве агентов