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

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

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

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

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

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

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

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

Это важно

Заголовки для каждого запуска можно указать, включив их в ресурсы инструментов при каждом запуске, или настроить его header_provider на Python локальных средствах MCP. Просмотрите все ключи 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

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

Tip

Полный исходный код и инструкции по выполнению этого примера доступны по 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-клиент, который MCPStreamableHTTPTool создает, не сохраняет файлы cookie ответа. Если серверу требуются файлы cookie для проверки подлинности, сеансов или сопоставления подсистемы балансировки нагрузки, передайте настроенный httpx.AsyncClient с помощью http_client=. Предоставленный клиент сохраняет поведение файла cookie и остается владельцем вызывающего пользователя. Область действия клиента с поддержкой файлов cookie и сеанса средства MCP до одного участника, прошедшего проверку подлинности.

Для конечных точек HTTP, прошедших проверку подлинности, используйте static_headers фиксированные учетные данные или header_provider значения, производные от каждого запуска. Оба пути добавляют заголовки только в запросы настроенного источника и удаляют их из перекрестных перенаправлений. Фиксированные заголовки копируются при создании средства и не сериализуются одновременных вызовов. Если оба параметра предоставляют один и тот же заголовок, динамическое значение из header_provider имеет приоритет.

Во время вызовов header_provider созданного средства получает только узел function_invocation_kwargsзапуска. Он не получает аргументы инструментов, предоставленные моделью, даже если аргумент модели имеет то же имя. Прямой call_tool(...) вызов передает аргументы ключевого слова, предоставленные вызывающим абонентом, поставщику. Значения модели по-прежнему могут иметь приоритет в отдельных объединенных аргументах средства исходящего трафика, но они не управляют заголовками проверки подлинности.

Фиксированные и динамические заголовки вместе образуют эффективное удостоверение сеанса HTTP. Имена заголовков сравниваются без учета регистра, а значения остаются чувствительными к регистру. Аргументы ключевых слов среды выполнения также доступны для исходящих аргументов средства, если схема сервера разрешает то же имя. Чтобы сохранить учетные данные из аргументов средства, захватить их в поставщике с помощью закрытия или использования static_headersили ContextVarпредоставить пользовательский HTTP-клиент.

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

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

Если средство подключается с нетерпением перед выполнением, поставщик получает пустое сопоставление для запросов на время существования подключения. Захватить или обновить учетные данные во время строительства в поставщике для этого случая. Если учетные данные поступают только во время выполнения, передайте неподключаемое средство run(tools=[...]) , function_invocation_kwargs чтобы выполнить установку подключения.

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

Выбор инструментов по однозначному имени

При установке allowed_tools или перечислении средств approval_modeиспользуйте необработанное имя удаленного средства или однозначное префиксное имя. Если одно настроенное имя соответствует нескольким необработанным удаленным именам после нормализации, агент Framework вызывает ToolExecutionException. Используйте точное необработанное имя или изменение tool_name_prefix , чтобы сделать локальные имена уникальными.

Отмена выборки MCP

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

Выборка MCP, инициированная сервером, и sampling_callback не рекомендуется использовать в спецификации MCP версии 2026-07-28 и удаляется не позднее 2027-07-28. Не создавайте новые интеграции с этой функцией. Серверы MCP должны вызывать API поставщика моделей напрямую.

Хранение полезных данных узла управления

Когда транспорт узла, например AG-UI, использует результат средства MCP, Agent Framework сохраняет полный безопасный результат JSON отдельно от синтаксического значения модели. Это позволяет узлу получать такие поля, как structuredContent без добавления данных только узла в журнал моделей.

Используйте tool_result_content любой транспорт MCP для выбора видимого для модели значения, если результат содержит оба content и structuredContent:

Ценность Видимый результат модели
structured_first Используется structuredContent при наличии, в противном случае content. Это значение является значением по умолчанию.
content_first Использует nonempty content, в противном случае structuredContent.
content_only Игнорирует structuredContent.
structured_only Игнорирует content.
both Добавляет сериализованный structuredContent после content блоков.

Этот выбор не изменяет полезные данные сохраненного узла. parse_tool_results переопределяет политику выбора.

Каждый транспорт MCP ограничивает сохраненную полезные данные узла до 1 МиБ по умолчанию. Неуправляемые полезные данные пропускаются из канала узла, а результат синтаксического анализа по-прежнему достигает модели. Задайте другое положительное ограничение байтов на транспорте или используйте None только в том случае, если подчиненный узел применяет собственную привязку:

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

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, которые можно использовать с платформой агента 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 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())

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

Пакет mcptool позволяет агентам использовать средства на серверах протокола контекста модели (MCP).

Подключение к серверу 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()

Перечисление и использование средств 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()

Поддерживаемые транспорты

  • HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
  • Stdio — запуск локального процесса сервера MCP

Tip

Полный пример запуска см. в примере средств MCP .

Предоставление агента в качестве сервера 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)

Обтекайте агент agenttool.New, зарегистрируйте его с помощью mcptool.AddToolсервера MCP и запустите сервер по 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

См. пример средства MCP агента для полного запуска.

Дальнейшие действия

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

  • Last updated on