Připojení agentů k serverům protokolu Model Context

Připojte agenty Foundry k serverům MCP (Model Context Protocol) pomocí nástroje MCP . Toto připojení rozšiřuje možnosti agenta s externími nástroji a zdroji dat. Připojením ke vzdáleným koncovým bodům serveru MCP má model Foundry vašeho agenta přístup k nástrojům hostovaným vývojáři a organizacemi, které můžou používat klienti kompatibilní s MCP, jako je služba Foundry Agent Service.

MCP je otevřený standard, který definuje, jak aplikace poskytují nástroje a kontextová data velkým jazykovým modelům (LLM). Umožňuje konzistentní a škálovatelnou integraci externích nástrojů do pracovních postupů modelu.

V tomto článku se naučíte:

  • Přidejte vzdálený server MCP jako nástroj.
  • Ověřte se na serveru MCP pomocí připojení k projektu.
  • Zkontrolujte a schvalte volání nástroje MCP.
  • Řešení běžných problémů s integrací MCP

Koncepční podrobnosti o tom, jak funguje integrace MCP, najdete v tématu Jak to funguje.

Podpora využití

Následující tabulka ukazuje podporu sady SDK a nastavení pro připojení MCP.

podpora Microsoft Foundry Python SDK C# SDK JavaScript SDK Java SDK REST API Základní nastavení agenta Nastavení standardního agenta
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Požadavky

Než začnete, ujistěte se, že máte:

  • Předplatné Azure s aktivním projektem Microsoft Foundry.
  • Azure řízení přístupu na základě role (RBAC): Role Přispěvatel nebo Vlastník v projektu Foundry.
  • Nejnovější balíček sady SDK pro váš jazyk. Sada .NET SDK je aktuálně ve verzi Preview. Podrobnosti o instalaci najdete v rychlém startu.
  • Azure přihlašovací údaje nakonfigurované pro ověřování (například DefaultAzureCredential).
  • Přístup ke vzdálenému koncovému bodu serveru MCP (například k serveru MCP GitHub na https://api.githubcopilot.com/mcp).

Koncové body MCP serveru, veřejné a privátní

Služba agenta podporuje veřejné i privátní koncové body serveru MCP:

  • Veřejné koncové body: Připojte se k jakémukoli veřejně přístupnému vzdálenému serveru MCP. Tato možnost funguje s nastavením agenta Basic i Standard.
  • Privátní koncové body: Připojte se k serverům MCP, které nejsou vystavené veřejnému internetu. Privátní MCP vyžaduje nastavení standardního agenta s privátními sítěmi a vyhrazenou podsíť MCP ve vaší virtuální síti.

U privátních serverů MCP nasaďte server MCP na Azure Container Apps s interním příchozím přenosem dat ve vyhrazené podsíti MCP delegované na Microsoft.App/environments. Začněte tím, že použijete šablonu 19-private-network-agents-tools-setup , která zřídí požadovanou síťovou infrastrukturu včetně podsítě MCP.

Podrobnosti o podpoře nástrojů v prostředích izolovaných v síti najdete v tématu Nástroje agenta s izolací sítě.

Použití nástrojů Foundry jako koncových bodů MCP

Sady nástrojů Foundry umožňují sbalit několik nástrojů , jako je vyhledávání na webu, interpret kódu, vyhledávání souborů, Azure AI Vyhledávač, servery MCP, nástroje OpenAPI a připojení agenta-agenta k agentům – do jednoho koncového bodu kompatibilního s MCP. Místo konfigurace jednotlivých nástrojů pro každého agenta vytvořte sadu nástrojů v Foundry a nasměrujte agenta na koncový bod sady nástrojů pomocí standardní mcp konfigurace nástroje (server_url a server_label).

Vzhledem k tomu, že koncový bod sady nástrojů je kompatibilní s MCP, může jakýkoli modul runtime, který může využívat server MCP, také využívat sadu nástrojů. Tato kompatibilita zahrnuje službu Foundry Agent Service, Microsoft Agent Framework, LangGraph, GitHub Copilot SDK a další klienty s podporou MCP. V sadě nástrojů můžete přidávat, odebírat nebo překonfigurovat nástroje beze změny kódu agenta.

Postup nastavení najdete v tématu Vytvoření a použití sady nástrojů Foundry.

Ověřování

Mnoho serverů MCP vyžaduje ověření.

Ve službě Foundry Agent service používejte připojení projektu k ukládání podrobností o ověřování, jako jsou klíče rozhraní API nebo nosné tokeny, místo pevně kódovaných přihlašovacích údajů ve vaší aplikaci.

Další informace o podporovaných možnostech ověřování, včetně ověřování založeného na klíčích, Microsoft Entra identit a předávání identity OAuth, najdete v tématu ověřování serveru MCP.

Poznámka

Nastavte project_connection_id na ID připojení projektu.

Tip

Když přidáte Azure DevOps MCP Server (Preview) prostřednictvím katalogu Add Tools, ověříte se během kroku připojení organizace k Azure DevOps a uložíte ověřování jako připojení k projektu. Při připojování organizace používejte přístup s nejnižšími oprávněními a zkontrolujte rozsahy.

Když použijete koncový bod MCP sady nástrojů Foundry, sada nástrojů centrálně spravuje ověřování. Sada nástrojů zpracovává vložení přihlašovacích údajů, aktualizaci tokenu a prosazení zásad během provozu pro všechny nástroje v sadě. Agenti se ověřují v samotném koncovém bodu sady nástrojů pomocí přihlašovacích údajů Microsoft Entra, jako jsou DefaultAzureCredential a přihlašovací údaje jednotlivých nástrojů nemusí předávat každý agent. Pro konfiguraci ověřování sady nástrojů se podívejte na Požadavky na Toolbox.

Důležité informace o používání služeb a serverů od jiných než Microsoftu

Jste vázáni podmínkami mezi vámi a poskytovatelem služeb, když používáte služby jiné než Microsoft. Když se připojíte ke službě, která není Microsoft, předáte některá data, jako je například obsah výzvy, službě, která není Microsoft, nebo vaše aplikace může přijímat data ze služby, která není Microsoft. Zodpovídáte za používání jiných než služby Microsoft a dat spolu s poplatky souvisejícími s tímto použitím.

Třetí strany, nikoli Microsoft, vytvářejí vzdálené servery MCP, které se rozhodnete použít s nástrojem MCP popsaným v tomto článku. Microsoft tyto servery neotestuje ani neověřuje. Microsoft nemá žádnou odpovědnost za vás nebo jiné uživatele ve vztahu k vašemu používání vzdálených serverů MCP.

Pečlivě zkontrolujte a sledujte, jaké servery MCP přidáte do služby agenta Foundry. Místo proxy serverů se spoléhají na servery hostované důvěryhodnými poskytovateli služeb.

Nástroj MCP umožňuje předávat vlastní hlavičky, jako jsou ověřovací klíče nebo schémata, které může vzdálený server MCP potřebovat. Zkontrolujte všechna data, která sdílíte se vzdálenými servery MCP, a protokolujte data pro účely auditování. Mějte na paměti praktiky nesouvisející s Microsoftem ohledně uchovávání a umístění dat.

Poznámka

Sady nástrojů Foundry se liší od serverů MCP třetích stran. Sady nástrojů jsou prostředky řízené organizací, které vytváříte a spravujete v rámci projektu Microsoft Foundry. Při vytváření obsahu panelu nástrojů ale stále zodpovídáte za výběr nástrojů, zpracování dat a dodržování předpisů.

Osvědčené postupy

Obecné pokyny k používání nástrojů najdete v tématu Nejlepší postupy pro používání nástrojů ve službě Microsoft Foundry Agent Service.

Při používání serverů MCP postupujte podle těchto postupů:

  • Použití seznamu povolených nástrojů pomocí allowed_tools.
  • Vyžadovat schválení pro vysoce rizikové operace, zejména nástroje, které zapisuje data nebo mění prostředky.
  • Před schválením zkontrolujte název a argumenty požadovaného nástroje.
  • Protokolování schválení a volání nástrojů k auditování a řešení problémů.

Tip

Když přidáte Azure DevOps MCP Server prostřednictvím katalogu Přidat nástroje, konfigurace výběru nástrojů se mapuje na chování allowed_tools popsané v tomto článku. Výběr podmnožiny nástrojů v katalogovém uživatelském rozhraní odpovídá zadání allowed_tools seznamu v kódu.

Vytvoření agenta v Python pomocí nástroje MCP

Pomocí následující ukázky kódu vytvořte agenta a volejte funkci. Sada .NET SDK je aktuálně ve verzi Preview. Podrobnosti najdete v průvodci rychlým startem.

Následující příklad ukazuje, jak používat server GitHub MCP jako nástroj pro agenta. Vyberte Prompt Agents, chcete-li použít SDK Azure AI Projects k vytvoření serverového agenta promptů, nebo Hosted Agents, chcete-li použít Agent Framework FoundryChatClient k vytvoření dočasného agenta v rámci procesu.

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

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění ukázky:

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

Vytvoření agenta pomocí nástroje MCP

Následující příklad ukazuje, jak používat vzdálený server MCP jako nástroj pro agenta. Vyberte Prompt Agents, chcete-li pomocí sady Azure AI Projects SDK vytvořit serverového agenta pro prompty, nebo Hosted Agents, chcete-li pomocí Microsoft Agent Framework vytvořit dočasného agenta v procesu.

Příklad používá synchronní metody k vytvoření agenta. Asynchronní metody najdete v kódu sample v Azure SDK pro .NET úložiště na 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);

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění ukázky:

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.

Vytvoření agenta pomocí nástroje MCP s ověřováním připojení k projektu

V tomto příkladu se dozvíte, jak se ověřit na serveru GitHub MCP a jak ho použít jako nástroj pro agenta. Příklad používá synchronní metody k vytvoření agenta. Asynchronní metody najdete v kódu sample v Azure SDK pro .NET úložiště na GitHub.

Nastavení připojení projektu

Před spuštěním ukázky:

  1. Přihlaste se ke svému GitHub profilu.
  2. Vyberte profilový obrázek v pravém horním rohu.
  3. Vyberte Nastavení.
  4. Na levém panelu vyberte Vývojářská nastavení a Osobní přístupové tokeny > Tokeny (klasické).
  5. Nahoře vyberte Vygenerovat nový token, zadejte heslo a vytvořte token, který může číst veřejná úložiště.
    • Důležité: Uložte token nebo nechte stránku otevřenou, protože jakmile je stránka zavřená, token se už nedá znovu zobrazit.
  6. Na portálu Azure otevřete Microsoft Foundry.
  7. Na levém panelu vyberte Centrum pro správu a pak vyberte Připojené prostředky.
  8. Vytvořte nové připojení typu Vlastní klíče .
  9. Pojmenujte ho a přidejte pár hodnot klíče.
  10. Nastavte název klíče na Authorization a hodnota by měla mít formát Bearer your_github_token.

Ukázka kódu pro vytvoření agenta

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

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění ukázky:

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

Vytvoření agenta v TypeScriptu pomocí nástroje MCP

Následující ukázka TypeScriptu ukazuje, jak vytvořit agenta s možnostmi nástroje MCP, odesílat žádosti, které aktivují pracovní postupy schválení MCP, zpracovávat žádosti o schválení a vyčistit prostředky. Verzi JavaScriptu najdete v kódu sample na Azure SDK pro úložiště JavaScript v 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);
});

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění ukázky:

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!

Vytvoření agenta pomocí nástroje MCP s ověřováním připojení k projektu

Následující ukázka TypeScriptu ukazuje, jak vytvořit agenta s funkcemi nástroje MCP pomocí ověřování připojení projektu, odesílat žádosti, které aktivují pracovní postupy schválení MCP, zpracovávat žádosti o schválení a vyčistit prostředky. Verzi JavaScriptu najdete v kódu sample na Azure SDK pro úložiště JavaScript v 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);
});

Očekávaný výstup

Následující příklad ukazuje očekávaný výstup při spuštění ukázky:

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!

Použití nástrojů MCP v agentu Java

Přidejte závislost do svého pom.xml:

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

Vytvoření agenta pomocí nástroje 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());
    }
}

Očekávaný výstup

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

Použití nástroje MCP s rozhraním REST API

Následující příklady ukazují, jak vytvořit agenta pomocí nástroje MCP a volat ho pomocí rozhraní API odpovědí. Pokud odpověď obsahuje výstupní položku s type nastavenou na mcp_approval_request, odešlete následný požadavek, který obsahuje mcp_approval_response položku.

Požadavky

Nastavte tyto proměnné prostředí:

  • FOUNDRY_PROJECT_ENDPOINT: Adresa URL koncového bodu projektu.
  • FOUNDRY_MODEL_DEPLOYMENT_NAME: Název nasazení modelu.
  • AGENT_TOKEN: Nosný token pro Foundry.
  • MCP_PROJECT_CONNECTION_NAME (volitelné): Název připojení projektu MCP.

Získání přístupového tokenu:

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

Pokud váš server MCP nevyžaduje ověření, v textu požadavku vynechejte project_connection_id .

Poznámka

V případě rozhraní REST API musíte nejprve načíst ID připojení z názvu připojení pomocí rozhraní CONNECTIONS API a pak id předat konfiguraci nástroje MCP.

Tip

Podrobnosti o schématu nástrojů MCP a položkách schválení najdete v tématu OpenAI.MCPTool a typy položek schválení MCP v odkazu REST.

1. Vytvoření agenta 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"
        }
      ]
    }
  }'

Pokud chcete použít ověřený server MCP s připojením k projektu, přidejte "project_connection_id": "'$MCP_PROJECT_CONNECTION_NAME'" do definice nástroje a změňte server_url koncový bod ověřeného serveru (například https://api.githubcopilot.com/mcp).

2. Vytvoření odpovědi

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"
  }'

Pokud odpověď obsahuje výstupní položku s nastavenou type na mcp_approval_request, zkopírujte položku id žádosti o schválení jako APPROVAL_REQUEST_ID. Zkopírujte také odpověď id nejvyšší úrovně jako PREVIOUS_RESPONSE_ID.

3. Odeslání odpovědi na schválení

Pokud nástroj MCP vyžaduje schválení, odešlete následnou žádost.

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. Vyčištění prostředků

Odstraňte agenta:

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

Jak to funguje

Ke službě Foundry Agent musíte připojit vzdálený server MCP (existující koncový bod serveru MCP). Několik vzdálených serverů MCP můžete přinést tak, že je přidáte jako nástroje. Pro každý nástroj musíte zadat jedinečnou server_label hodnotu ve stejném agentu a server_url hodnotu, která odkazuje na vzdálený server MCP. Nezapomeňte pečlivě zkontrolovat, které servery MCP přidáte do služby agenta Foundry.

Kromě připojení libovolných vzdálených serverů MCP pomocí adresy URL je možné některé servery MCP přidat přímo z katalogu Foundry Add Tools . Například Azure DevOps MCP Server (Preview) je k dispozici jako položka katalogu. Položky katalogu zjednodušují nastavení připojení a odpovídají stejným mechanismům schvalování a auditování, které jsou popsané v tomto článku.

Další informace o používání MCP najdete tady:

Nastavení připojení MCP

Následující kroky popisují, jak se připojit ke vzdálenému serveru MCP ze služby Foundry Agent Service:

  1. Vyhledejte vzdálený server MCP, ke kterému se chcete připojit, například k serveru GitHub MCP. Pomocí nástroje mcp vytvořte nebo aktualizujte agenta Foundry pomocí následujících informací:
    1. server_url: Adresa URL serveru MCP, například https://api.githubcopilot.com/mcp/.
    2. server_label: Jedinečný identifikátor tohoto serveru MCP pro agenta, například github.
    3. allowed_tools: Volitelný seznam nástrojů, ke kterým může tento agent přistupovat a používat. Pokud tuto hodnotu nezadáte, bude výchozí hodnota zahrnovat všechny nástroje na serveru MCP.
    4. require_approval: Volitelně určete, jestli je požadováno schválení. Výchozí hodnota je always. Podporované hodnoty jsou:
      • always: Vývojář musí ke každému hovoru poskytnout schválení. Pokud nezadáte hodnotu, jedná se o výchozí hodnotu.
      • never: Nevyžaduje se žádné schválení.
      • {"never":[<tool_name_1>, <tool_name_2>]}: Zadáte seznam nástrojů, které nevyžadují schválení.
      • {"always":[<tool_name_1>, <tool_name_2>]}: Zadáte seznam nástrojů, které vyžadují schválení.
  2. project_connection_id: ID připojení projektu, které ukládá ověřování a další podrobnosti připojení pro server MCP.
  3. Pokud se model pokusí vyvolat nástroj na serveru MCP s požadovaným schválením, získáte typ výstupní položky odpovědi jako mcp_approval_request. Ve výstupní položce odpovědi můžete získat další podrobnosti o tom, který nástroj na serveru MCP se volá, a argumenty, které se mají předat. Zkontrolujte nástroj a argumenty, abyste mohli učinit informované rozhodnutí o schválení.
  4. Zašlete schválení agentovi pomocí previous_response_id a nastavte approve na true.

Připojení k serveru Azure DevOps MCP

Azure DevOps MCP Server (Preview) je k dispozici jako položka katalogu v Foundry. Přidání:

  1. Na portálu Foundry přejděte na svůj projekt.
  2. Vyberte Přidat nástroje>Catalog a vyhledejte "Azure DevOps".
  3. Vyberte Azure DevOps MCP Server (Preview) a vyberte Create.
  4. Zadejte název organizace Azure DevOps a vyberte Connect.
  5. Vyberte, které Azure DevOps nástroje, které se mají zpřístupnit vašemu agentu. Můžete vybrat podmnožinu nástrojů pro řízení přesně toho, k čemu má agent přístup.

Toto nastavení založené na katalogu vytvoří nástroj MCP pro použití agenty bez nutnosti změn kódu. Před integrací nástroje do produkčního kódu můžete ověřit připojení a chování nástrojů v prostředí pro testování chatu Foundry.

Tip

Správa verzí sady nástrojů: Sady nástrojů Foundry podporují správu verzí, takže můžete iterovat na nové verzi, aniž by to mělo vliv na produkční agenty. Pro produkční agenty použijte koncový bod příjemce ({project_endpoint}/toolboxes/{name}/mcp?api-version=v1) – vždy obsluhuje upřednostněnou výchozí verzi. Před povýšením použijte koncový bod specifický pro verzi ({project_endpoint}/toolboxes/{name}/versions/{version}/mcp?api-version=v1) k otestování. Udržujte server_label jedinečné pro každého agenta, i při přepínání verzí sady nástrojů. Podrobnosti najdete v tématu Zvýšení úrovně verze na výchozí.

Dlouhotrvající operace (Preview)

Některé servery MCP poskytují nástroje, kterým trvá déle, než vrátí výsledek, než je standardní synchronní časový limit. Pokud chcete tyto operace podporovat, spusťte agenta v režimu na pozadí. Režim na pozadí spouští odpověď asynchronně, takže volání nástroje MCP může pokračovat, aniž by drželo otevřené připojení, a dotazujete se na stav odpovědi, dokud se neskončí. Tento přístup umožňuje, aby volání nástrojů MCP překročila 100sekundový časový limit mimo streamování popsaný v známých omezeních.

Poznámka

Dlouhotrvající operace MCP jsou ve verzi Preview. Funkce ve verzi Preview jsou poskytovány bez smlouvy o úrovni služeb a nedoporučuje se pro produkční úlohy. Chování a podporované modely se můžou změnit.

Požadavky na server MCP

Modul runtime agenta spoléhá na server MCP, který operaci spouští asynchronně a hlásí průběh. Server musí:

  • Implementujte funkci úloh protokolu kontextu modelu , aby volání nástroje místo blokování vrátilo odkaz na úkol, dokud se práce nedokončí.
  • Při spuštění dlouho běžící operace vraťte v metadatech výsledku nástroje související identifikátor úkolu (pole io.modelcontextprotocol/related-task s hodnotou taskId).
  • Umožnit běhovému prostředí zjišťovat stav úlohy a po jejím dokončení načíst konečný výsledek.
  • Být dostupný jako vzdálený koncový bod MCP, stejný jako jakýkoli jiný nástroj MCP. Aby bylo možné poskytovat vzdálený koncový bod, musí být místní servery MCP hostované v místním prostředí. Viz Hostování místního serveru MCP.

Když běhové prostředí agenta vyvolá nástroj, který spustí dlouhotrvající operaci, server vrátí referenci na úlohu a běhové prostředí odpověď uchovává na pozadí. Modul runtime zahájí odpověď, okamžitě vrátí odpověď id a status o hodnotě queued a výsledek získá, jakmile se úloha dokončí. Opakovaně zjišťujete stav odpovědi id, dokud se status nestane completed, a pak přečtete finální výstup.

Režim na pozadí pro dlouhotrvající operace MCP funguje s jakýmkoli modelem, který podporuje režim pozadí, například gpt-5.4 nebo gpt-5.5.

Pokud váš agent používá model, který nepodporuje režim na pozadí, spustí se synchronně volání nástroje MCP a podléhá vypršení časového limitu 100 sekund.

Povolení režimu na pozadí na portálu Microsoft Foundry

Režim na pozadí pro agenta můžete v playgroundu portálu Microsoft Foundry portal zapnout, aniž byste museli psát kód:

  1. Otevřete agenta a vyberte kartu Playground.

  2. V seznamu Model vyberte model, který podporuje režim pozadí, například gpt-5.4 nebo gpt-5.5.

  3. Vyberte ikonu parametrů vedle modelu a zapněte režim pozadí.

    Snímek obrazovky s panelem parametrů modelu na portálu Foundry s vybraným podporovaným modelem a zapnutým přepínačem režimu pozadí

  4. V části Nástroje přidejte nástroj, jehož server MCP podporuje úlohy MCP, například Fabric datového agenta přidaného prostřednictvím nástroje Fabric IQ. Postup najdete v tématu Připojení agentů k Microsoft Fabric pomocí Fabric IQ.

  5. Odeslat zprávu. Agent spustí běh na pozadí a zobrazuje jeho průběh, zatímco se dokončuje dlouho trvající volání nástroje. Po dokončení běhu se odpověď objeví v chatu.

    Snímek obrazovky chatu na portálu Foundry zobrazující probíhající běh na pozadí s indikátorem průběhu poté, co uživatel odešle zprávu.

Spuštění režimu pozadí s kódem

Následující příklady spouštějí agenta, který je již nakonfigurován s nástrojem MCP, nastaví background na true a opakovaně se dotazují, dokud není odpověď dokončena. Zástupné hodnoty nahraďte vlastními hodnotami.

from time import sleep
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_mcp_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response. It returns immediately with status "queued".
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Run the long-running task and summarize the result.",
    background=True,
)

# Poll the response ID until the MCP tool call completes.
while response.status in ("queued", "in_progress"):
    sleep(5)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

using Azure.Identity;
using Azure.AI.Projects;

var projectEndpoint = "your_project_endpoint";
var agentName = "your_mcp_agent_name";

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

ProjectResponsesClient responsesClient
    = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentName);

// Start a background response. It returns immediately with status "queued".
ResponseResult response = await responsesClient.CreateResponseAsync(
    new CreateResponseOptions
    {
        InputItems = { ResponseItem.CreateUserMessageItem(
            "Run the long-running task and summarize the result.") },
        Background = true,
    });

// Poll the response ID until the MCP tool call completes.
while (response.Status is "queued" or "in_progress")
{
    await Task.Delay(5000);
    response = await responsesClient.RetrieveResponseAsync(response.Id);
}
Console.WriteLine(response.GetOutputText());

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

const PROJECT_ENDPOINT = "your_project_endpoint";
const AGENT_NAME = "your_mcp_agent_name";

const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();

// Start a background response. It returns immediately with status "queued".
let response = await openai.responses.create({
  input: "Run the long-running task and summarize the result.",
  background: true,
  agent_reference: {
    name: AGENT_NAME,
    type: "agent_reference",
  },
});

// Poll the response ID until the MCP tool call completes.
while (response.status === "queued" || response.status === "in_progress") {
  await new Promise((r) => setTimeout(r, 5000));
  response = await openai.responses.retrieve(response.id);
}
console.log(response.output_text);

import com.azure.ai.agents.*;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

String projectEndpoint = "your_project_endpoint";
String agentName = "your_mcp_agent_name";

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

AgentReference agentRef = new AgentReference(agentName);

// Start a background response. It returns immediately with status "queued".
Response response = responsesClient.createAzureResponse(
    new AzureCreateResponseOptions()
        .setAgentReference(agentRef)
        .setBackground(true),
    ResponseCreateParams.builder()
        .input("Run the long-running task and summarize the result."));

// Poll the response ID until the MCP tool call completes.
while (response.status().equals("queued") || response.status().equals("in_progress")) {
    Thread.sleep(5000);
    response = responsesClient.getAzureResponse(response.id());
}
System.out.println(response.output());

Vytvořte odpověď na pozadí. Požadavek okamžitě vrátí odpověď id a status o hodnotě queued:

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": "Run the long-running task and summarize the result.",
    "background": true
  }'

Zkopírujte odpověď id z výsledku a pak ji dotazujte, dokud status nebude completed:

curl "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses/$RESPONSE_ID" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Pokud je statuscompleted, pole output obsahuje výsledek volání nástroje MCP a závěrečnou zprávu asistenta.

Známá omezení

  • Vypršení časového limitu volání nástroje MCP bez streamování: Volání nástroje MCP bez streamování mají časový limit 100 sekund. Pokud odezva serveru MCP trvá déle než 100 sekund, volání selže. Abyste se vyhnuli vypršení časových limitů, ujistěte se, že váš server MCP reaguje v rámci tohoto limitu. Pokud váš případ použití vyžaduje delší dobu zpracování, spusťte agenta v režimu na pozadí s podporovaným modelem, optimalizujte logiku na straně serveru nebo rozdělte operaci do menších kroků.
  • Privátní MCP vyžaduje instalaci standardního agenta: Připojení k privátnímu serveru MCP je k dispozici pouze s nastavením standardního agenta s privátní sítí (BYO VNet). Základní nastavení agenta nepodporuje privátní koncové body MCP.
  • Soukromý hosting MCP: Azure Container Apps na vyhrazené podsíti MCP je testovaná konfigurace pro soukromé servery MCP. Aplikace funkcí nebo App Services mohou fungovat jako privátní hostitel serveru MCP, ale nebyly interně ověřeny.

Běžné dotazy a chyby

K následujícím běžným problémům může dojít při použití nástrojů MCP se službou Foundry Agent Service:

  • Neplatné schéma nástrojů:

    K této chybě obvykle dochází v případě, že definice serveru MCP obsahuje anyOf nebo allOfnebo pokud parametr přijímá více typů hodnot. Aktualizujte definici serveru MCP a zkuste to znovu.

  • "Neautorizováno" nebo "Zakázáno" ze serveru MCP:

    Ověřte, že server MCP podporuje vaši metodu ověřování, a ověřte přihlašovací údaje uložené v připojení k projektu. Pro GitHub používejte tokeny s nejnižšími oprávněními a pravidelně je obměňujte.

  • Model nikdy nevolá váš nástroj MCP:

    Potvrďte pokyny pro agenta, které podporují používání nástrojů, a ověřte hodnoty server_label, server_url a allowed_tools. Pokud nastavíte allowed_tools, ujistěte se, že název nástroje odpovídá tomu, co server MCP zveřejňuje.

  • Agent po schválení nikdy nepokračuje:

    Potvrďte odeslání následné žádosti s nastaveným previous_response_id na původní ID odpovědi a že použijete ID položky žádosti o schválení jako approval_request_id.

Hostování místního serveru MCP

Modul runtime služby agenta přijímá pouze vzdálený koncový bod serveru MCP. Pokud chcete přidat nástroje z místního serveru MCP, musíte ho sami hostovat na Azure Container Apps nebo Azure Functions, abyste získali vzdálený koncový bod serveru MCP.

Vzdálený koncový bod může být veřejný nebo privátní koncový bod ve vaší virtuální síti. U privátních serverů MCP nasaďte svou containerovou aplikaci pouze s interním přístupem (--internal-only true) ve vyhrazené podsíti MCP. Podrobnosti o nastavení najdete v části Veřejné a privátní koncové body serveru MCP .

Při hostování místních serverů MCP v cloudu zvažte následující faktory:

Nastavení místního serveru MCP Hostování v Azure Container Apps Hostování v Azure Functions
Dopravy Koncové body HTTP POST/GET jsou vyžadovány. Je vyžadována podpora streamování HTTP.
Změny kódu Vyžaduje se opětovné sestavení kontejneru. Azure Functions specifické konfigurační soubory vyžadované v kořenovém adresáři.
Ověřování Vyžaduje se vlastní implementace ověřování. Pouze na základě klíče. OAuth potřebuje API Management.
Jazyk Libovolný jazyk, který běží v kontejnerech Linuxu (Python, Node.js, .NET, TypeScript, Go). Python, Node.js, Java, pouze .NET.
Požadavky na kontejnery Pouze Linux (Linux/amd64). Žádné privilegované kontejnery. Kontejnerizované servery se nepodporují.
Závislosti Všechny závislosti musí být v obrazu kontejneru. Závislosti na úrovni operačního systému (například Playwright) se nepodporují.
Stav Jen bezstavová. Jen bezstavová.
UVX/NPX Podporováno Nepodporuje se. npx příkazy start nejsou podporovány.

Související obsah

  • Last updated on