Подключение агентов к серверам протокола контекста модели

Подключите ваши агенты Foundry к серверам протокола Model Context Protocol (MCP) с помощью средства MCP. Это расширяет возможности агента с внешними инструментами и источниками данных. Подключився к удаленным конечным точкам сервера MCP, агенты могут получить доступ к средствам, размещенным разработчиками и организациями, которые могут использовать клиенты, совместимые с MCP, такие как Служба агента Foundry.

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

В этой статье вы узнаете, как:

• Добавьте удаленный сервер MCP в качестве средства.
• Проверка подлинности на сервере MCP с помощью подключения к проекту.
• Проверка и утверждение вызовов инструментов MCP.
• Устранение распространенных проблем интеграции MCP.

Концептуальные сведения о том, как работает интеграция MCP, см. в статье о том, как она работает.

Поддержка использования

В следующей таблице показана поддержка пакета SDK и настройки подключений MCP. В следующей таблице показана поддержка пакета SDK и настройки.

Поддержка Microsoft Foundry	пакет SDK Python	Пакет SDK для C#	Пакет SDK для JavaScript	пакет SDK Java	REST API	Базовая настройка агента	Настройка стандартного агента
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Предпосылки

Прежде чем начать, убедитесь, что у вас есть следующее:

• Подписка Azure с активным проектом Microsoft Foundry.
• Azure управление доступом на основе ролей (RBAC): роль участника или владельца проекта Foundry.
• Последний пакет SDK для вашего языка. Пакет SDK для .NET в настоящее время находится в предварительной версии. Дополнительные сведения об установке см. в кратком руководстве .
• Azure учетные данные, настроенные для проверки подлинности (например, DefaultAzureCredential).
• Доступ к удаленной конечной точке сервера MCP (например, на https://api.githubcopilot.com/mcpсервере MCP GitHub).

Общедоступные и частные конечные точки сервера MCP

Служба агента поддерживает как общедоступные, так и частные конечные точки сервера MCP:

• Общедоступные конечные точки: подключение к любому общедоступному удаленному серверу MCP. Этот параметр работает с настройками агента "Базовый" и "Стандартный".
• Частные конечные точки: подключение к серверам MCP, которые не доступны в общедоступном интернете. Для частной MCP требуется настройка стандартного агента с частным сетевым взаимодействием и выделенной подсети MCP в рамках виртуальной сети.

Для частных серверов MCP разверните сервер MCP в Azure Container Apps с только внутренним шлюзом на выделенной подсети MCP, делегированной Microsoft.App/environments. Чтобы приступить к работе, используйте шаблон 19-hybrid-private-resources-agent-setup , который подготавливает необходимую сетевую инфраструктуру, включая подсеть MCP.

Дополнительные сведения о поддержке средств в изолированных от сети средах см. в разделе "Средства агента" с сетевой изоляцией.

Authentication

Для многих серверов MCP требуется проверка подлинности.

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

Для получения сведений о поддерживаемых параметрах аутентификации (на основе ключей, идентификациях Microsoft Entra и сквозной передачи идентификаций OAuth) см. статью MCP server authentication.

Замечание

Задайте project_connection_id для идентификатора подключения вашего проекта.

Подсказка

При добавлении MCP сервера Azure DevOps (предварительная версия) через каталог Добавление инструментов, аутентификация в Azure DevOps устанавливается на этапе подключения к организации и сохраняется как подключение к проекту. Используйте минимально необходимые привилегии доступа и проверьте области при подключении организации.

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

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

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

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

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

Лучшие практики

Общие рекомендации по использованию инструментов см. в рекомендациях по использованию средств в службе Microsoft Foundry Agent.

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

• Предпочитайте список разрешений инструментов с помощью allowed_tools.
• Требовать утверждения для операций с высоким риском (особенно средства, которые записывают данные или изменяют ресурсы).
• Перед утверждением просмотрите запрашиваемое название инструмента и его аргументы.
• Журналирование утверждений и вызовов инструментов для аудита и устранения неполадок.

Подсказка

При добавлении сервера Azure DevOps MCP через каталог "Добавление инструментов " конфигурация выбора инструментов сопоставляется с поведением, описанным allowed_tools в этой статье. Выбор подмножества инструментов в пользовательском интерфейсе каталога эквивалентен указанию allowed_tools списка в коде.

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

Используйте следующий пример кода, чтобы создать агент и вызвать функцию. Пакет SDK для .NET в настоящее время находится в предварительной версии. Дополнительные сведения см. в кратком руководстве .

В следующем примере показано, как использовать сервер MCP GitHub в качестве средства для агента.

import json
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool
from openai.types.responses.response_input_param import McpApprovalResponse, ResponseInputParam

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
MCP_CONNECTION_NAME = "my-mcp-connection"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# [START tool_declaration]
tool = MCPTool(
    server_label="api-specs",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id=MCP_CONNECTION_NAME,
)
# [END tool_declaration]

# Create a prompt agent with MCP tool capabilities
agent = project.agents.create_version(
    agent_name="MyAgent7",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="Use MCP tools as needed",
        tools=[tool],
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Create a conversation to maintain context across multiple interactions
conversation = openai.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Send initial request that will trigger the MCP tool
response = openai.responses.create(
    conversation=conversation.id,
    input="What is my username in my GitHub profile?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

# Process any MCP approval requests that were generated
input_list: ResponseInputParam = []
for item in response.output:
    if item.type == "mcp_approval_request" and item.id:
        print("MCP approval requested")
        print(f"  Server: {item.server_label}")
        print(f"  Tool: {getattr(item, 'name', '<unknown>')}")
        print(
            f"  Arguments: {json.dumps(getattr(item, 'arguments', None), indent=2, default=str)}"
        )

        # Approve only after you review the tool call.
        # In production, implement your own approval UX and policy.
        should_approve = (
            input("Approve this MCP tool call? (y/N): ").strip().lower() == "y"
        )
        input_list.append(
            McpApprovalResponse(
                type="mcp_approval_response",
                approve=should_approve,
                approval_request_id=item.id,
            )
        )

# Send the approval response back to continue the agent's work
response = openai.responses.create(
    input=input_list,
    previous_response_id=response.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response: {response.output_text}")

# Clean up resources by deleting the agent version
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при запуске примера:

Agent created (id: <agent-id>, name: MyAgent7, version: 1)
Created conversation (id: <conversation-id>)
Response: Your GitHub username is "example-username".
Agent deleted

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

В следующем примере показано, как использовать сервер MCP GitHub в качестве средства для агента. В примере используются синхронные методы для создания агента. Асинхронные методы см. в примере кода в репозитории Azure SDK для .NET на GitHub.

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create Agent with the `MCPTool`. Note that in this scenario 
// GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval is used,
// which means that any calls to the MCP server must be approved.
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
    Tools = { ResponseTool.CreateMcpTool(
        serverLabel: "api-specs",
        serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
    )) }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// If the tool approval is required, the response item is
// of `McpToolCallApprovalRequestItem` type and contains all
// the information about tool call. This example checks that
// the server label is "api-specs" and approves the tool call.
// All other calls are denied because they should not occur for
// the current configuration.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

CreateResponseOptions nextResponseOptions = new([ResponseItem.CreateUserMessageItem("Please summarize the Azure REST API specifications README")]);
ResponseResult latestResponse = null;

while (nextResponseOptions is not null)
{
    latestResponse = responseClient.CreateResponse(nextResponseOptions);
    nextResponseOptions = null;

    foreach (ResponseItem responseItem in latestResponse.OutputItems)
    {
        if (responseItem is McpToolCallApprovalRequestItem mcpToolCall)
        {
            nextResponseOptions = new CreateResponseOptions()
            {
                PreviousResponseId = latestResponse.Id,
            };
            if (string.Equals(mcpToolCall.ServerLabel, "api-specs"))
            {
                Console.WriteLine($"Approval requested for {mcpToolCall.ServerLabel} (tool: {mcpToolCall.ToolName})");
                Console.Write("Approve this MCP tool call? (y/N): ");
                bool approved = string.Equals(Console.ReadLine(), "y", StringComparison.OrdinalIgnoreCase);
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: approved));
            }
            else
            {
                Console.WriteLine($"Rejecting unknown call {mcpToolCall.ServerLabel}...");
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: false));
            }
        }
    }
}

// Output the final response from the agent.
Console.WriteLine(latestResponse.GetOutputText());

// Clean up resources by deleting the agent version.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при запуске примера:

Approval requested for api-specs...
Response: The Azure REST API specifications repository contains the OpenAPI specifications for Azure services. It is
organized by service and includes guidelines for contributing new specifications. The repository is intended for use by developers building tools and services that interact with Azure APIs.

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

В этом примере вы узнаете, как пройти проверку подлинности на сервере MCP GitHub и использовать его в качестве инструмента для агента. В примере используются синхронные методы для создания агента. Асинхронные методы см. в примере кода в репозитории Azure SDK для .NET на GitHub.

Настройка подключения проекта

Перед выполнением примера:

1. Войдите в свой профиль GitHub.
2. Выберите рисунок профиля в правом верхнем углу.
3. Выберите Параметры.
4. На левой панели выберите "Параметры разработчика" и "Личные маркеры > доступа" (классическая модель).
5. В верхней части выберите "Создать новый маркер", введите пароль и создайте маркер, который может читать общедоступные репозитории.
   • Важно: Сохраните маркер или оставьте страницу открытой, так как после закрытия страницы не удается снова отображать маркер.
6. На портале Azure откройте Microsoft Foundry.
7. На левой панели выберите центр управления и выберите "Подключенные ресурсы".
8. Создайте новое соединение типа пользовательских ключей.
9. Назовите его и добавьте пару "значение ключа".
10. Задайте имя Authorization ключа и значение должно иметь форму Bearer your_github_token.

Пример кода для создания агента

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var mcpConnectionName = "my-mcp-connection";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create an agent with the MCPTool. Note that, in this scenario,
// GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval is used.
// This means that any calls to the MCP server must be approved.
// The ProjectConnectionId property is then set on the McpTool
// so agent can authenticate with GitHub.
McpTool tool = ResponseTool.CreateMcpTool(
        serverLabel: "api-specs",
        serverUri: new Uri("https://api.githubcopilot.com/mcp"),
        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
    ));
tool.ProjectConnectionId = mcpConnectionName;
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
    Tools = { tool }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// If the tool approval is required, the response item is
// of McpToolCallApprovalRequestItem type and contains all
// the information about tool call. This example checks that
// the server label is "api-specs" and approves the tool call,
// All other calls are denied because they shouldn't happen given
// the current configuration.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

CreateResponseOptions nextResponseOptions = new([ResponseItem.CreateUserMessageItem("What is my username in my GitHub profile?")]);
ResponseResult latestResponse = null;

while (nextResponseOptions is not null)
{
    latestResponse = responseClient.CreateResponse(nextResponseOptions);
    nextResponseOptions = null;

    foreach (ResponseItem responseItem in latestResponse.OutputItems)
    {
        if (responseItem is McpToolCallApprovalRequestItem mcpToolCall)
        {
            nextResponseOptions = new()
            {
                PreviousResponseId = latestResponse.Id,
            };
            if (string.Equals(mcpToolCall.ServerLabel, "api-specs"))
            {
                Console.WriteLine($"Approval requested for {mcpToolCall.ServerLabel} (tool: {mcpToolCall.ToolName})");
                Console.Write("Approve this MCP tool call? (y/N): ");
                bool approved = string.Equals(Console.ReadLine(), "y", StringComparison.OrdinalIgnoreCase);
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: approved));
            }
            else
            {
                Console.WriteLine($"Rejecting unknown call {mcpToolCall.ServerLabel}...");
                nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: false));
            }
        }
    }
}

// Output the final response from the agent.
Console.WriteLine(latestResponse.GetOutputText());

// Clean up resources by deleting the agent version.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при запуске примера:

Approval requested for api-specs...
Response: Your GitHub username is "example-username".

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

В следующем примере TypeScript показано, как создать агент с возможностями средства MCP, отправлять запросы, которые активируют рабочие процессы утверждения MCP, обрабатывают запросы на утверждение и очищают ресурсы. Сведения о версии JavaScript можно найти в образце кода в репозитории Azure SDK для JavaScript на GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import OpenAI from "openai";
import * as readline from "readline";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating agent with MCP tool...");

  // Define MCP tool that connects to Azure REST API specifications GitHub repository
  // The tool requires approval for each operation to ensure user control over external requests
  const agent = await project.agents.createVersion("agent-mcp", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions:
      "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
    tools: [
      {
        type: "mcp",
        server_label: "api-specs",
        server_url: "https://gitmcp.io/Azure/azure-rest-api-specs",
        require_approval: "always",
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Create a conversation thread to maintain context across multiple interactions
  console.log("\nCreating conversation...");
  const conversation = await openai.conversations.create();
  console.log(`Created conversation (id: ${conversation.id})`);

  // Send initial request that will trigger the MCP tool to access Azure REST API specs
  // This will generate an approval request since requireApproval="always"
  console.log("\nSending request that will trigger MCP approval...");
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Please summarize the Azure REST API specifications Readme",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  // Process any MCP approval requests that were generated
  // When requireApproval="always", the agent will request permission before accessing external resources
  const inputList: OpenAI.Responses.ResponseInputItem.McpApprovalResponse[] = [];

  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
  for (const item of response.output) {
    if (item.type === "mcp_approval_request") {
      if (item.server_label === "api-specs" && item.id) {
        console.log(`\nReceived MCP approval request (id: ${item.id})`);
        console.log(`  Server: ${item.server_label}`);
        console.log(`  Tool: ${item.name}`);

        // Approve only after you review the tool call.
        // In production, implement your own approval UX and policy.
        const answer = (await ask("Approve this MCP tool call? (y/N): ")).trim().toLowerCase();
        const approve = answer === "y";
        inputList.push({
          type: "mcp_approval_response",
          approval_request_id: item.id,
          approve,
        });
      }
    }
  }

  rl.close();

  console.log(`\nProcessing ${inputList.length} approval request(s)`);
  console.log("Final input:");
  console.log(JSON.stringify(inputList, null, 2));

  // Send the approval response back to continue the agent's work
  // This allows the MCP tool to access the GitHub repository and complete the original request
  console.log("\nSending approval response...");
  const finalResponse = await openai.responses.create(
    {
      input: inputList,
      previous_response_id: response.id,
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  console.log(`\nResponse: ${finalResponse.output_text}`);

  // Clean up resources by deleting the agent version and conversation
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await openai.conversations.delete(conversation.id);
  console.log("Conversation deleted");

  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nMCP sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при запуске примера:

Creating agent with MCP tool...
Agent created (id: <agent-id>, name: agent-mcp, version: 1)

Creating conversation...
Created conversation (id: <conversation-id>)

Sending request that will trigger MCP approval...

Received MCP approval request (id: <approval-request-id>)
  Server: api-specs
  Tool: get-readme

Processing 1 approval request(s)
Final input:
[
  {
    "type": "mcp_approval_response",
    "approval_request_id": "<approval-request-id>",
    "approve": true
  }
]

Sending approval response...

Response: The Azure REST API specifications repository contains the OpenAPI specifications for Azure services. It is organized by service and includes guidelines for contributing new specifications. The repository is intended for use by developers building tools and services that interact with Azure APIs.

Cleaning up resources...
Conversation deleted
Agent deleted

MCP sample completed!

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

В следующем примере TypeScript показано, как создать агент с возможностями средства MCP с помощью проверки подлинности подключения к проекту, отправлять запросы, которые активируют рабочие процессы утверждения MCP, обрабатывают запросы на утверждение и очищают ресурсы. Сведения о версии JavaScript можно найти в образце кода в репозитории Azure SDK для JavaScript на GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import OpenAI from "openai";
import * as readline from "readline";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const MCP_CONNECTION_NAME = "my-mcp-connection";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating agent with MCP tool using project connection...");

  // Define MCP tool that connects to GitHub Copilot API with project connection authentication
  // The project connection should have Authorization header configured with "Bearer <GitHub PAT token>"
  // Token can be created at https://github.com/settings/personal-access-tokens/new
  const agent = await project.agents.createVersion("agent-mcp-connection-auth", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "Use MCP tools as needed",
    tools: [
      {
        type: "mcp",
        server_label: "api-specs",
        server_url: "https://api.githubcopilot.com/mcp",
        require_approval: "always",
        project_connection_id: MCP_CONNECTION_NAME,
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Create a conversation thread to maintain context across multiple interactions
  console.log("\nCreating conversation...");
  const conversation = await openai.conversations.create();
  console.log(`Created conversation (id: ${conversation.id})`);

  // Send initial request that will trigger the MCP tool
  console.log("\nSending request that will trigger MCP approval...");
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "What is my username in my GitHub profile?",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  // Process any MCP approval requests that were generated
  const inputList: OpenAI.Responses.ResponseInputItem.McpApprovalResponse[] = [];

  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
  for (const item of response.output) {
    if (item.type === "mcp_approval_request") {
      if (item.server_label === "api-specs" && item.id) {
        console.log(`\nReceived MCP approval request (id: ${item.id})`);
        console.log(`  Server: ${item.server_label}`);
        console.log(`  Tool: ${item.name}`);

        // Approve only after you review the tool call.
        // In production, implement your own approval UX and policy.
        const answer = (await ask("Approve this MCP tool call? (y/N): ")).trim().toLowerCase();
        const approve = answer === "y";
        inputList.push({
          type: "mcp_approval_response",
          approval_request_id: item.id,
          approve,
        });
      }
    }
  }

  rl.close();

  console.log(`\nProcessing ${inputList.length} approval request(s)`);
  console.log("Final input:");
  console.log(JSON.stringify(inputList, null, 2));

  // Send the approval response back to continue the agent's work
  // This allows the MCP tool to access the GitHub repository and complete the original request
  console.log("\nSending approval response...");
  const finalResponse = await openai.responses.create(
    {
      input: inputList,
      previous_response_id: response.id,
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  console.log(`\nResponse: ${finalResponse.output_text}`);

  // Clean up resources by deleting the agent version and conversation
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await openai.conversations.delete(conversation.id);
  console.log("Conversation deleted");

  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nMCP with project connection sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при запуске примера:

Creating agent with MCP tool using project connection...
Agent created (id: <agent-id>, name: agent-mcp-connection-auth, version: 1)
Creating conversation...
Created conversation (id: <conversation-id>)
Sending request that will trigger MCP approval...
Received MCP approval request (id: <approval-request-id>)
  Server: api-specs
  Tool: get-github-username
Processing 1 approval request(s)
Final input:
[
  {
    "type": "mcp_approval_response",
    "approval_request_id": "<approval-request-id>",
    "approve": true
  }
]
Sending approval response...
Response: Your GitHub username is "example-username".
Cleaning up resources...
Conversation deleted
Agent deleted
MCP with project connection sample completed!

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

Добавьте зависимость в вашу pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.0</version>
</dependency>

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

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.McpTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class McpToolExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String mcpConnectionName = "my-mcp-connection";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create MCP tool with server label, URL, connection, and approval mode
        McpTool mcpTool = new McpTool("api-specs")
            .setServerUrl("https://gitmcp.io/Azure/azure-rest-api-specs")
            .setProjectConnectionId(mcpConnectionName)
            .setRequireApproval("always");

        // Create agent with MCP tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a helpful assistant that can use MCP tools.")
            .setTools(Collections.singletonList(mcpTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("mcp-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("Summarize the Azure REST API specifications"));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

Ожидаемые выходные данные

Agent created: mcp-agent (version 1)
Response: [ResponseOutputItem containing MCP tool results ...]

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

В следующих примерах показано, как создать агент с помощью средства MCP и вызвать его с помощью API ответов. Если ответ содержит выходной элемент с type, установленным на mcp_approval_request, отправьте дополнительный запрос, содержащий элемент mcp_approval_response.

Предпосылки

Задайте следующие переменные среды:

• FOUNDRY_PROJECT_ENDPOINT: URL-адрес конечной точки проекта.
• FOUNDRY_MODEL_DEPLOYMENT_NAME: название развертывания модели.
• AGENT_TOKEN: маркер носителя для Foundry.
• MCP_PROJECT_CONNECTION_NAME (необязательно): имя подключения проекта MCP.

Получение токена доступа:

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

Если сервер MCP не требует проверки подлинности, исключите project_connection_id из тела запроса.

Замечание

Для REST API необходимо сначала получить идентификатор подключения из имени подключения с помощью API подключений, а затем передать идентификатор в конфигурацию средства MCP.

Подсказка

Дополнительные сведения о схеме и утверждениях средств MCP см. в статье OpenAI.MCPTool и типы элементов утверждения MCP в справочнике REST.

1. Создание агента MCP

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "<AGENT_NAME>-mcp",
    "description": "MCP agent",
    "definition": {
      "kind": "prompt",
      "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
      "instructions": "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
      "tools": [
        {
          "type": "mcp",
          "server_label": "api-specs",
          "server_url": "https://gitmcp.io/Azure/azure-rest-api-specs",
          "require_approval": "never"
        }
      ]
    }
  }'

Чтобы использовать прошедший проверку подлинности сервер MCP с подключением к проекту, добавьте "project_connection_id": "'$MCP_PROJECT_CONNECTION_NAME'" в определение инструмента и измените server_url на конечную точку сервера, осуществляющего проверку подлинности (например, https://api.githubcopilot.com/mcp).

2. Создание ответа

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent": {"type": "agent_reference", "name": "<AGENT_NAME>-mcp"},
    "input": "Please summarize the Azure REST API specifications Readme"
  }'

Если ответ содержит выходной элемент с параметром type, установленным на mcp_approval_request, скопируйте элемент запроса на утверждение id как APPROVAL_REQUEST_ID. Кроме того, скопируйте ответ id верхнего уровня как PREVIOUS_RESPONSE_ID.

3. Отправка ответа на утверждение

Если для средства MCP требуется утверждение, отправьте следующий запрос:

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "previous_response_id": "'$PREVIOUS_RESPONSE_ID'",
    "input": [
      {
        "type": "mcp_approval_response",
        "approval_request_id": "'$APPROVAL_REQUEST_ID'",
        "approve": true
      }
    ]
  }'

4. Очистка ресурсов

Удалите агент:

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/<AGENT_NAME>-mcp?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Принцип работы

Необходимо перенести удаленный сервер MCP (существующую конечную точку сервера MCP) в службу агента Foundry. Вы можете добавить несколько удаленных серверов MCP, добавив их в качестве инструментов. Для каждого средства необходимо указать уникальное server_label значение в одном агенте и server_url значение, указывающее на удаленный сервер MCP. Внимательно проверьте, какие серверы MCP добавляются в службу агента Foundry.

Помимо подключения произвольных удаленных серверов MCP по URL-адресу, некоторые серверы MCP можно добавлять непосредственно из каталога Foundry Add Tools. Например, сервер Azure DevOps MCP (предварительная версия) доступен в виде элемента каталога. Записи каталога упрощают настройку подключения и соответствуют тем же механизмам утверждения и аудита, описанным в этой статье.

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

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

Настройка подключения MCP

Ниже описано, как подключиться к удаленному серверу MCP из службы агента Foundry:

1. Найдите удаленный сервер MCP, к которому требуется подключиться, например сервер GitHub MCP. Создайте или обновите агента Foundry с помощью средства mcp, используя следующие сведения:
   1. server_url: URL-адрес сервера MCP, например https://api.githubcopilot.com/mcp/.
   2. server_label: уникальный идентификатор этого сервера MCP для агента, например github.
   3. allowed_tools: необязательный список инструментов, к которым этот агент может обращаться и использовать. Если это значение не указано, значение по умолчанию включает все средства на сервере MCP.
   4. require_approval: при необходимости определите, требуется ли утверждение. Значение по умолчанию — always. Поддерживаемые значения:
      • always: разработчику необходимо предоставить утверждение для каждого вызова. Если вы не предоставляете значение, это значение по умолчанию.
      • never: утверждение не требуется.
      • {"never":[<tool_name_1>, <tool_name_2>]}: вы предоставляете список инструментов, которые не требуют утверждения.
      • {"always":[<tool_name_1>, <tool_name_2>]}: вы предоставляете список инструментов, требующих утверждения.
2. project_connection_id: идентификатор подключения проекта, который хранит проверку подлинности и другие сведения о подключении для сервера MCP.
3. Если модель пытается вызвать средство на сервере MCP с обязательным утверждением, вы получите тип выходного элемента ответа как mcp_approval_request. В результате обработки вы можете получить дополнительные сведения о том, какой инструмент вызывается на сервере MCP и какие аргументы будут переданы. Просмотрите инструмент и аргументы, чтобы вы могли принять обоснованное решение для утверждения.
4. Отправьте утверждение агенту с помощью previous_response_id и установите approve на true.

Подключитесь к серверу MCP Azure DevOps

Сервер Azure DevOps MCP (предпросмотр) доступен как элемент каталога в Foundry. Чтобы добавить его, выполните приведенные далее действия.

1. На портале Foundry перейдите к вашему проекту.
2. Выберите "Добавить каталог инструментов>" и найдите "Azure DevOps".
3. Выберите azure DevOps MCP Server (предварительная версия) и нажмите кнопку "Создать".
4. Введите имя организации Azure DevOps и нажмите кнопку Connect.
5. Выберите, какие средства Azure DevOps будут предоставлять агенту. Вы можете выбрать подмножество инструментов, чтобы точно управлять тем, к чему имеет доступ агент.

Эта настройка на основе каталога создает средство MCP для использования агентами без внесения изменений в код. Вы можете проверить поведение подключения и инструментов в интерфейсе тестирования чата Foundry перед интеграцией средства в рабочий код.

Известные ограничения

• Время ожидания вызова инструмента MCP, не использующего потоковую передачу: вызовы инструментов MCP, не использующих потоковую передачу, имеют время ожидания 100 секунд. Если сервер MCP отвечает более чем через 100 секунд, вызов завершается ошибкой. Чтобы избежать времени ожидания, убедитесь, что сервер MCP отвечает в пределах этого ограничения. Если для вашего варианта использования требуется более длительное время обработки, рассмотрите возможность оптимизации логики на стороне сервера или прерывания операции на небольших шагах.
• Для частного MCP требуется стандартная настройка агента: подключение к частному серверу MCP доступно только в стандартной настройке агента с частной сетью (виртуальная сеть BYO). Базовая настройка агента не поддерживает частные конечные точки MCP.
• Частное размещение MCP: Контейнерные приложения Azure в выделенной MCP подсети — это проверенная конфигурация для размещения частных серверов MCP. Функциональные приложения или службы приложений могут работать в качестве частного хоста сервера MCP, но еще не проверены.

Распространенные вопросы и ошибки

Ниже приведены распространенные проблемы, которые могут возникнуть при использовании средств MCP со службой агента Foundry:

• "Недопустимая схема инструментов":

  Недопустимая схема инструментария обычно возникает, если в вашем определении сервера MCP присутствует anyOf или allOf, или если параметр может принимать несколько типов значений. Обновите определение сервера MCP и повторите попытку.

• "Несанкционированный" или "Запрещено" на сервере MCP:

  Убедитесь, что сервер MCP поддерживает метод проверки подлинности и проверьте учетные данные, хранящиеся в подключении проекта. Для GitHub используйте токены с минимальными привилегиями и регулярно обновляйте их.

• Модель никогда не вызывает средство MCP:

  Убедитесь, что инструкции агента поощряют использование инструментов, а также проверьте значения server_label, server_url и allowed_tools. Если задано allowed_tools, убедитесь, что имя средства соответствует тому, что предоставляет сервер MCP.

• Агент после утверждения никогда не продолжает работу.

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

Размещение локального сервера MCP

Среда выполнения службы агента принимает только удаленную конечную точку сервера MCP. Если вы хотите добавить средства с локального сервера MCP, необходимо самостоятельно разместить его на Azure Container Apps или Azure Functions для получения удаленной конечной точки сервера MCP.

Удаленная конечная точка может быть общедоступной конечной точкой или частной конечной точкой в виртуальной сети. Для частных серверов MCP разверните контейнерное приложение с внутренним доступом (--internal-only true) на выделенной подсети MCP. Дополнительные сведения о настройке см. в общедоступных и частных конечных точках сервера MCP .

При размещении локальных серверов MCP в облаке следует учитывать следующие факторы:

Настройка локального сервера MCP	Размещение в Azure Container Apps	Размещение в Azure Functions
Транспорт	Необходимые конечные точки HTTP POST/GET.	Требуется поток HTTP с возможностью потоковой передачи.
Изменения кода	Требуется пересборка контейнера.	Файлы конфигурации, специфичные для Azure Functions, которые требуются в корневом каталоге.
Аутентификация	Требуется реализация пользовательской проверки подлинности.	Только на базе ключей. OAuth требует управления API.
Язык	Любой язык, работающий в контейнерах Linux (Python, Node.js, .NET, TypeScript, Go).	Python, Node.js, Java, только .NET.
Требования к контейнерам	Только Linux (linux/amd64). Нет привилегированных контейнеров.	Контейнерные серверы не поддерживаются.
Зависимости	Все зависимости должны находиться в образе контейнера.	Зависимости на уровне ОС (такие как Playwright) не поддерживаются.
State	Состояние не отслеживается.	Состояние не отслеживается.
UVX/NPX	Supported.	Не поддерживается. npx Команды запуска не поддерживаются.

Связанный контент

• Начало работы с агентами с помощью кода
• Проверка подлинности сервера MCP
• Создание и регистрация сервера протокола контекста модели (MCP)
• Настройка частной сети для службы агента Foundry
• Настройка приватного канала для Foundry
• Документация по REST для инструмента MCP
• Рекомендации по безопасности для MCP
• Понимание и устранение рисков безопасности в реализации MCP