Łączenie agentów z serwerami protokołu kontekstu modelu

Połącz agentów foundry z serwerami protokołu MCP (Model Context Protocol) przy użyciu narzędzia MCP. Rozszerza to możliwości agenta za pomocą narzędzi zewnętrznych i źródeł danych. Łącząc się ze zdalnymi punktami końcowymi serwera MCP, agenci mogą uzyskiwać dostęp do narzędzi hostowanych przez deweloperów i organizacje, których mogą używać klienci zgodni z programem MCP, tacy jak Foundry Agent Service.

MCP to otwarty standard, który definiuje sposób, w jaki aplikacje zapewniają narzędzia i dane kontekstowe do dużych modeli językowych (LLMs). Umożliwia spójną, skalowalną integrację narzędzi zewnętrznych z przepływami pracy modelu.

W tym artykule dowiesz się, jak:

• Dodaj zdalny serwer MCP jako narzędzie.
• Uwierzytelnij się do serwera MCP przy użyciu połączenia projektu.
• Przejrzyj i zatwierdź wywołania narzędzia MCP.
• Rozwiązywanie typowych problemów z integracją z programem MCP.

Aby uzyskać szczegółowe informacje na temat sposobu działania integracji z programem MCP, zobacz Jak to działa.

Wsparcie użytkowania

W poniższej tabeli przedstawiono zestaw SDK i obsługę konfiguracji połączeń MCP. ✔️ (GA) wskazuje ogólną dostępność, ✔️ (wersja zapoznawcza) wskazuje publiczną wersję zapoznawcza, a kreska (-) wskazuje, że funkcja nie jest dostępna.

Pomoc techniczna firmy Microsoft Foundry	Zestaw SDK dla języka Python	Zestaw SDK języka C#	Zestaw SDK dla języka JavaScript	Java SDK	interfejs API REST	Konfiguracja agenta podstawowego	Konfiguracja agenta standardowego
✔️	✔️ (Podgląd)	✔️ (Podgląd)	✔️ (Podgląd)	-	✔️ (GA - ogólna dostępność)	✔️	✔️

Uwaga / Notatka

Zestaw JAVA SDK nie obsługuje obecnie narzędzi MCP przy użyciu nowych interfejsów API agenta (azure-ai-projects pakiet). Integracja z programem MCP jest dostępna tylko za pośrednictwem języka Python, C#, TypeScript i interfejsu API REST.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz:

• Subskrypcja platformy Azure z aktywnym projektem Microsoft Foundry.
• Kontrola dostępu oparta na rolach (RBAC) platformy Azure: rola współautora lub właściciela w projekcie Foundry.
• Najnowszy pakiet zestawu SDK wersji wstępnej dla danego języka. Szczegółowe informacje dotyczące instalacji można znaleźć w przewodniku Szybki start .
• Poświadczenia platformy Azure skonfigurowane do uwierzytelniania (na przykład DefaultAzureCredential).
• Skonfigurowane zmienne środowiskowe:
  • FOUNDRY_PROJECT_ENDPOINT: adres URL punktu końcowego projektu.
  • FOUNDRY_MODEL_DEPLOYMENT_NAME: Nazwa wdrożenia modelu.
  • MCP_PROJECT_CONNECTION_NAME: Nazwa połączenia projektu MCP.
• Dostęp do zdalnego punktu końcowego serwera MCP (na przykład serwera MCP usługi GitHub pod adresem https://api.githubcopilot.com/mcp).

Authentication

Wiele serwerów MCP wymaga uwierzytelniania.

W usłudze Foundry Agent Service użyj połączenia projektu, aby przechowywać szczegóły uwierzytelniania (na przykład klucze API lub tokeny nośnika) zamiast twardego kodowania poświadczeń w aplikacji.

Aby dowiedzieć się więcej o obsługiwanych opcjach uwierzytelniania (opartych na kluczach, tożsamościach firmy Microsoft i przekazywaniu tożsamości OAuth), zobacz Uwierzytelnianie serwera MCP.

Uwaga / Notatka

Ustaw project_connection_id jako identyfikator połączenia projektu.

Zagadnienia dotyczące korzystania z usług i serwerów firm innych niż Microsoft

Użytkownik podlega warunkom między Tobą a dostawcą usług, gdy korzystasz z połączonych usług innych niż Microsoft. Po nawiązaniu połączenia z usługą niepochodzącą od Microsoft, przekażesz niektóre dane (takie jak zawartość monitu) do tej usługi, albo twoja aplikacja może odbierać dane z takiej usługi. Ponosisz odpowiedzialność za korzystanie z usług i danych firm innych niż Microsoft wraz z wszelkimi opłatami skojarzonymi z tym użyciem.

Inne firmy, a nie firma Microsoft, tworzą zdalne serwery MCP, których decydujesz się używać z narzędziem MCP opisanym w tym artykule. Firma Microsoft nie testuje ani nie weryfikuje tych serwerów. Firma Microsoft nie ponosi odpowiedzialności wobec Ciebie lub innych w związku z Twoim korzystaniem z jakichkolwiek zdalnych serwerów MCP.

Uważnie przejrzyj i śledź, jakie serwery MCP dodajesz do usługi Foundry Agent Service. Polegaj na serwerach hostowanych przez zaufanych dostawców usług zamiast serwerów proxy.

Narzędzie MCP umożliwia przekazywanie niestandardowych nagłówków, takich jak klucze uwierzytelniania lub schematy, których może potrzebować zdalny serwer MCP. Przejrzyj wszystkie dane udostępniane zdalnym serwerom MCP i zarejestruj dane na potrzeby inspekcji. Należy pamiętać o praktykach firmy innych niż Microsoft dotyczących przechowywania i lokalizacji danych.

Najlepsze rozwiązania

Aby uzyskać ogólne wskazówki dotyczące użycia narzędzi, zobacz Najlepsze rozwiązania dotyczące używania narzędzi w usłudze Microsoft Foundry Agent.

W przypadku korzystania z serwerów MCP należy postępować zgodnie z następującymi rozwiązaniami:

• Preferuj listę dozwolonych narzędzi przy użyciu polecenia allowed_tools.
• Wymagaj zatwierdzenia operacji wysokiego ryzyka (zwłaszcza narzędzi, które zapisują dane lub zmieniają zasoby).
• Przed zatwierdzeniem przejrzyj żądaną nazwę i argumenty narzędzia.
• Rejestrowanie zatwierdzeń i wywołania narzędzi do audytu i rozwiązywania problemów.

Tworzenie agenta w języku Python za pomocą narzędzia MCP

Użyj poniższego przykładu kodu, aby utworzyć agenta i wywołać funkcję. Potrzebujesz najnowszego pakietu wersji wstępnej. Aby uzyskać szczegółowe informacje, zobacz przewodnik Szybki start .

Szybka weryfikacja

Przed uruchomieniem pełnego przykładu sprawdź połączenie projektu (opcjonalnie dla uwierzytelnionych serwerów MCP):

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], credential=credential) as project_client,
):
    print("Connected to project.")

    # Verify MCP connection exists (optional - only needed for authenticated servers)
    connection_name = os.environ.get("MCP_PROJECT_CONNECTION_NAME")
    if connection_name:
        try:
            conn = project_client.connections.get(connection_name)
            print(f"MCP connection verified: {conn.name}")
        except Exception as e:
            print(f"MCP connection '{connection_name}' not found: {e}")
    else:
        print("MCP_PROJECT_CONNECTION_NAME not set (optional for unauthenticated servers).")
        print("Available connections:")
        for conn in project_client.connections.list():
            print(f"  - {conn.name}")

Jeśli ten kod działa bez błędów, poświadczenia są poprawnie skonfigurowane. W przypadku uwierzytelnionych serwerów MCP upewnij się, że połączenie istnieje.

Pełny przykład

W poniższym przykładzie pokazano, jak używać serwera MCP w usłudze GitHub jako narzędzia dla agenta.

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

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):

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

    # Create a prompt agent with MCP tool capabilities
    agent = project_client.agents.create_version(
        agent_name="MyAgent7",
        definition=PromptAgentDefinition(
            model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
            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_client.conversations.create()
    print(f"Created conversation (id: {conversation.id})")

    # Send initial request that will trigger the MCP tool
    response = openai_client.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,
                )
            )

    print("Final input:")
    print(input_list)

    # 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
    response = openai_client.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
    # This prevents accumulation of unused agent versions in your project
    project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
    print("Agent deleted")

Oczekiwane dane wyjściowe

W poniższym przykładzie pokazano oczekiwane dane wyjściowe po uruchomieniu przykładu:

Agent created (id: <agent-id>, name: MyAgent7, version: 1)
Created conversation (id: <conversation-id>)
Final input:
[McpApprovalResponse(type='mcp_approval_response', approve=True, approval_request_id='<approval-request-id>')]
Response: Your GitHub username is "example-username".
Agent deleted

Tworzenie agenta za pomocą narzędzia MCP

W poniższym przykładzie pokazano, jak używać serwera MCP w usłudze GitHub jako narzędzia dla agenta. W przykładzie użyto metod synchronicznych do utworzenia agenta. Aby uzyskać metody asynchroniczne, zobacz przykładowy kod w repozytorium zestawu Azure SDK dla platformy .NET w witrynie GitHub.

// Create project client and read the environment variables that are used in the next steps.
var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
var modelDeploymentName = System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
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.
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
{
    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.Agents.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.OpenAI.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.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Oczekiwane dane wyjściowe

W poniższym przykładzie pokazano oczekiwane dane wyjściowe po uruchomieniu przykładu:

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.

Tworzenie agenta za pomocą narzędzia MCP przy użyciu uwierzytelniania połączenia projektu

Szybka weryfikacja

Przed uruchomieniem pełnego przykładu sprawdź połączenie projektu (opcjonalnie dla uwierzytelnionych serwerów MCP):

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

var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
var mcpConnectionName = System.Environment.GetEnvironmentVariable("MCP_PROJECT_CONNECTION_NAME");

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

Console.WriteLine("Connected to project.");

// Verify MCP connection exists (optional - only needed for authenticated servers)
if (!string.IsNullOrEmpty(mcpConnectionName))
{
    try
    {
        AIProjectConnection conn = projectClient.Connections.GetConnection(connectionName: mcpConnectionName);
        Console.WriteLine($"MCP connection verified: {conn.Name}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"MCP connection '{mcpConnectionName}' not found: {ex.Message}");
    }
}
else
{
    Console.WriteLine("MCP_PROJECT_CONNECTION_NAME not set (optional for unauthenticated servers).");
    Console.WriteLine("Available connections:");
    foreach (var conn in projectClient.Connections.GetConnections())
    {
        Console.WriteLine($"  - {conn.Name}");
    }
}

Jeśli ten kod działa bez błędów, poświadczenia są poprawnie skonfigurowane. W przypadku uwierzytelnionych serwerów MCP upewnij się, że połączenie istnieje.

Pełny przykład

W tym przykładzie dowiesz się, jak uwierzytelniać się na serwerze MCP usługi GitHub i używać go jako narzędzia dla agenta. W przykładzie użyto metod synchronicznych do utworzenia agenta. Aby uzyskać metody asynchroniczne, zobacz przykładowy kod w repozytorium zestawu Azure SDK dla platformy .NET w witrynie GitHub.

Konfigurowanie połączenia projektu

Przed uruchomieniem przykładu:

1. Zaloguj się do profilu usługi GitHub.
2. Wybierz obraz profilu w prawym górnym rogu.
3. Wybierz Ustawienia.
4. W panelu po lewej stronie wybierz pozycję Ustawienia dewelopera i Osobiste tokeny dostępu Tokeny > (wersja klasyczna).
5. W górnej części wybierz pozycję Generuj nowy token, wprowadź hasło i utwórz token, który może odczytywać repozytoria publiczne.
   • Ważne: Zapisz token lub pozostaw stronę otwartą tak, jak po zamknięciu strony nie można wyświetlić tokenu ponownie.
6. W witrynie Azure Portal otwórz aplikację Microsoft Foundry.
7. W panelu po lewej stronie wybierz pozycję Centrum zarządzania , a następnie wybierz pozycję Połączone zasoby.
8. Utwórz nowe połączenie typu Klucze niestandardowe.
9. Nadaj mu nazwę i dodaj parę wartości klucza.
10. Ustaw nazwę klucza na Authorization , a wartość powinna mieć postać Bearer your_github_token.

Przykładowy kod umożliwiający utworzenie agenta

// Create project client and read the environment variables to be used in the next steps.
var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
var modelDeploymentName = System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
var mcpConnectionName = System.Environment.GetEnvironmentVariable("MCP_PROJECT_CONNECTION_NAME");
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;
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
{
    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.Agents.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.OpenAI.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.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Oczekiwane dane wyjściowe

W poniższym przykładzie pokazano oczekiwane dane wyjściowe po uruchomieniu przykładu:

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

Tworzenie agenta w języku TypeScript za pomocą narzędzia MCP

W poniższym przykładzie języka TypeScript pokazano, jak utworzyć agenta z funkcjami narzędzi MCP, wysyłać żądania wyzwalające przepływy pracy zatwierdzania MCP, obsługiwać żądania zatwierdzenia i czyścić zasoby. Aby zapoznać się z wersją języka JavaScript, zobacz przykładowy kod w repozytorium zestawu Azure SDK dla języka JavaScript w witrynie GitHub.

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

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["FOUNDRY_MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";

export async function main(): Promise<void> {
  // Create AI Project client
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = await 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: deploymentName,
    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 openAIClient.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 openAIClient.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 openAIClient.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 openAIClient.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);
});

Oczekiwane dane wyjściowe

W poniższym przykładzie pokazano oczekiwane dane wyjściowe po uruchomieniu przykładu:

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!

Tworzenie agenta za pomocą narzędzia MCP przy użyciu uwierzytelniania połączenia projektu

Szybka weryfikacja

Przed uruchomieniem pełnego przykładu sprawdź połączenie projektu (opcjonalnie dla uwierzytelnionych serwerów MCP):

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

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const mcpConnectionName = process.env["MCP_PROJECT_CONNECTION_NAME"] || "";

async function verifyConnection(): Promise<void> {
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  console.log("Connected to project.");

  // Verify MCP connection exists (optional - only needed for authenticated servers)
  if (mcpConnectionName) {
    try {
      const conn = await project.connections.get(mcpConnectionName);
      console.log(`MCP connection verified: ${conn.name}`);
    } catch (error) {
      console.log(`MCP connection '${mcpConnectionName}' not found: ${error}`);
    }
  } else {
    console.log("MCP_PROJECT_CONNECTION_NAME not set (optional for unauthenticated servers).");
    console.log("Available connections:");
    for await (const conn of project.connections.list()) {
      console.log(`  - ${conn.name}`);
    }
  }
}

verifyConnection().catch(console.error);

Jeśli ten kod działa bez błędów, poświadczenia są poprawnie skonfigurowane. W przypadku uwierzytelnionych serwerów MCP upewnij się, że połączenie istnieje.

Pełny przykład

W poniższym przykładzie języka TypeScript pokazano, jak utworzyć agenta z funkcjami narzędzi MCP przy użyciu uwierzytelniania połączenia projektu, wysyłać żądania wyzwalające przepływy pracy zatwierdzania MCP, obsługiwać żądania zatwierdzenia i czyścić zasoby. Aby zapoznać się z wersją języka JavaScript, zobacz przykładowy kod w repozytorium zestawu Azure SDK dla języka JavaScript w witrynie GitHub.

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

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["FOUNDRY_MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";
const mcpConnectionName = process.env["MCP_PROJECT_CONNECTION_NAME"] || "";

export async function main(): Promise<void> {
  // Create AI Project client
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = await 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: deploymentName,
    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: mcpConnectionName,
      },
    ],
  });
  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 openAIClient.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 openAIClient.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 openAIClient.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 openAIClient.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);
});

Oczekiwane dane wyjściowe

W poniższym przykładzie pokazano oczekiwane dane wyjściowe po uruchomieniu przykładu:

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!

Używanie narzędzia MCP z interfejsem API REST

W poniższych przykładach pokazano, jak utworzyć agenta za pomocą narzędzia MCP i wywołać go przy użyciu interfejsu API odpowiedzi. Jeśli odpowiedź zawiera element wyjściowy z type ustawionym na mcp_approval_request, wyślij kolejne żądanie zawierające element mcp_approval_response.

Wymagania wstępne

Ustaw następujące zmienne środowiskowe:

• FOUNDRY_PROJECT_ENDPOINT: adres URL punktu końcowego projektu.
• AGENT_TOKEN: token elementu nośnego dla rozwiązania Foundry.
• MCP_PROJECT_CONNECTION_NAME (opcjonalnie): Nazwa połączenia projektu MCP.

Uzyskiwanie tokenu dostępu:

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

Jeśli serwer MCP nie wymaga uwierzytelniania, pomiń project_connection_id w treści żądania.

Uwaga / Notatka

W przypadku interfejsu API REST należy najpierw pobrać identyfikator połączenia z nazwy połączenia przy użyciu interfejsu API połączeń, a następnie przekazać identyfikator do konfiguracji narzędzia MCP.

Wskazówka

Aby uzyskać szczegółowe informacje na temat schematu i elementów zatwierdzania narzędzia MCP, zobacz OpenAI.MCPTool i typy elementów zatwierdzania MCP w dokumentacji REST.

1. Tworzenie 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": "<MODEL_DEPLOYMENT>",
      "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"
        }
      ]
    }
  }'

Aby użyć uwierzytelnionego serwera MCP z połączeniem projektu, dodaj "project_connection_id": "'$MCP_PROJECT_CONNECTION_NAME'" do definicji narzędzia i zmień server_url na uwierzytelniony punkt końcowy serwera (na przykład https://api.githubcopilot.com/mcp).

2. Tworzenie odpowiedzi

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

Jeśli odpowiedź zawiera element wyjściowy z ustawioną type wartością mcp_approval_request, skopiuj element id żądania zatwierdzenia jako APPROVAL_REQUEST_ID. Skopiuj również odpowiedź id najwyższego poziomu jako PREVIOUS_RESPONSE_ID.

3. Wyślij odpowiedź na zatwierdzenie

Jeśli narzędzie MCP wymaga zatwierdzenia, wyślij żądanie kontynuacji:

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. Czyszczenie zasobów

Usuń agenta:

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

Jak to działa

Należy przenieść zdalny serwer MCP (istniejący punkt końcowy serwera MCP) do usługi Foundry Agent Service. Możesz przenieść wiele zdalnych serwerów MCP, dodając je jako narzędzia. Dla każdego narzędzia należy podać unikatową wartość server_label w obrębie tego samego agenta oraz wartość server_url wskazującą na zdalny serwer MCP. Pamiętaj, aby dokładnie sprawdzić, które serwery MCP dodajesz do agenta usługi Foundry.

Aby uzyskać więcej informacji na temat korzystania z programu MCP, zobacz:

• Najlepsze rozwiązania w zakresie zabezpieczeń w witrynie internetowej protokołu kontekstowego modelu.
• Zrozumienie i ograniczenie ryzyka zabezpieczeń w implementacjach mcP w blogu Społeczności zabezpieczeń firmy Microsoft.

Konfigurowanie połączenia MCP

W poniższych krokach opisano sposób nawiązywania połączenia z zdalnym serwerem MCP z poziomu usługi agenta foundry:

1. Znajdź zdalny serwer MCP, z którym chcesz nawiązać połączenie, na przykład z serwerem MCP usługi GitHub. Utwórz lub zaktualizuj agenta usługi Foundry przy użyciu narzędzia mcp, korzystając z następujących informacji:
   1. server_url: adres URL serwera MCP, taki jak https://api.githubcopilot.com/mcp/.
   2. server_label: unikatowy identyfikator tego serwera MCP dla agenta, na przykład github.
   3. allowed_tools: opcjonalna lista narzędzi, do których ten agent może uzyskiwać dostęp i używać. Jeśli nie podasz tej wartości, wartość domyślna zawiera wszystkie narzędzia na serwerze MCP.
   4. require_approval: Opcjonalnie określ, czy wymagane jest zatwierdzenie. Domyślna wartość to always. Obsługiwane wartości to:
      • always: Deweloper musi zatwierdzić każde wywołanie. Jeśli nie podasz wartości, jest to wartość domyślna.
      • never: Nie jest wymagane zatwierdzenie.
      • {"never":[<tool_name_1>, <tool_name_2>]}: Udostępniasz listę narzędzi, które nie wymagają zatwierdzenia.
      • {"always":[<tool_name_1>, <tool_name_2>]}: Udostępniasz listę narzędzi, które wymagają zatwierdzenia.
2. project_connection_id: identyfikator połączenia projektu, który przechowuje uwierzytelnianie i inne szczegóły połączenia dla serwera MCP.
3. Jeśli model próbuje wywołać narzędzie na serwerze MCP z wymogiem zatwierdzenia, otrzymasz jako typ elementu wyjściowego odpowiedzi mcp_approval_request. W elemencie danych wyjściowych odpowiedzi można uzyskać więcej szczegółów na temat wywoływanego narzędzia na serwerze MCP i przekazywanych argumentów. Przejrzyj narzędzie i argumenty, aby można było podjąć świadomą decyzję o zatwierdzeniu.
4. Prześlij zatwierdzenie do agenta przy użyciu polecenia response_id i ustawieniu approve na true.

Znane ograniczenia

• Wywołania narzędzia MCP bez przesyłania strumieniowego mają limit czasu 100 sekund. Jeśli serwer MCP odpowiada dłużej niż 100 sekund, wywołanie nie powiedzie się. Aby uniknąć przekroczenia limitu czasu, upewnij się, że serwer MCP odpowiada w ramach tego limitu. Jeśli przypadek użycia wymaga dłuższego czasu przetwarzania, rozważ optymalizację logiki po stronie serwera lub podzielenie operacji na mniejsze kroki.
• Przekazywanie tożsamości nie jest obsługiwane w aplikacji Teams: narzędzia MCP korzystające z przekazywania tożsamości OAuth nie działają, gdy agent jest publikowany w usłudze Microsoft Teams. Agenci opublikowani w usłudze Teams używają tożsamości zarządzanej projektu do uwierzytelniania, która nie jest zgodna z przekazywaniem tożsamości (on-Behalf-Of).

Typowe pytania i błędy

Poniżej przedstawiono typowe problemy, które mogą wystąpić podczas korzystania z narzędzi MCP z Foundry Agent Service:

• "Nieprawidłowy schemat narzędzia":

  Nieprawidłowy schemat narzędzia zazwyczaj występuje, gdy w definicji serwera MCP masz anyOf lub allOf, albo gdy parametr może przyjmować wiele typów wartości. Zaktualizuj definicję serwera MCP i spróbuj ponownie.

• "Brak autoryzacji" lub "Zabronione" z serwera MCP:

  Upewnij się, że serwer MCP obsługuje metodę uwierzytelniania i sprawdź poświadczenia przechowywane w połączeniu projektu. W przypadku usługi GitHub używaj tokenów z najmniejszymi uprawnieniami i regularnie je obracaj.

• Model nigdy nie wywołuje narzędzia MCP:

  Upewnij się, że instrukcje agenta zachęcają do użycia narzędzi oraz weryfikacji wartości server_label, server_url i allowed_tools. Jeśli ustawisz wartość allowed_tools, upewnij się, że nazwa narzędzia jest zgodna z tym, co uwidacznia serwer MCP.

• Agent nigdy nie kontynuuje działania po zatwierdzeniu.

  Potwierdź, że wysyłasz żądanie uzupełniające z ustawionym previous_response_id na oryginalny identyfikator odpowiedzi, i że używasz identyfikatora elementu żądania zatwierdzenia jako approval_request_id.

Hostowanie lokalnego serwera MCP

Środowisko uruchomieniowe usługi agenta akceptuje tylko zdalny punkt końcowy serwera MCP. Jeśli chcesz dodać narzędzia z lokalnego serwera MCP, musisz samodzielnie hostować je w usłudze Azure Container Apps lub Azure Functions , aby uzyskać zdalny punkt końcowy serwera MCP. Podczas hostowania lokalnych serwerów MCP w chmurze należy wziąć pod uwagę następujące czynniki:

Konfiguracja lokalnego serwera MCP	Hosting w usłudze Azure Container Apps	Hosting w usłudze Azure Functions
Transport	Wymagane punkty końcowe HTTP POST/GET.	Wymagana jest możliwość transmitowania HTTP.
Zmiany kodu	Wymagane jest odtworzenie kontenera.	Pliki konfiguracji specyficzne dla usługi Azure Functions wymagane w katalogu głównym.
Uwierzytelnianie	Wymagana jest implementacja uwierzytelniania niestandardowego.	Tylko oparte na kluczach. Protokół OAuth wymaga usługi API Management.
Język	Dowolny język uruchamiany w kontenerach systemu Linux (Python, Node.js, .NET, TypeScript, Go).	Tylko język Python, Node.js, Java, .NET.
Wymagania dotyczące kontenera	Linux (tylko linux/amd64). Brak uprzywilejowanych kontenerów.	Serwery konteneryzowane nie są obsługiwane.
Zależności	Wszystkie zależności muszą znajdować się w obrazie kontenera.	Zależności na poziomie systemu operacyjnego (takie jak Playwright) nie są obsługiwane.
Stan	Tylko bezstanowe.	Tylko bezstanowe.
UVX/NPX	Supported.	Niewspierane. npx polecenia uruchamiania nie są obsługiwane.

Treści powiązane

• Rozpoczynanie pracy z agentami przy użyciu kodu
• Uwierzytelnianie serwera MCP
• Tworzenie i rejestrowanie serwera protokołu MCP (Model Context Protocol)
• Dokumentacja REST narzędzia MCP
• Najlepsze rozwiązania w zakresie zabezpieczeń dla mcp
• Zrozumienie i ograniczenie ryzyka zabezpieczeń w implementacjach mcp